# Getting Started
Source: https://docs.stackone.com/agents/guides/getting-started

Learn how to leverage StackOne integrations in your AI agent with StackOne

This comprehensive guide will help you get started with StackOne's AI tools, covering installation, basic usage, tool filtering, and advanced features.

## Installation

<CodeGroup>
  ```bash Typescript
  # Using npm
  npm install @stackone/ai

  # Using pnpm
  pnpm add @stackone/ai

  # Using bun
  bun add @stackone/ai
  ```

  ```bash Python
  # Using pip
  pip install stackone-ai

  # Using poetry
  poetry add stackone-ai

  # Using uv
  uv add stackone-ai
  ```
</CodeGroup>

## Authentication Setup

Configure authentication using one of these methods:

### Using a .env File

```env
STACKONE_API_KEY=<your-api-key>
```

Load it in your code:

<CodeGroup>
  ```typescript TypeScript
  import * as dotenv from 'dotenv';
  dotenv.config();
  ```

  ```python Python
  from dotenv import load_dotenv
  load_dotenv()
  ```
</CodeGroup>

### Initializing Toolset

<CodeGroup>
  ```typescript TypeScript
  import { StackOneToolSet } from '@stackone/ai';
  const toolset = new StackOneToolSet();
  ```

  ```python Python
  from stackone import StackOneToolSet
  toolset = StackOneToolSet()
  ```
</CodeGroup>

### Using the ToolSet

Here's a complete example showing how to use filtered tools:

<CodeGroup>
  ```typescript TypeScript
  async function manageEmployees() {
    const tools = toolset.getStackOneTools(['hris_*'], accountId);

    try {
      // List employees
      const employees = await tools.getTool('hris_list_employees')
        .execute();

      // Get specific employee
      const employee = await tools.getTool('hris_get_employee')
        .execute({ employeeId: '123' });

      // Create new employee
      const newEmployee = await tools.getTool('hris_create_employee')
        .execute({
          firstName: 'John',
          lastName: 'Doe',
          email: 'john@example.com'
        });

      console.log('Operations completed:', {
        totalEmployees: employees.length,
        specificEmployee: employee,
        newEmployee
      });
    } catch (error) {
      console.error('Error:', error);
    }
  }
  ```

  ```python Python
  async def manage_employees():
      tools = toolset.get_stackone_tools(['hris_*'], account_id=account_id)

      try:
          # List employees
          employees = await tools.get_tool('hris_list_employees').execute()

          # Get specific employee
          employee = await tools.get_tool('hris_get_employee').execute(
              employee_id='123'
          )

          # Create new employee
          new_employee = await tools.get_tool('hris_create_employee').execute(
              first_name='John',
              last_name='Doe',
              email='john@example.com'
          )

          print('Operations completed:', {
              'total_employees': len(employees),
              'specific_employee': employee,
              'new_employee': new_employee
          })
      except Exception as error:
          print('Error:', error)
  ```
</CodeGroup>

## AI Framework Integration

### OpenAI Functions

<CodeGroup>
  ```typescript TypeScript
  import { OpenAI } from 'openai';

  const openai = new OpenAI();
  const tools = toolset.getStackOneTools(['hris_*'], accountId);
  const openAITools = tools.toOpenAI();

  const completion = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'List all employees' }],
    tools: openAITools
  });

  if (completion.choices[0].message.tool_calls) {
    const toolCall = completion.choices[0].message.tool_calls[0];
    const result = await tools.execute(toolCall.function.arguments);
    console.log('Function result:', result);
  }
  ```

  ```python Python
  from openai import OpenAI

  client = OpenAI()

  tools = toolset.get_stackone_tools(["hris_*"], account_id=account_id)
  openai_tools = tools.to_openai()

  completion = await client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "List all employees"}],
      tools=openai_tools
  )

  if completion.choices[0].message.tool_calls:
      tool_call = completion.choices[0].message.tool_calls[0]
      result = await tools.execute(tool_call.function.arguments)
      print('Function result:', result)
  ```
</CodeGroup>

### AI SDK by Vercel

```typescript Typescript

const toolset = new StackOneToolSet();
const tools = toolset.getStackOneTools(['hris_*'], accountId);
const aiSdkTools = tools.toAISDK();

const { text } = await generateText({
  model: openai('gpt-4o'),
  tools: aiSdkTools,
  prompt: 'Find all employees in the engineering department',
  maxSteps: 3,
});
```

### LangChain Integration

```python Python
from langchain_openai import ChatOpenAI

toolset = StackOneToolSet()
tools = toolset.get_tools(["hris_*"], account_id=account_id)
langchainTools = tools.to_langchain();

# Create model with tools
model = ChatOpenAI(model="gpt-4o-mini")
model_with_tools = model.bind_tools(langchain_tools)

result = model_with_tools.invoke(f"Find all employees in the engineering department")
```


# OpenAPI Tools
Source: https://docs.stackone.com/agents/guides/openapi-tools

Use Open API specs as tools via the StackOne (typescript) AI SDK

This guide explains how to work with OpenAPI-generated tools via the StackOne (typescript) AI SDK.

## OpenAPIToolSet

The OpenAPIToolSet class allows you to parse OpenAPI specifications as tools from either a local file or a remote URL.

### Loading from a File

```typescript
import { OpenAPIToolSet } from "@stackone/ai";
import path from "node:path";

// Create the toolset
const toolset = new OpenAPIToolSet({
  filePath: path.join(__dirname, "path/to/openapi-spec.json");
});

// Get all tools
const allTools = toolset.getTools();

// Get filtered tools
const filteredTools = toolset.getTools("user_*");
```

### Loading from a URL

```typescript
import { OpenAPIToolSet } from "@stackone/ai";

// Create the toolset using the factory method
const toolset = await OpenAPIToolSet.fromUrl({
  url: "https://example.com/path/to/openapi-spec.json",
});
```

### Authentication Options

The OpenAPIToolSet supports easy usage of bot Basic and Bearer authentication:

```typescript
// Basic Authentication
const toolsetWithBasicAuth = new OpenAPIToolSet({
  filePath: "path/to/spec.json",
  authentication: {
    type: "basic",
    credentials: {
      username: "user",
      password: "pass",
    },
  },
});

// Bearer Authentication
const toolsetWithBearerAuth = await OpenAPIToolSet.fromUrl({
  url: "https://example.com/spec.json",
  authentication: {
    type: "bearer",
    credentials: {
      token: "your-bearer-token",
    },
  },
});
```

You can also directly write to the toolset headers:

```typescript
const toolsetWithHeaders = new OpenAPIToolSet({
  filePath: "path/to/spec.json",
  headers: {
    Authorization: "Bearer your-bearer-token",
  },
});
```


# Tool Filtering
Source: https://docs.stackone.com/agents/guides/tool-filtering

Filter tools when using the StackOne AI SDK

The StackOne SDK provides glob-based filtering capabilities to help you select and manage specific tools across different SaaS platforms.

## Overview

Tool filtering allows you to:

* Select tools by category (HRIS, ATS, etc.)
* Filter by specific actions (create, read, update, delete)
* Combine multiple patterns for precise selection
* Exclude specific tools or patterns

## Basic Filtering Patterns

```typescript
import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();

// Get all HRIS tools
const hrisTools = toolset.getTools('hris_*');
// Get all ATS tools etc.
const atsTools = toolset.getStackOneTools('ats_*');

// Get all create operations
const createTools = toolset.getStackOneTools('*_create_*');

// Get all HRIS create operations
const hrisCreateTools = toolset.getStackOneTools('hris_create_*');
```

## Advanced Filtering

### 1. Multiple Patterns

```typescript
// Get both HRIS and ATS tools
const tools = toolset.getStackOneTools(['hris_*', 'ats_*']);

// Get specific operations across categories
const specificTools = toolset.getStackOneTools([
  'hris_create_employee',
  'ats_update_candidate',
  'crm_get_contact'
]);
```

## Tool Categories

Common tool categories and their patterns:

```typescript
const TOOL_CATEGORIES = {
  // HRIS Tools
  hris: {
    all: 'hris_*',
    employee: 'hris_*_employee*',
    document: 'hris_*_document*',
    payroll: 'hris_*_payroll*'
  },

  // ATS Tools
  ats: {
    all: 'ats_*',
    candidate: 'ats_*_candidate*',
    job: 'ats_*_job*',
    application: 'ats_*_application*'
  },

  // CRM Tools
  crm: {
    all: 'crm_*',
    contact: 'crm_*_contact*',
    deal: 'crm_*_deal*',
    company: 'crm_*_company*'
  }
};
```

## Best Practices

1. **Be Specific**: Use the most specific patterns that meet your needs
2. **Use Exclusions**: Exclude patterns for better precision
3. **Group Related Tools**: Use category-based filtering for related operations


# Overview
Source: https://docs.stackone.com/agents/introduction

Build AI agents with StackOne

StackOne Agent Tools provide a powerful way to build AI agents that can interact with various business systems through our unified APIs. This guide will help you understand our agent toolsets and choose the right SDK for your AI applications.

## Why StackOne for AI Agents?

StackOne simplifies building B2B SaaS agents by providing:

1. **Unified API Access** - Standardized interfaces across different SaaS providers
2. **AI-First Design** - Tools designed specifically for AI agent development
3. **Multi-Tenant Support** - Built-in handling of customer accounts and permissions
4. **Standardized Data Models** - Consistent data structures across providers

## Architecture Overview

```mermaid
graph TB
    A[AI Agent] --> B[StackOne Tools]
    B --> C[StackOne Unified API]
    C --> D1[Customer A's HRIS]
    C --> D2[Customer B's ATS]
    C --> D3[Customer C's CRM]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px
    style C fill:#dfd,stroke:#333,stroke-width:2px
    style D1 fill:#fdd,stroke:#333,stroke-width:2px
    style D2 fill:#fdd,stroke:#333,stroke-width:2px
    style D3 fill:#fdd,stroke:#333,stroke-width:2px
```

The StackOne Agent Tools consist of three main components:

1. **Unified API** - Our standardized API layer that normalizes data across different providers
2. **Toolsets** - Language-specific SDKs that wrap the unified API into AI-friendly tools
3. **Dashboard & Accounts** - Central management of your integrations and API keys

## Choosing Your SDK

We provide SDKs for both TypeScript/JavaScript and Python. Here's how to choose:

### TypeScript/JavaScript SDK (`@stackone/ai`)

[Check it out on Github](https://github.com/StackOneHQ/stackone-ai-node)

✅ **Best for**:

* Web applications and Next.js projects
* OpenAI Functions integration
* Vercel AI SDK compatibility
* Projects requiring strong type safety
* Frontend-heavy applications

### Python SDK (`stackone-ai`)

[Check it out on Github](https://github.com/StackOneHQ/stackone-ai-python)

✅ **Best for**:

* Data science and ML projects
* LangChain applications
* Backend-heavy systems
* Scientific computing integration
* Jupyter notebook development

Both SDKs offer:

* Full type support
* AI framework integrations
* Automatic parameter handling
* Multi-tenant support

## Getting Started

To start building with StackOne Agent Tools:

1. Choose your SDK based on the considerations above
2. Install the package:
   ```bash
   # For TypeScript/JavaScript
   npm install @stackone/ai

   # For Python
   pip install stackone-ai
   ```
3. Configure your API key
4. Start building your agent

## Next Step

* [Getting started with the AI SDK](/agents/guides/getting-started)

<Note>
  Need help choosing? Contact our support team for personalized guidance on selecting the right SDK for your use case.
</Note>


# Create Application
Source: https://docs.stackone.com/ats/api-reference/applications/create-application

post /unified/ats/applications



# Download Application Document
Source: https://docs.stackone.com/ats/api-reference/applications/documents/download-application-document

get /unified/ats/applications/{id}/documents/{subResourceId}/download



# Get Application Document
Source: https://docs.stackone.com/ats/api-reference/applications/documents/get-application-document

get /unified/ats/applications/{id}/documents/{subResourceId}



# List Application Documents
Source: https://docs.stackone.com/ats/api-reference/applications/documents/list-application-documents

get /unified/ats/applications/{id}/documents



# Upload Application Document
Source: https://docs.stackone.com/ats/api-reference/applications/documents/upload-application-document

post /unified/ats/applications/{id}/documents/upload



# Get Application
Source: https://docs.stackone.com/ats/api-reference/applications/get-application

get /unified/ats/applications/{id}



# Get Application Scorecard
Source: https://docs.stackone.com/ats/api-reference/applications/get-application-scorecard

get /unified/ats/applications/{id}/scorecards/{subResourceId}



# List Applications
Source: https://docs.stackone.com/ats/api-reference/applications/list-applications

get /unified/ats/applications



# Move Application
Source: https://docs.stackone.com/ats/api-reference/applications/move-application

post /unified/ats/applications/{id}/move



# Create Application Note
Source: https://docs.stackone.com/ats/api-reference/applications/notes/create-application-note

post /unified/ats/applications/{id}/notes



# Get Application Note
Source: https://docs.stackone.com/ats/api-reference/applications/notes/get-application-note

get /unified/ats/applications/{id}/notes/{subResourceId}



# List Application Notes
Source: https://docs.stackone.com/ats/api-reference/applications/notes/list-application-notes

get /unified/ats/applications/{id}/notes



# Update an Application Note
Source: https://docs.stackone.com/ats/api-reference/applications/notes/update-an-application-note

patch /unified/ats/applications/{id}/notes/{subResourceId}



# Get Application Offer
Source: https://docs.stackone.com/ats/api-reference/applications/offers/get-application-offer

get /unified/ats/applications/{id}/offers/{subResourceId}



# List Application Offers
Source: https://docs.stackone.com/ats/api-reference/applications/offers/list-application-offers

get /unified/ats/applications/{id}/offers



# Reject Application
Source: https://docs.stackone.com/ats/api-reference/applications/reject-application

post /unified/ats/applications/{id}/reject



# Get Applications scheduled interview
Source: https://docs.stackone.com/ats/api-reference/applications/scheduled-interviews/get-applications-scheduled-interview

get /unified/ats/applications/{id}/scheduled_interviews/{subResourceId}



# List Applications scheduled interviews
Source: https://docs.stackone.com/ats/api-reference/applications/scheduled-interviews/list-applications-scheduled-interviews

get /unified/ats/applications/{id}/scheduled_interviews



# List Application Scorecards
Source: https://docs.stackone.com/ats/api-reference/applications/scorecards/list-application-scorecards

get /unified/ats/applications/{id}/scorecards



# Update an Application
Source: https://docs.stackone.com/ats/api-reference/applications/update-an-application

patch /unified/ats/applications/{id}



# Get Assessments Requests
Source: https://docs.stackone.com/ats/api-reference/assessments/orders/get-assessments-requests

get /unified/ats/assessments/orders/{id}



# Order Assessments Request
Source: https://docs.stackone.com/ats/api-reference/assessments/orders/order-assessments-request

post /unified/ats/assessments/orders



# Get Assessments Package
Source: https://docs.stackone.com/ats/api-reference/assessments/packages/get-assessments-package

get /unified/ats/assessments/packages/{id}



# List Assessments Packages
Source: https://docs.stackone.com/ats/api-reference/assessments/packages/list-assessments-packages

get /unified/ats/assessments/packages



# Get Assessments Results
Source: https://docs.stackone.com/ats/api-reference/assessments/results/get-assessments-results

get /unified/ats/assessments/orders/{id}/results



# Update Assessments Result
Source: https://docs.stackone.com/ats/api-reference/assessments/results/update-assessments-result

patch /unified/ats/assessments/orders/{id}/result



# Get Background Check Request
Source: https://docs.stackone.com/ats/api-reference/background-checks/orders/get-background-check-request

get /unified/ats/background_checks/orders/{id}



# List Background Check Request
Source: https://docs.stackone.com/ats/api-reference/background-checks/orders/list-background-check-request

get /unified/ats/background_checks/orders



# Order Background Check Request
Source: https://docs.stackone.com/ats/api-reference/background-checks/orders/order-background-check-request

post /unified/ats/background_checks/orders



# Create Background Check Package
Source: https://docs.stackone.com/ats/api-reference/background-checks/packages/create-background-check-package

post /unified/ats/background_checks/packages



# Delete Background Check Package
Source: https://docs.stackone.com/ats/api-reference/background-checks/packages/delete-background-check-package

delete /unified/ats/background_checks/packages/{id}



# Get Background Check Package
Source: https://docs.stackone.com/ats/api-reference/background-checks/packages/get-background-check-package

get /unified/ats/background_checks/packages/{id}



# List Background Check Packages
Source: https://docs.stackone.com/ats/api-reference/background-checks/packages/list-background-check-packages

get /unified/ats/background_checks/packages



# Update Background Check Package
Source: https://docs.stackone.com/ats/api-reference/background-checks/packages/update-background-check-package

patch /unified/ats/background_checks/packages/{id}



# Get Background Check Results
Source: https://docs.stackone.com/ats/api-reference/background-checks/results/get-background-check-results

get /unified/ats/background_checks/orders/{id}/results



# Update Background Check Result
Source: https://docs.stackone.com/ats/api-reference/background-checks/results/update-background-check-result

patch /unified/ats/background_checks/orders/{id}/result



# Create Candidate
Source: https://docs.stackone.com/ats/api-reference/candidates/create-candidate

post /unified/ats/candidates



# Get Candidate
Source: https://docs.stackone.com/ats/api-reference/candidates/get-candidate

get /unified/ats/candidates/{id}



# List Candidates
Source: https://docs.stackone.com/ats/api-reference/candidates/list-candidates

get /unified/ats/candidates



# Create Candidate Note
Source: https://docs.stackone.com/ats/api-reference/candidates/notes/create-candidate-note

post /unified/ats/candidates/{id}/notes



# Get Candidate Note
Source: https://docs.stackone.com/ats/api-reference/candidates/notes/get-candidate-note

get /unified/ats/candidates/{id}/notes/{subResourceId}



# List Candidate Notes
Source: https://docs.stackone.com/ats/api-reference/candidates/notes/list-candidate-notes

get /unified/ats/candidates/{id}/notes



# Update Candidate
Source: https://docs.stackone.com/ats/api-reference/candidates/update-candidate

patch /unified/ats/candidates/{id}



# Get Application Custom Field Definition
Source: https://docs.stackone.com/ats/api-reference/custom-field-definitions/get-application-custom-field-definition

get /unified/ats/custom_field_definitions/applications/{id}



# Get Candidate Custom Field Definition
Source: https://docs.stackone.com/ats/api-reference/custom-field-definitions/get-candidate-custom-field-definition

get /unified/ats/custom_field_definitions/candidates/{id}



# Get Job Custom Field Definition
Source: https://docs.stackone.com/ats/api-reference/custom-field-definitions/get-job-custom-field-definition

get /unified/ats/custom_field_definitions/jobs/{id}



# List Application Custom Field Definitions
Source: https://docs.stackone.com/ats/api-reference/custom-field-definitions/list-application-custom-field-definitions

get /unified/ats/custom_field_definitions/applications



# List Candidate Custom Field Definitions
Source: https://docs.stackone.com/ats/api-reference/custom-field-definitions/list-candidate-custom-field-definitions

get /unified/ats/custom_field_definitions/candidates



# List Job Custom Field Definitions
Source: https://docs.stackone.com/ats/api-reference/custom-field-definitions/list-job-custom-field-definitions

get /unified/ats/custom_field_definitions/jobs



# Get Department
Source: https://docs.stackone.com/ats/api-reference/departments/get-department

get /unified/ats/departments/{id}



# List Departments
Source: https://docs.stackone.com/ats/api-reference/departments/list-departments

get /unified/ats/departments



# Get Interview Stage
Source: https://docs.stackone.com/ats/api-reference/interview-stages/get-interview-stage

get /unified/ats/interview_stages/{id}



# List Interview Stages
Source: https://docs.stackone.com/ats/api-reference/interview-stages/list-interview-stages

get /unified/ats/interview_stages



# Get Interview
Source: https://docs.stackone.com/ats/api-reference/interviews/get-interview

get /unified/ats/interviews/{id}



# List Interviews
Source: https://docs.stackone.com/ats/api-reference/interviews/list-interviews

get /unified/ats/interviews



# Get Job Posting
Source: https://docs.stackone.com/ats/api-reference/job-postings/get-job-posting

get /unified/ats/job_postings/{id}



# List Job Postings
Source: https://docs.stackone.com/ats/api-reference/job-postings/list-job-postings

get /unified/ats/job_postings



# Create Job
Source: https://docs.stackone.com/ats/api-reference/jobs/create-job

post /unified/ats/jobs



# Get Job
Source: https://docs.stackone.com/ats/api-reference/jobs/get-job

get /unified/ats/jobs/{id}



# List Jobs
Source: https://docs.stackone.com/ats/api-reference/jobs/list-jobs

get /unified/ats/jobs



# Update Job
Source: https://docs.stackone.com/ats/api-reference/jobs/update-job

patch /unified/ats/jobs/{id}



# Get all Lists
Source: https://docs.stackone.com/ats/api-reference/lists/get-all-lists

get /unified/ats/lists



# Get List
Source: https://docs.stackone.com/ats/api-reference/lists/get-list

get /unified/ats/lists/{id}



# Get Location
Source: https://docs.stackone.com/ats/api-reference/locations/get-location

get /unified/ats/locations/{id}



# List locations
Source: https://docs.stackone.com/ats/api-reference/locations/list-locations

get /unified/ats/locations



# Creates an offer
Source: https://docs.stackone.com/ats/api-reference/offers/creates-an-offer

post /unified/ats/offers



# Get Offer
Source: https://docs.stackone.com/ats/api-reference/offers/get-offer

get /unified/ats/offers/{id}



# List Offers
Source: https://docs.stackone.com/ats/api-reference/offers/list-offers

get /unified/ats/offers



# Get Rejected Reason
Source: https://docs.stackone.com/ats/api-reference/rejected-reasons/get-rejected-reason

get /unified/ats/rejected_reasons/{id}



# List Rejected Reasons
Source: https://docs.stackone.com/ats/api-reference/rejected-reasons/list-rejected-reasons

get /unified/ats/rejected_reasons



# Get User
Source: https://docs.stackone.com/ats/api-reference/users/get-user

get /unified/ats/users/{id}



# List Users
Source: https://docs.stackone.com/ats/api-reference/users/list-users

get /unified/ats/users



# null
Source: https://docs.stackone.com/ats/common-guide/pagination



StackOne's <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip> allows paginating on API requests that return multiple records using a page cursor.

The following optional URL parameters are used for pagination:

<ParamField query="page_size" type="string" default="25">
  The number of records per page.
</ParamField>

<ParamField query="next" type="string">
  The `next` parameter is used to iterate through data pages.
</ParamField>

<Warning>
  It is recommended to keep the same page\_size throughout the sequence of pagination requests otherwise unexpected behaviour may occur.
</Warning>

## Sample URL

```
https://api.stackone.com/unified/hris/employees?page_size=25&next=eyJyIjphAsHHere
```

## Sample Response

In the response payload, you can find the `next` cursor. To get the next page of data send a new request with the `next` parameter set to this value.

```json
"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]
```

Once the cursor reaches the end of the data list, both values become NULL.

<Frame>
  ![Bypassed Records scenario](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/cd9e2c8-pagination_stripped.gif)
</Frame>

For further information see [Guides - Pagination](/guides/pagination)


# Overview
Source: https://docs.stackone.com/ats/introduction



A unified ATS API overcomes recruitment integration challenges by standardizing inconsistent data models, normalizing varied terminology, and creating a consistent entity structure where application statuses, interview stages, assessment results, and candidate fields exist predictably regardless of which vendor's system houses the underlying recruitment data.

## Benefits of the ATS API

Here are some benefits of using our ATS API that simplifies and enhances the recruitment process:

<AccordionGroup>
  <Accordion title="Sandbox Access for Seamless Testing">
    Developers can utilize sandbox environments to test integrations without affecting live data, ensuring a smooth deployment process.
  </Accordion>

  <Accordion title="Real-Time Data Synchronization">
    StackOne's APIs interfaces with the underlying systems in real-time, allowing for immediate updates and synchronization across platforms.
  </Accordion>

  <Accordion title="Privacy-First Design Ensuring Compliance">
    With a [focus on security](https://www.stackone.com/blog/why-your-choice-of-unified-api-could-make-or-break-compliance), StackOne's architecture avoids unnecessary data storage, maintaining compliance with data protection regulations.
  </Accordion>

  <Accordion title="Synthetic and Native Webhooks for Updates">
    The platform provides both [synthetic and native webhooks](/guides/webhooks), enabling real-time notifications for candidate and job posting changes.
  </Accordion>

  <Accordion title="Comprehensive ATS Integration Coverage">
    StackOne offers [out-of-the-box integration use-cases](https://www.stackone.com/integrations) with a wide range of ATS platforms, simplifying the integration process.
  </Accordion>
</AccordionGroup>

## Key Features

The table below shows key features of the ATS API that make recruitment easier, from real-time application tracking and offer Management:

| **Feature**                        | **Description**                                                                                                 |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Comprehensive Candidate Management | Easily create, update, and retrieve candidate profiles, including personal information and application history. |
| Job Postings and Metadata          | List and manage job postings, access detailed descriptions, compensation ranges, and related questionnaires.    |
| Application Tracking               | Monitor and update application statuses, manage interview stages, and handle offer details.                     |
| Real-Time Webhooks                 | Receive instant notifications for changes in data like - candidates, applications, or job postings.             |
| Document Handling                  | Upload, download, and manage candidate documents such as resumes and cover letters.                             |
| Interview Scheduling               | Record and manage interview details, including times, participants, and locations.                              |
| Offer Management                   | Handle job offers, track their status, and manage candidate responses efficiently.                              |

## Entity Model and Relationships

The following diagram illustrates the key entities within the ATS API:

```mermaid
erDiagram
    %% Main entities
    Application {
        string id
        string candidate_id
        string job_id
        string job_posting_id
        string interview_stage_id
        array location_ids
    }

    Candidate {
        string id
    }

    Job {
        string id
        array department_ids
        array location_ids
    }

    %% Interview process entities
    InterviewStage {
        string id
    }

    Interview {
        string id
        string application_id
        string interview_stage_id
    }

    Scorecard {
        string id
        string application_id
        string interview_id
        string candidate_id
        string author_id
    }

    %% Offer and rejection entities
    Offer {
        string id
        string application_id
    }

    RejectedReason {
        string id
    }

    %% Assessment entities
    AssessmentPackage {
        string id
    }

    AssessmentOrder {
        string id
        string application_id
        string candidate_id
    }

    BackgroundCheckPackage {
        string id
    }

    BackgroundCheckOrder {
        string id
        string application_id
        string candidate_id
    }

    %% Support entities
    Department {
        string id
    }

    Location {
        string id
    }

    JobPosting {
        string id
        string job_id
    }

    Note {
        string id
        string author_id
    }

    User {
        string id
    }

    List {
        string id
    }

    %% Core hiring flow
    Candidate ||--o{ Application : submits
    Job ||--o{ Application : receives
    JobPosting ||--o{ Application : attracts

    %% Interview process
    Job ||--o{ InterviewStage : defines
    Application ||--o{ Interview : schedules
    Interview }|--|| InterviewStage : follows
    Interview ||--o{ Scorecard : evaluated_by

    %% Outcome paths
    Application ||--o{ Offer : may_receive
    Application ||--o{ RejectedReason : may_have

    %% Assessments
    Application ||--o{ AssessmentOrder : undergoes
    AssessmentOrder }|--|| AssessmentPackage : uses
    Application ||--o{ BackgroundCheckOrder : undergoes
    BackgroundCheckOrder }|--|| BackgroundCheckPackage : uses

    %% Supporting relationships
    Job }|--o{ Department : belongs_to
    Job }|--o{ Location : based_in
    Job ||--o{ JobPosting : advertised_as
    Application }|--o{ Location : associated_with
    User ||--o{ Note : writes
    Application ||--o{ Note : has
    Candidate ||--o{ Note : has
```

The following table outlines key entities within the ATS system and provides a brief description of each:

| Entity                    | Description                                                                                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Applications              | Manages job applications, including creation date, status, linked job and candidate identifiers, and more.                                                         |
| Application Offers        | Handles job offers associated with applications, providing information on offer status, details, responses, and tracking from creation to acceptance or rejection. |
| Interviews                | Records details of candidate interviews, including times, participants, and location (e.g., meeting URL).                                                          |
| Interview Stages          | Represents different interview process stages, such as initial screening, technical rounds, and final interviews.                                                  |
| Rejected Reasons          | Manages standardized reasons for candidate application rejections, aiding in consistent decision-making and recruitment process analysis.                          |
| Candidates                | Provides detailed profiles of job candidates, including personal information, qualifications, application status, and history with the company.                    |
| Candidate Notes           | Manages notes related to specific candidates, including content (usually simple text strings) and author.                                                          |
| Users                     | Manages user accounts within the ATS, including recruiters, HR personnel, and hiring managers, with access to user details, roles, and permissions.                |
| Jobs                      | Manages job positions within the organization, including title, location, and status.                                                                              |
| Job Postings              | Focuses on the public aspect of the job, including extended descriptions, compensation ranges, and related questionnaires for applying.                            |
| Locations                 | Manages geographical locations associated with a job or job posting.                                                                                               |
| Departments               | Manages organizational departments that jobs are associated with.                                                                                                  |
| Scorecards                | Tracks evaluations and feedback from interviewers about candidates, including ratings and comments.                                                                |
| Lists                     | Manages custom lists that can be used to group candidates, jobs, or other entities.                                                                                |
| Assessment Packages       | Defines assessment tests that candidates can take during the hiring process.                                                                                       |
| Assessment Orders         | Records instances of assessments assigned to specific candidates.                                                                                                  |
| Background Check Packages | Defines background check processes that candidates may undergo.                                                                                                    |
| Background Check Orders   | Records instances of background checks performed on specific candidates.                                                                                           |
| Notes                     | Manages notes that can be associated with various entities like applications, candidates, etc.                                                                     |

## Use cases

<CardGroup cols={3}>
  <Card title="Job Board Application Tracking" href="/ats/use-cases/job-board-easy-apply">
    Job boards can post positions, accept applications, and monitor candidate progress through normalized recruitment stages via a single API that handles the complete application lifecycle.
  </Card>

  <Card title="Interview Insights" href="/ats/use-cases/interview-intelligence">
    Interview intelligence platforms can access structured interview data, update scorecards, and analyze candidate performance across standardized evaluation criteria.
  </Card>

  <Card title="Candidate Screening" href="/ats/use-cases/application-screening">
    Screening solutions can retrieve applications, process candidate data through qualification algorithms, and update application stages with acceptance or rejection reasoning using standardized fields.
  </Card>

  <Card title="Assessment & Background Checks" href="/ats/use-cases/assessment-flow">
    Providers can receive candidate evaluation orders, update test results, and automatically update application statuses with standardized scoring data that flows seamlessly into the hiring decision process.
  </Card>
</CardGroup>


# Automated Application Screening
Source: https://docs.stackone.com/ats/use-cases/application-screening

Automated application and candidate screening or scoring (eg. for AI-powered resume scoring).

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/banner-automatic-candidate-screening-ats.png" />
</Frame>

Imagine you’re working on your recruitment SaaS and looking to integrate AI features like application scoring and automated candidate screening. While it may seem simple, syncing data from multiple ATS platforms and handling job postings can bring challenges.

Tracking candidate applications in real-time across different ATS providers can become complicated. It requires proper management to keep everything up to date and consistent, ensuring smooth operation and data accuracy.

<ResponseField name="StackOne simplifies all of this by offering:">
  <Expandable title="StackOne Features">
    <ResponseField name="Why StackOne?">
      * **Unified API** connecting multiple ATS platforms for easy job and candidate data sync.
      * **Scalability** that lets you easily add new ATS platforms as your hiring needs grow.
      * **Standardized data formats** across ATS platforms for consistent and simplified data management.
      * **Real-time updates** via **webhooks**, keeping candidate and application data up to date.
    </ResponseField>
  </Expandable>
</ResponseField>

## Automated Candidate Screening with AI: Key Steps and System Interactions

Integrating automated candidate screening into your recruitment SaaS involves syncing data from multiple ATS providers, retrieving job postings, applications, LinkedIn profiles, and resumes, and using AI to score candidates based on job descriptions and criteria set by HR. This allows HR to make quick decisions, such as moving or rejecting candidates.

### Steps for Enabling Automated Candidate Screening in Your SaaS

Below are the steps to enable AI-powered candidate screening in your SaaS, allowing you to sync job postings and applications, score applications, and manage candidate workflows.

<Steps>
  <Step title="Sync Active Job Postings and Applications">
    **First, fetch active job postings:** Start by pulling all active job postings from the connected ATS provider using `x-account-id` in the request header. This will give you details like `title`, `content`, `locations`, `compensation`, and more.

    * **API Endpoint**: [GET /ats/job\_postings](/ats/api-reference/job-postings/list-job-postings)

    **Next, pull recent applications:** Fetch all candidate applications updated within the last month by setting the `updated_after` query parameter (e.g., **2024-08-01T00:00:00.000Z**) to ensure your SaaS dashboard has the latest applications.

    * **API Endpoint:** [GET /ats/applications](/ats/api-reference/applications/list-applications)

    **Retrieve associated candidate data:** For each application, retrieve the associated candidate information, including `name`, `email`, `social_links`, `phone`, and **Resume**. This data will be displayed alongside the application on your SaaS dashboard for easy review and analysis.

    * **API Endpoint:** [GET /ats/candidates/\{id}](/ats/api-reference/candidates/get-candidate)
  </Step>

  <Step title="Automate Application and Candidate Sync with Webhooks">
    **First, [set up webhooks](../../guides/webhooks) for application updates:** Configure webhooks to automatically sync updates for existing applications, such as `interview_stage`, `rejected_reasons`, and `application_status`, or capture new ones as soon as they are created. Hence, the dashboard always has the most current application data.

    * **Webhook Events:** `ats_applications.updated` or `ats_applications.created`

    **Next, sync candidate updates:** Similarly, set up webhooks to sync candidate information whenever there are updates or new candidates are added. This keeps your system up to date with the latest candidate details.

    * **Webhook Events:** `ats_candidates.updated` or `ats_candidates.created`

    **Trigger AI screening system:** Set up a webhook to trigger the intelligence system, which automatically screens and scores applications as they are updated or newly added. This ensures real-time evaluation and decision-making.
  </Step>

  <Step title="Store Candidate Data in Database">
    **Store fetched data:** Now, store fetched data, such as `application_id`, `candidate_id`, `job_id`, `interview_stage`, `application_status`, `candidate details`, and `resumes` in your database to facilitate real-time screening and analysis.

    **Centralize candidate information:** Keeping all data in one place ensures quick access to applications and candidate details for processing and HR decisions.
  </Step>

  <Step title="AI-Powered Application Scoring and Candidate Management">
    After applications and candidate details are fetched from the ATS via the recruitment SaaS, they will be screened by an intelligent AI system. The AI will carry out the following operations in the recruitment process:

    **Remove bias and fetch profiles:** AI will remove any bias related to gender, race, or culture when evaluating candidates. It will also fetch LinkedIn profiles along with the applications(from the ATS) for a complete analysis.

    **Score applications based on criteria:** AI scores each application using criteria set by HR, using NLP to analyze applications against job descriptions.

    **Automate actions and emails:** Based on the AI score, the system will automatically or manually move candidates to stages like `Shortlisted`, `Paused`, or `Rejected`, etc, and can send personalized rejection or shortlisted emails to candidates at scale.

    * **API Endpoint:** [PATCH ats/applications/\{id}](/ats/api-reference/applications/update-an-application)

    **Store scores and analysis:** The AI-generated score, application status, and detailed analysis for each candidate will be stored in the database, ensuring easy access for future reference and reporting.
  </Step>
</Steps>

The diagram below shows the key steps, from fetching job postings and applications to storing them in your database, using webhooks for updates, and applying AI-generated data for automated candidate screening and management.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/automatic-candidate-screening-ats-flow-diagram.png)
</Frame>

## Conclusion

This walkthrough explained how to add AI-driven resume scoring and automated candidate management to your recruitment SaaS. With StackOne's API and webhooks, you can sync job postings and candidate data across ATS platforms, improving the hiring process. AI Intelligence provides unbiased scoring, automates candidate actions, and stores detailed analysis for future reference, helping HR make quick decisions and improve the hiring process.


# Assessment & Background Checks
Source: https://docs.stackone.com/ats/use-cases/assessment-flow

Learn how to integrate real-time assessment data, AI insights, and ATS syncing to simplify user workflows and improve candidate evaluation

<Frame>
  ![assessment-provider-banner](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/assessment-intelligence-ats-banner.png)
</Frame>

Imagine you're developing an intelligence assessment SaaS designed to handle assessments like coding tests or psychometric evaluations for job candidates. While it may seem simple at first, integrating these assessments and syncing job data from multiple ATS systems can become complex.

Managing real-time candidate assessments across various ATS platforms requires precise data syncing and configuration, ensuring the right assessments are assigned to the correct roles and that results are handled efficiently.

<ResponseField name="StackOne simplifies all of this by offering:">
  <Expandable title="StackOne Features">
    <ResponseField name="Why StackOne?">
      * **Unified API:** connecting multiple ATS platforms for consistent job and candidate data sync.
      * **Scalable Infrastructure:** Easily onboard additional ATS providers as your hiring needs grow.
      * **Standardized data formats:** Avoid discrepancies across ATS platforms by using standardized data formats.
      * **Real-Time Webhooks:** Automatically sync assessment orders and results, keeping your dashboard always up to date.
    </ResponseField>
  </Expandable>
</ResponseField>

## Integrating Candidate Assessments Intelligence in Your SaaS: Key Steps and System Interactions

Integrating assessments into your SaaS involves syncing with multiple ATS providers, retrieving job and candidate data, and managing assessments such as coding tests or psychometric evaluations. This enables HR teams to assign, track, and evaluate candidate assessments based on specific job requirements, simplifying the hiring process.

### Steps for Integrating Assessment Intelligence in Your Assessment SaaS

Below are the steps to integrate assessment intelligence into your SaaS, enabling seamless assessment management, syncing with ATS providers, and automating candidate assessments:

<Steps>
  <Step title="Automate Assessment Sync with Webhooks for Real-Time Updates">
    **First, subscribe to the assessment webhook:** Start by setting up a webhook to automatically receive notifications when new assessment orders are created. This ensures your dashboard stays updated in real time when a new assessment is triggered for a candidate.

    * **Webhook Event:** `assessment_order.created`

    **Next, fetch detailed candidate and job data:** Once the webhook triggers, additional API calls will retrieve more information about the candidate's application, such as `id`, `candidate_id`, `interview_stage`, and more.

    * **API Endpoint:** [GET /ats/application/{id}](/ats/api-reference/applications/get-application)

    **We can also fetch job details** such as `id`, `title`, `content`, and more related to the application. This data can be used to update the dashboard with assessment and candidate details.

    * **API Endpoint:** [GET /ats/job-postings/{id}](/ats/api-reference/job-postings/get-job-posting)
  </Step>

  <Step title="Enable Assessments for Candidates in Your Dashboard">
    **Allow Users to enable different assessments:** Allow users to enable a variety of assessments like **coding tests**, **psychometric tests**, and more for their candidates in the dashboard. This helps them tailor the assessments based on the job role or specific hiring needs.

    * **API Endpoint:** [GET /ats/assessments/packages](/ats/api-reference/assessments/packages/list-assessments-packages)
  </Step>

  <Step title="Assign Assessments to Jobs and Candidates">
    **First, fetch active job postings:** Start by pulling all active job postings from the connected ATS provider using `x-account-id` in the request header. This will give you details like `title`, `content`, `locations`, `compensation`, and more.

    * **API Endpoint**: [GET /ats/job\_postings](/ats/api-reference/job-postings/list-job-postings)

    **Then, configure job-specific assessments:** Allow users to assign assessments to specific jobs. For instance, different coding tests can be assigned based on the role (**data engineer** vs. **front-end engineer**).

    * **API Endpoint:** [POST /ats/assessments/orders](/ats/api-reference/assessments/orders/order-assessments-request)

    **Trigger the assessment through ATS workflow:** When the candidate moves to a specific stage in the job process, allow users to trigger an assessment for the candidate using the `applicant_id` parameter.

    * **API Endpoint:** [POST /ats/assessments/orders](/ats/api-reference/assessments/orders/order-assessments-request)

    **After this, update the application status:** Update the candidate's application status using the `application_status` parameter.

    * **API Endpoint:** [PATCH /ats/applications/{id}](/ats/api-reference/applications/update-an-application)
  </Step>

  <Step title="Notify Candidates and Manage Results with AI Insights">
    **Send assessment details to candidates:** After triggering the assessment, the dashboard will send an email notification with instructions and a link to the assessment assigned to the candidate.

    **AI-driven candidate analysis:** Once the results are available for assessment (e.g., behavioral analysis), your SaaS can evaluate the candidate on traits like empathy, leadership, and creativity, giving a percentage score for each.

    **Performance report:** Your SaaS can also generate a visual performance report, analyzing the candidate's results in assigned assessments and providing users with insights through detailed graphical data.

    **Push the assessment results to the ATS:** Finally, update the ATS provider with the assessment results, ensuring users can see the outcome directly on their dashboard whenever needed.

    * **API Endpoint:** [PATCH /ats/assessments/orders/{id}/result](/ats/api-reference/assessments/results/update-assessments-result)
  </Step>
</Steps>

The diagram below outlines the main steps involved in integrating assessments into your SaaS, from subscribing to webhooks, syncing with ATS, and assigning assessments, to update results for simplified candidate management.

<Frame>
  ![flow-diagram](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/assessment-provider-ats-flow-diagram.png)
</Frame>

## Conclusion

This walkthrough showed how to integrate assessment features into your SaaS platform, making it easier to manage candidate assessments. With StackOne's API and webhooks, you can sync job and candidate data from ATS platforms, assign job-specific assessments, and handle the process of sending results back to the ATS. This helps users make faster, more informed decisions, improving the overall hiring process.


# Intelligent Candidate Screening
Source: https://docs.stackone.com/ats/use-cases/intelligent-candidate-screening

Automated candidate screening and scoring to simplify application management and HR decisions

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/banner-automatic-candidate-screening-ats.png)
</Frame>

Imagine you’re working on your recruitment SaaS and looking to integrate AI features like application scoring and automated candidate screening. While it may seem simple, syncing data from multiple ATS platforms and handling job postings can bring challenges.

Tracking candidate applications in real-time across different ATS providers can become complicated. It requires proper management to keep everything up to date and consistent, ensuring smooth operation and data accuracy.

<ResponseField name="StackOne simplifies all of this by offering:">
  <Expandable title="StackOne Features">
    <ResponseField name="Why StackOne?">
      * **Unified API** connecting multiple ATS platforms for easy job and candidate data sync.
      * **Scalability** that lets you easily add new ATS platforms as your hiring needs grow.
      * **Standardized data formats** across ATS platforms for consistent and simplified data management.
      * **Real-time updates** via **webhooks**, keeping candidate and application data up to date.
    </ResponseField>
  </Expandable>
</ResponseField>

## Automated Candidate Screening with AI: Key Steps and System Interactions

Integrating automated candidate screening into your recruitment SaaS involves syncing data from multiple ATS providers, retrieving job postings, applications, LinkedIn profiles, and resumes, and using AI to score candidates based on job descriptions and criteria set by HR. This allows HR to make quick decisions, such as moving or rejecting candidates.

### Steps for Enabling Automated Candidate Screening in Your SaaS

Below are the steps to enable AI-powered candidate screening in your SaaS, allowing you to sync job postings and applications, score applications, and manage candidate workflows.

<Steps>
  <Step title="Sync Active Job Postings and Applications">
    **First, fetch active job postings:** Start by pulling all active job postings from the connected ATS provider using `x-account-id` in the request header. This will give you details like `title`, `content`, `locations`, `compensation`, and more.

    * **API Endpoint**: [GET /ats/job\_postings](/ats/api-reference/job-postings/list-job-postings)

    **Next, pull recent applications:** Fetch all candidate applications updated within the last month by setting the `updated_after` query parameter (e.g., **2024-08-01T00:00:00.000Z**) to ensure your SaaS dashboard has the latest applications.

    * **API Endpoint:** [GET /ats/applications](/ats/api-reference/applications/list-applications)

    **Retrieve associated candidate data:** For each application, retrieve the associated candidate information, including `name`, `email`, `social_links`, `phone`, and **Resume**. This data will be displayed alongside the application on your SaaS dashboard for easy review and analysis.

    * **API Endpoint:** [GET /ats/candidates/\{id}](/ats/api-reference/candidates/get-candidate)
  </Step>

  <Step title="Automate Application and Candidate Sync with Webhooks">
    **First, [set up webhooks](../../guides/webhooks) for application updates:** Configure webhooks to automatically sync updates for existing applications, such as `interview_stage`, `rejected_reasons`, and `application_status`, or capture new ones as soon as they are created. Hence, the dashboard always has the most current application data.

    * **Webhook Events:** `ats_applications.updated` or `ats_applications.created`

    **Next, sync candidate updates:** Similarly, set up webhooks to sync candidate information whenever there are updates or new candidates are added. This keeps your system up to date with the latest candidate details.

    * **Webhook Events:** `ats_candidates.updated` or `ats_candidates.created`

    **Trigger AI screening system:** Set up a webhook to trigger the intelligence system, which automatically screens and scores applications as they are updated or newly added. This ensures real-time evaluation and decision-making.
  </Step>

  <Step title="Store Candidate Data in Database">
    **Store fetched data:** Now, store fetched data, such as `application_id`, `candidate_id`, `job_id`, `interview_stage`, `application_status`, `candidate details`, and `resumes` in your database to facilitate real-time screening and analysis.

    **Centralize candidate information:** Keeping all data in one place ensures quick access to applications and candidate details for processing and HR decisions.
  </Step>

  <Step title="AI-Powered Application Scoring and Candidate Management">
    After applications and candidate details are fetched from the ATS via the recruitment SaaS, they will be screened by an intelligent AI system. The AI will carry out the following operations in the recruitment process:

    **Remove bias and fetch profiles:** AI will remove any bias related to gender, race, or culture when evaluating candidates. It will also fetch LinkedIn profiles along with the applications(from the ATS) for a complete analysis.

    **Score applications based on criteria:** AI scores each application using criteria set by HR, using NLP to analyze applications against job descriptions.

    **Automate actions and emails:** Based on the AI score, the system will automatically or manually move candidates to stages like `Shortlisted`, `Paused`, or `Rejected`, etc, and can send personalized rejection or shortlisted emails to candidates at scale.

    * **API Endpoint:** [PATCH ats/applications/\{id}](/ats/api-reference/applications/update-an-application)

    **Store scores and analysis:** The AI-generated score, application status, and detailed analysis for each candidate will be stored in the database, ensuring easy access for future reference and reporting.
  </Step>
</Steps>

The diagram below shows the key steps, from fetching job postings and applications to storing them in your database, using webhooks for updates, and applying AI-generated data for automated candidate screening and management.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/automatic-candidate-screening-ats-flow-diagram.png)
</Frame>

## Conclusion

This walkthrough explained how to add AI-driven resume scoring and automated candidate management to your recruitment SaaS. With StackOne's API and webhooks, you can sync job postings and candidate data across ATS platforms, improving the hiring process. AI Intelligence provides unbiased scoring, automates candidate actions, and stores detailed analysis for future reference, helping HR make quick decisions and improve the hiring process.


# Interview Intelligence
Source: https://docs.stackone.com/ats/use-cases/interview-intelligence

Learn how to integrate real-time interview data into your SaaS to deliver intelligent insights and seamlessly sync back to your customers’ ATS

<Frame>
  ![StackOne Interview Intelligence Banner](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/interview-intelligence-use-case-banner.png)
</Frame>

Imagine you're working on your SaaS, aiming to integrate real-time interview data along with AI-powered features such as interview recordings by a bot, automatic note-taking, and candidate feedback collection. While integrating real-time interview data into your SaaS seems straightforward, it can quickly become challenging when dealing with multiple ATS platforms.

Each ATS provider, such as Greenhouse, Ashby, or Workday, has its own data structures, APIs, and syncing methods, which often lead to mismatched data, delayed interview updates, and the need for endless custom code just to keep everything in sync.

<ResponseField name="StackOne simplifies all of this by offering:">
  <Expandable title="StackOne Features">
    <ResponseField name="Why StackOne?">
      * **Unified API** that connects to multiple ATS platforms, simplifying interview data sync.
      * **Consistent interview data formats** across different ATS integrations.
      * **Scalability** that lets you easily add new ATS platforms as your needs grow.
      * **Real-time updates through webhooks**, ensuring always-current interview data.
    </ResponseField>
  </Expandable>
</ResponseField>

With StackOne, you can move beyond the grind of manual integrations and focus on building the features that truly matter.

## Integrating Interview Data and AI Intelligence: Key Steps and System Interactions

Integrating real-time interview data and AI insights into your SaaS involves syncing data from ATS providers like Greenhouse and capturing details such as interview recording links, notes, and candidate feedback.

### Steps for Enabling Interview Intelligence in Your SaaS

Below are the steps to enable interview intelligence in your SaaS, allowing you to sync interview data from multiple ATS providers, keep your database updated in real time, and store AI-generated insights:

<Steps>
  <Step title="Automate Sync with Webhooks for Real-Time Interview Updates">
    * **First, retrieve the list of interviews**: Start by fetching interviews from the selected ATS provider using `x-account-id` in the request header, according to the chosen ATS. Set the `updated_after` query parameter to one year ago (e.g., **2023-09-25T00:00:00.000Z**) to get interviews updated within the last year.

      * API Endpoint: [GET /ats/interviews](/ats/api-reference/interviews/list-interviews)

    * **Next, store the data**: Save this interview data in your database. You’ll also want to fetch additional applicant details using `application_id` as the path parameter, which includes fields like `job ID`, `application_status`, and `remote_candidate_id`.

      * API Endpoint: [GET /ats/applications/\{id}](/ats/api-reference/applications/get-application)

    * **Then, [set up a webhook](/guides/webhooks) for real-time updates:** Set up a webhook to automatically sync new interviews or updates to existing interview data (e.g., `interview_status`, `interview_stage`, `interviewers info`, `start_at`, `end_at`, and `meeting_url`). Each time a webhook update is received, your SaaS database will be refreshed with the latest applicant data.
  </Step>

  <Step title="Fetch Interviews for Applicants as per the Requirement">
    * **First, pull relevant interviews from your database:** Use the database to pull up all relevant interviews along with the corresponding applicant details whenever you need them.

    * **Next, apply filters to refine your search:** Use parameters like `interview_status`, `start_at`, `interviewer info`, `application_id`, `interview_stage`, and more to get the interviews you need and display them on your dashboard.

    * **If you need more information**, make an API call to the specific ATS provider using `x-account-id` in the request header to fetch the additional interview details.

      * ATS Endpoint: [GET /ats/interviews/\{id}](/ats/api-reference/interviews/get-interview)
  </Step>

  <Step title="Generate and Store Interview Intelligence">
    * **Generate interview intelligence:** Utilize fetched interview data to generate intelligent insights such as **interview notes**, **candidate feedback**, **recording links**, and other relevant information captured during the interview process.

    * **Next, store this intelligence data:** Save these insights in your database so they’re accessible whenever needed, providing a centralized view of all interview details for easy reference.
  </Step>
</Steps>

The diagram below shows the key steps, from fetching interviews and storing them in your database to using webhooks for updates and incorporating AI-generated data.

<Frame>
  ![StackOne Interview Intelligence Flow Diagram](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/interview-intelligence-use-case-flow-diagram.png)
</Frame>

## Conclusion

In this walkthrough, we covered how to integrate real-time interview data and AI-driven features into your SaaS. With StackOne's unified API and webhooks, we made it easier to sync interview data from multiple ATS providers while also adding features like automatic interview recordings, notes, and candidate feedback. This approach keeps your SaaS updated and allows for efficient management of interview data across different ATS platforms.


# Job Board - Easy Apply
Source: https://docs.stackone.com/ats/use-cases/job-board-easy-apply

Learn how StackOne simplifies job board integrations with multiple ATS platforms, reducing custom code and maintenance

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/banner-simplifying-integrations-across-disparate-ats.png)
</Frame>

Imagine you're building a job board that needs to pull listings from multiple ATS platforms like Greenhouse, Ashby, and Workday. Each platform has its own API and data format, requiring custom code and constant maintenance.

As the number of integrations grows, so does the complexity—leading to a fragile and time-consuming system.

Managing these integrations can quickly become a burden, consuming valuable time and resources. Without a unified solution, you’re likely to face:

* Repetitive and tedious coding for each ATS, making the integration process time-consuming and error-prone.
* Ongoing maintenance burdens as you try to keep all integrations functional with every API update.
* Frustration with traditional iPaaS solutions that are complex to implement and come with high costs.

<Card title="StackOne simplifies all of this by offering:" icon="square-terminal" iconType="duotone">
  - • A unified API that allows you to connect to multiple ATS platforms with minimal effort.
  - • Consistent data formats across all integrations, reducing the need for custom code.
  - • Scalability that lets you easily add new ATS platforms as your needs grow.
</Card>

With StackOne, you can move beyond the grind of manual integrations and focus on building the features that truly matter.

## Integrating ATS Platforms: Key Steps and System Interactions for Your Job Board

When building your job board, you'll need to display jobs and manage applications from various ATS providers like Greenhouse, Ashby, and others. To streamline this process, we will be using StackOne's ATS endpoints to integrate and synchronize data across multiple platforms.

Understanding the sequence of API calls is crucial to making this integration work seamlessly. The diagram below illustrates how these interactions occur—from the moment a user engages with your job board to the retrieval of job listings and application data from the ATS providers.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/api-flow-simplifying-integrations-across-disparate-ats.png)
</Frame>

### Steps to Building a Job Board Using StackOne

When building a job board that integrates with multiple ATS platforms there are several steps involved. Each step corresponds to a specific operation within StackOne, which handles the necessary API interactions to fetch, display, and manage job listings and applications. Below are the steps needed to create a functional job board using StackOne.

<Steps>
  <Step title="Fetch ATS Accounts to Display Jobs and Applications">
    The first step in setting up your job board is to fetch all available ATS accounts. This operation retrieves the account information, including the accountId, which is crucial for identifying which ATS platform's data will be accessed for further operations. This allows HR professionals to select any ATS account from which they want to view jobs and applications. By displaying all connected ATS accounts, the job board provides a centralized interface for managing multiple platforms.

    * API endpoint: [GET /accounts](/platform/api-reference/accounts/list-accounts)
  </Step>

  <Step title="Display Job Listings from Multiple ATS Providers">
    After an ATS account is selected, the next step is to fetch the job listings associated with that account. This API call translates the interface and retrieves job data from the selected ATS platform, which is then displayed on the job board. This step enables HR professionals to view job listings from any selected ATS account, making it easier to manage job openings across different platforms through a single interface.

    * API endpoint: [GET /ats/jobs](/ats/api-reference/jobs/list-jobs)
  </Step>

  <Step title="Display Applications from Multiple ATS Providers">
    After fetching job listings, you'll also need to display the candidate applications associated with those jobs. This operation retrieves application data related to the selected accountId, ensuring that all candidate applications are accessible in one place. HR professionals can view candidate applications for any selected ATS account, streamlining the process of managing and reviewing applications across multiple platforms.

    * API endpoint: [GET /ats/applications](/ats/api-reference/applications/list-applications)
  </Step>

  <Step title="Display Job Postings to Candidates">
    To keep your job board's listings up-to-date and accessible to candidates, this API call retrieves job postings from the selected ATS accounts. The endpoint translates the interface and fetches the data, allowing you to present a comprehensive list of job opportunities on your job board.

    * API endpoint: [GET /ats/job\_postings](/ats/api-reference/job-postings/list-job-postings)
  </Step>

  <Step title="Submit Job Applications">
    In this step of the job board process, we are enabling candidates to submit their job applications. This operation sends the application details from the job board to StackOne, which then forwards them to the appropriate ATS platform for processing. This allows candidates to apply for jobs directly through your job board, ensuring that their applications are correctly submitted and tracked by the respective ATS platform.

    * API endpoint: [POST /ats/applications](/ats/api-reference/applications/create-application)
  </Step>
</Steps>

## Conclusion

In this walkthrough, we explored the process of creating a job board that integrates with multiple ATS platforms like Greenhouse and Ashby. By using StackOne's unified API, we minimized the effort required to connect these systems. StackOne streamlined the integration process, enabling us to manage jobs and applications across various platforms without the need for custom coding or extensive maintenance.


# Get Account
Source: https://docs.stackone.com/crm/api-reference/accounts/get-account

get /unified/crm/accounts/{id}



# List Accounts
Source: https://docs.stackone.com/crm/api-reference/accounts/list-accounts

get /unified/crm/accounts



# Creates a new Contact
Source: https://docs.stackone.com/crm/api-reference/contacts/creates-a-new-contact

post /unified/crm/contacts



# Get Contact
Source: https://docs.stackone.com/crm/api-reference/contacts/get-contact

get /unified/crm/contacts/{id}



# List Contacts
Source: https://docs.stackone.com/crm/api-reference/contacts/list-contacts

get /unified/crm/contacts



# Update Contact (early access)
Source: https://docs.stackone.com/crm/api-reference/contacts/update-contact-early-access

patch /unified/crm/contacts/{id}



# Get Contact Custom Field Definition
Source: https://docs.stackone.com/crm/api-reference/custom-field-definitions/get-contact-custom-field-definition

get /unified/crm/custom_field_definitions/contacts/{id}



# List Contact Custom Field Definitions
Source: https://docs.stackone.com/crm/api-reference/custom-field-definitions/list-contact-custom-field-definitions

get /unified/crm/custom_field_definitions/contacts



# Get all Lists
Source: https://docs.stackone.com/crm/api-reference/lists/get-all-lists

get /unified/crm/lists



# Get List
Source: https://docs.stackone.com/crm/api-reference/lists/get-list

get /unified/crm/lists/{id}



# null
Source: https://docs.stackone.com/crm/common-guide/pagination



StackOne's <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip> allows paginating on API requests that return multiple records using a page cursor.

The following optional URL parameters are used for pagination:

<ParamField query="page_size" type="string" default="25">
  The number of records per page.
</ParamField>

<ParamField query="next" type="string">
  The `next` parameter is used to iterate through data pages.
</ParamField>

<Warning>
  It is recommended to keep the same page\_size throughout the sequence of pagination requests otherwise unexpected behaviour may occur.
</Warning>

## Sample URL

```
https://api.stackone.com/unified/hris/employees?page_size=25&next=eyJyIjphAsHHere
```

## Sample Response

In the response payload, you can find the `next` cursor. To get the next page of data send a new request with the `next` parameter set to this value.

```json
"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]
```

Once the cursor reaches the end of the data list, both values become NULL.

<Frame>
  ![Bypassed Records scenario](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/cd9e2c8-pagination_stripped.gif)
</Frame>

For further information see [Guides - Pagination](/guides/pagination)


# Overview
Source: https://docs.stackone.com/crm/introduction



A unified CRM API helps overcomes typical integration challenges by standardizing inconsistent data models, normalizing varied terminology, and creating a consistent entity structure where contacts, accounts, and lists exist predictably regardless of which vendor's system houses the underlying customer data.

## Benefits of the CRM API

Here are some benefits of using our CRM API that simplifies and enhances customer relationship management:

<AccordionGroup>
  <Accordion title="Unified Contact and Account Management" defaultOpen={false}>
    Manage customer contacts and accounts through a single standardized API, regardless of the underlying CRM platforms, ensuring a consistent view of customer data.
  </Accordion>

  <Accordion title="Sandbox Access for Seamless Testing">
    Developers can utilize sandbox environments to test integrations without affecting live data, ensuring a smooth deployment process.
  </Accordion>

  <Accordion title="Real-Time Data Synchronization">
    StackOne's APIs support real-time data polling, allowing for immediate updates and synchronization across platforms.
  </Accordion>

  <Accordion title="Privacy-First Design Ensuring Compliance">
    With a [focus on security](https://www.stackone.com/blog/why-your-choice-of-unified-api-could-make-or-break-compliance), StackOne's architecture avoids unnecessary data storage, maintaining compliance with data protection regulations.
  </Accordion>

  <Accordion title="Synthetic and Native Webhooks for Updates">
    The platform provides both [synthetic and native webhooks](/guides/webhooks), enabling real-time notifications for customer and opportunity changes.
  </Accordion>
</AccordionGroup>

## Key Features

The table below shows key features of the CRM API that make customer relationship management easier, from real-time contact tracking to opportunity management:

| **Feature**                      | **Description**                                                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Comprehensive Contact Management | Easily create, update, and retrieve customer profiles, including contact details, interaction history, and engagement. |
| Real-Time Data Synchronization   | Ensure that customer information, sales opportunities, and interactions are updated across systems instantly.          |
| Real-Time Webhooks               | Receive instant notifications for changes in customer profiles, opportunities, or lead statuses.                       |

## Entity Model and Relationships

The following diagram illustrates the key entities within the CRM API:

```mermaid
erDiagram
    Contact ||--o{ Account : ""
    List }o--o{ Contact : ""
    List }o--o{ Account : ""

    Contact {
        string id
        string remote_id
        string name
        string address
        string communicationPreferences
        string email
        string phoneNumber
    }

    Account {
        string id
        string status
        string transactionHistory
        date createdAt
        date updatedAt
    }

    List {
        string id
        string name
        string type
        date createdAt
        date updatedAt
    }

```

The following table outlines key entities within the CRM system and provides a brief description of each.

| Entity   | Description                                                                                                              |
| -------- | ------------------------------------------------------------------------------------------------------------------------ |
| Contacts | Manages individual contact details, including names, addresses, and communication preferences.                           |
| Accounts | Handles organizational accounts, encompassing details like account status, associated contacts, and transaction history. |
| Lists    | Manage your custom data lists across your service providers.                                                             |


# Get Drive
Source: https://docs.stackone.com/documents/api-reference/drives/get-drive

get /unified/documents/drives/{id}



# List Drives
Source: https://docs.stackone.com/documents/api-reference/drives/list-drives

get /unified/documents/drives



# Download File
Source: https://docs.stackone.com/documents/api-reference/files/download-file

get /unified/documents/files/{id}/download



# Get File
Source: https://docs.stackone.com/documents/api-reference/files/get-file

get /unified/documents/files/{id}



# List Files
Source: https://docs.stackone.com/documents/api-reference/files/list-files

get /unified/documents/files



# Search Files
Source: https://docs.stackone.com/documents/api-reference/files/search-files

post /unified/documents/files/search



# Upload File
Source: https://docs.stackone.com/documents/api-reference/files/upload-file

post /unified/documents/files/upload



# Get Folder
Source: https://docs.stackone.com/documents/api-reference/folders/get-folder

get /unified/documents/folders/{id}



# List Folders
Source: https://docs.stackone.com/documents/api-reference/folders/list-folders

get /unified/documents/folders



# null
Source: https://docs.stackone.com/documents/common-guide/pagination



StackOne's <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip> allows paginating on API requests that return multiple records using a page cursor.

The following optional URL parameters are used for pagination:

<ParamField query="page_size" type="string" default="25">
  The number of records per page.
</ParamField>

<ParamField query="next" type="string">
  The `next` parameter is used to iterate through data pages.
</ParamField>

<Warning>
  It is recommended to keep the same page\_size throughout the sequence of pagination requests otherwise unexpected behaviour may occur.
</Warning>

## Sample URL

```
https://api.stackone.com/unified/hris/employees?page_size=25&next=eyJyIjphAsHHere
```

## Sample Response

In the response payload, you can find the `next` cursor. To get the next page of data send a new request with the `next` parameter set to this value.

```json
"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]
```

Once the cursor reaches the end of the data list, both values become NULL.

<Frame>
  ![Bypassed Records scenario](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/cd9e2c8-pagination_stripped.gif)
</Frame>

For further information see [Guides - Pagination](/guides/pagination)


# null
Source: https://docs.stackone.com/documents/file-Picker



# StackOne File Picker SDK Documentation

The StackOne File Picker SDK enables you to integrate file selection from connected integrations into your application. Below are the installation steps, usage examples, and API details.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/site-picker.png)
</Frame>

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/sharepoint-native-picker.png)
</Frame>

## Installation

Install the SDK using one of the following package managers:

```bash
# Using NPM
npm install --save @stackone/file-picker

# Using Yarn
yarn add @stackone/file-picker
```

# Usage

Below you can find the basic usage of the StackOne File Picker SDK using React:

```jsx
import React, { useState, useEffect, useCallback } from 'react';
import { FilePicker } from '@stackone/file-picker';

export const FilePickerButton = () => {
  const [filePicker, setFilePicker] = useState(null);

  useEffect(() => {
    const initializePicker = async () => {
      const { sessionToken } = await retrieveAPISessionToken();
      setFilePicker(new FilePicker({ sessionToken }));
    };

    initializePicker();
  }, []);

  const handleClick = useCallback(() => {
    filePicker?.open();
  }, [filePicker]);

  return (
    <button onClick={handleClick} disabled={!filePicker}>
      Open File Picker
    </button>
  );
};
```

# API Reference

## FilePicker Class

### Constructor: FilePicker(options)

The options object can include the following parameters:

<ParamField query="sessionToken" type="string" required>
  The session token generated on the server side.
</ParamField>

<ParamField query="baseUrl" type="string" default="https://app.stackone.com">
  The base URL for the StackOne API.
</ParamField>

<ParamField query="containerId" type="string">
  The ID of the container to mount the picker into.
</ParamField>

<ParamField query="onFilesPicked" type="function">
  Callback function that is triggered when files are selected.
  The function will return an array of files with the Unified ID that can be used in the Unified Download Documents API.
  After receiving the files, the File Picker will close automatically.
</ParamField>

<ParamField query="onOpen" type="function">
  Callback function that is triggered when the picker opens.
</ParamField>

<ParamField query="onClose" type="function">
  Callback function that is triggered when the picker closes.
</ParamField>

<ParamField query="onCancel" type="function">
  Callback function that is triggered when the picker is closed without file selection.
</ParamField>

### Methods

<ParamField query="open()" type="method">
  Opens the file picker interface.
</ParamField>

<ParamField query="close()" type="method">
  Closes the file picker interface.
</ParamField>


# Overview
Source: https://docs.stackone.com/documents/introduction



The StackOne unified API for Documents streamlines access to knowledge bases (e.g., Notion, Confluence) and file storage platforms (e.g., Google Drive, SharePoint), enabling seamless retrieval, uploading, and downloading of content. By abstracting away platform-specific complexities, it simplifies integration while ensuring secure and efficient document management across multiple systems.

## Benefits of the Documents API

Here are some benefits of using our Documents API that simplifies and enhances the recruitment process:

<AccordionGroup>
  <Accordion title="Sandbox Access for Seamless Testing">
    Developers can utilize sandbox environments to test integrations without affecting live data, ensuring a smooth deployment process.
  </Accordion>

  <Accordion title="Real-Time Data Synchronization">
    StackOne's APIs support real-time synchronization, ensuring that content changes are reflected immediately across connected platforms.
  </Accordion>

  <Accordion title="Privacy-First Design Ensuring Compliance">
    With a [focus on security](https://www.stackone.com/blog/why-your-choice-of-unified-api-could-make-or-break-compliance), StackOne ensures secure content storage and maintains compliance with data protection regulations.
  </Accordion>

  <Accordion title="Synthetic and Native Webhooks for Updates">
    The platform provides both [synthetic and native webhooks](/guides/webhooks), delivering real-time notifications for changes in drives, folders, and files.
  </Accordion>

  <Accordion title="Comprehensive File Management and Knowledge Base Integration Coverage">
    StackOne offers [out-of-the-box integrations](https://www.stackone.com/integrations) with leading File Management platforms, simplifying the integration process.
  </Accordion>
</AccordionGroup>

## Entity Model and Relationships

The following diagram illustrates the key entities within the Documents API:

```mermaid
erDiagram
    Drives ||--o{ Folders : ""
    Drives ||--o{ Files : ""
    Folders ||--o{ Files : ""
    Folders ||--o{ Folders : ""

    Drives {
        string id
        string remote_id
    }

    Folders {
        string id
        string remote_id
        string parent_folder_id
        string remote_parent_folder_id
        string drive_id
        string remote_drive_id
    }

    Files {
        string folder_id
        string remote_folder_id
        string drive_id
        string remote_drive_id
    }
```

The following table outlines key entities within the Documents system and provides a brief description of each:

| Entity  | Description                                                                                                                                                                                                                                                                                                      |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Drives  | Represents the top-level storage containers in the document management system. Each drive can contain multiple folders and files, and has basic metadata like name, description, and URL. Drives are typically used to organize content at the highest level, such as by department or project.                  |
| Folders | Manages hierarchical organization within drives. Folders can contain files and other folders (subfolders), creating a tree structure. Each folder tracks its owner, parent folder, associated drive, and various metadata like size and path. Folders help organize content in a logical structure.              |
| Files   | Contains the actual documents and their metadata. Each file belongs to a folder and drive, has an owner, and includes important attributes like format, size, and path. Files represent the actual content being managed, with support for various file types and versioning through created/updated timestamps. |


# Accounts
Source: https://docs.stackone.com/guides/accounts-section

Browse and take actions on any of the project's linked accounts

<Note>
  Linked Account definition

  An Account (or "linked account") represents one of your customer or user's connection with a third party system.
</Note>

The Accounts section ([https://app.stackone.com/accounts](https://app.stackone.com/accounts)) of the StackOne dashboard allows you to view all the tools connected by your customers (or yourself in the case of sandbox accounts).

The Account section can be used to:

* See an exhaustive list of every tool linked by your customers
* Test the connection with the account by executing requests and seeing result
  * This request testing interface can help you quickly test that the connection is working as expected and assist in debugging issues flagged by your customer
* Easily access and copy the underlying Account ID of a linked account
* Edit & re-connect one of your customers linked account on their behalf
* View and manage additional information about the account

### Access

* Project User with `Basic` permission will only be able to view high level details about the accounts
* Users with `Project Admin` permissions will be able to edit, delete and trigger API requests for any of the accounts linked in that project

## Capabilities

You can use use the interactive demo below to preview the accounts page features

**Filtering the list for specific accounts & providers**

<iframe width="100%" height="500px" src="https://demo.arcade.software/eb05aVOOTWQPdVBhSeX1?embed&show_copy_link=true\" title="Accounts - Search & Filters" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen allow="clipboard-write" />

**Take quick action about specific accounts directly on the listing page**

<iframe width="100%" height="500px" src="https://demo.arcade.software/YVSEE44aVN7GVaV5bm7F?embed&show_copy_link=true" title="Accounts - List Actions" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen allow="clipboard-write" />

**View more details about a specific account**

<iframe width="100%" height="500px" src="https://demo.arcade.software/LTXeW2VAxTxIHLVbFelM?embed&show_copy_link=true" title="Accounts - Account Overview" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen allow="clipboard-write" />


# API Keys
Source: https://docs.stackone.com/guides/api-keys

Steps to generate and manage API keys

To connect your application with StackOne securely, you need to generate API keys. These keys authenticate your application and protect your data.

## Step-by-Step Guide to Generating an API Key

<Steps>
  <Step title="Access the API Key Management Section">
    * Log in to StackOne and go to the "API Keys" section in the left navigation menu.
    * This is where you can generate and manage your API keys.

    <Frame>
      ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/15d009b-image.png)
    </Frame>
  </Step>

  <Step title="Generate a New API Key">
    * Click the "Create API Key" button. In the popup dialog, enter a name for your key (e.g., "stackone-ats-key").
    * This name is a label and cannot be changed later. Click "Generate" to create your unique API key.

    <Frame>
      ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/9948098-image.png)
    </Frame>
  </Step>

  <Step title="Securely Store the API Key">
    * The API key will be displayed on-screen. Copy it immediately and store it securely, as this is the only time it will be shown.
    * If you lose the key, you'll need to generate a new one. Store the key in a secure location, such as a password manager.

    <Frame>
      ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/4490dbe-image.png)
    </Frame>
  </Step>

  <Step title="Managing API Keys">
    * The new API key will be listed in the "API Keys" tab.
    * You can view, revoke, or regenerate keys as needed, such as if there's a security issue.

    <Frame>
      ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/744a9dc-image.png)
    </Frame>
  </Step>
</Steps>

## Using the generated API Key

Once you've [generated your API key](#step-by-step-guide-to-generating-an-api-key), it’s essential to know how to use it for authentication.

You will need to include the API key for every API call. For basic authentication, you can use the API key in the username or password field when calling any API endpoint, such as the [List Accounts endpoint](/platform/api-reference/accounts/list-accounts).

### Basic Authentication

If you need detailed steps on how to use the API key for basic authentication, including how to convert it into a Base64 encoded string, refer to the [Basic Authentication Guide](/basic-authentication-with-stackone-api).

## Recommendation

**Secure API Keys and Credentials:** Store your API keys and other sensitive information in secure locations such as key vaults or password managers. Avoid hard-coding them directly into your application. Use environment variables to pass these values to your application during runtime.


# Auth Link
Source: https://docs.stackone.com/guides/auth-link



## Overview

Auth Links allow you to deliver a secure URL to your end users that integrates them seamlessly, giving them a secure, in-browser experience without requiring you to embed the Stackone Integration Hub in your web app.

## How to generate a link

<iframe width="100%" height="500px" src="https://demo.arcade.software/GqFN5NNTGHqlaikCSUe6?embed&show_copy_link=true" title="StackOne - Accounts - Auth Link" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen allow="clipboard-write" />

An Auth Link can be generated directly from the StackOne dashboard. Here's how:

1. Log in to the [StackOne dashboard](https://app.stackone.com/) and select [Accounts](https://app.stackone.com/accounts) from the left menu.

2. Press the **🔗 Create Auth Link** button on the right hand-side

   <Frame>
     ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/257b14c-image.png)
   </Frame>

3. Fill in the required fields into the **Create Auth Link** modal:

   * Origin owner ID - this should be the customer identifier you use in your own system(s) (most likely, a UUID or integer)

   * Origin owner name - this is the Customer Name in your own system(s)

   * (optional) Origin username - your customers' user (eg: an email address) that will connect or be responsible for the connection of the system

   * (optional) Category - If you have enabled integrations across multiple category - you can filter the list of connector displayedMake sure that the information you enter matches your system precisely. Then click on **Create Link**.

   * <Frame>
       ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/0a9923f-image.png)
     </Frame>

4. A unique **Auth Link** is then generated. Copy and send this to your customer.

   <Frame>
     ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/be49579-image.png)
   </Frame>

<Note>
  Note: This link expires after 5 days.
</Note>

### Generating the link programmatically

You can programmatically retrieve such links to enable a more scalable way of sending links to your customer.

You can generate a link by doing  call to the [Create Connect Session Endpoint](/platform/api-reference/connect-sessions/create-connect-session) and use the `auth_link_url`property sent back.

<Info>
  make sure to specify an appropriate value in `expires_in` when creating the token in order to leave enough time for your customer to complete the connection process after receiving the link (eg. 5 days is 432000, 7 days is 605000)
</Info>

## What does the receiving user see?

When the user clicks on the **Auth Link**, they will see the StackOne Integrations Hub with a list of all integrations enabled on your project. The user can then select the provider they want to connect and will be prompted to fill out their authorization details.

<Frame>
  ![Auth Link Result Page](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/auth-link-result-page.png)
</Frame>

## Verifying the Connection

After the user has completed their authentication and connected successfully, Stackone will fire a `account.created` [webhook event](/guides/webhooks) containing the Account ID (which you will need to [successfully make a unified API request](/guides/making-your-first-api-request)). The linked account will also be displayed in the [accounts](https://app.stackone.com/accounts) page and it will also be visible via the [Accounts](/platform/api-reference/accounts/list-accounts) API endpoint.


# null
Source: https://docs.stackone.com/guides/common-integration-errors



## Teamtailor

Below is a table detailing common error codes returned by the Unified API, their meanings, and common remediation steps:

| Error Code | Description | Probable Cause                                                  | Remediation Steps                                                                                                                                          |
| :--------: | ----------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|    `501`   | Bad Request | The API key is missing permissions to access the given endpoint | Ask your customer to re-authenticate following the steps outlined in the [relevant documentation](https://hub.stackone.com/en/articles/7727336-teamtailor) |

### Candidate hired\_at date

* Given Teamtailor considers a Candidate as hired when they are in the `Hired` stage, the `hired_at` field indicates the date when the Candidate entered the `Hired` stage.

## Hibob

### Missing or inaccurate employment information

* `termination_date` may be missing or null as well as `employment_status` if the `View selected employees' Lifecycle sections` is missing from the service user (refer to [the Hibob guide](https://hub.stackone.com/en/articles/8233374-hibob-service-user-authentication) for the full permission sets that your customer needs to enable)

<br />

| Error Code | Description | Probable Cause                                                                                                                              | Remediation Steps                                                                                                                                                                                             |
| :--------: | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|    `403`   | Forbidden   | If you receive an empty response or error 403, it likely means the permissions do not allow you to access the data you are trying to fetch. | Ask your customer to re-authenticate following the steps outlined in the [relevant documentation](https://hub.stackone.com/connection-guides/hris/hibob-service-user#access-permissions-for-the-service-user) |

<br />

## Greenhouse

| Error Code | Description | Probable Cause                                                                                                                         | Remediation Steps                                                                                                                                          |
| :--------: | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|    `404`   | Not found   | Greenhouse may also return 404 if an invalid Greenhouse user ID was provided in the on-behalf-of input in the account linking process. | Ask your customer to re-authenticate following the steps outlined in the [relevant documentation](https://hub.stackone.com/en/articles/7727805-greenhouse) |

<br />

## SmartRecruiters

SmartRecruiters has restrictive [rate limits](https://developers.smartrecruiters.com/docs/rate-limiting) and does not offer the ability of listing applications and interviews. This means a lot of requests need to be made to backfill this behaviour (and allow it in the unified API), combined with the rate limits it can take some time to list / sync applications & interviews.

Due to these behaviours, the `interview` endpoint by default has a filter applied to only return interviews for candidates in the following status `INTERVIEW` `OFFERED` `HIRED` `TRANSFERRED`, filtering out candidates that are in `REJECTED` `WITHDRAWN` `LEAD` and `IN_REVIEW` status.

## Lever

| Error Code | Description         | Probable Cause                                                                                                                         | Remediation Steps                                                                                                                                                                  |
| :--------: | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|    `400`   | Invalid Request     | This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again. | Double-check the parameters you are sending (query parameters or body data)                                                                                                        |
|    `401`   | Unauthorized        | The credentials or scopes provided do not suffice to access this resource.                                                             | Verify the lever credentials in the integrations page per the [relevant documentation](https://hub.stackone.com/en/articles/7996595-enable-the-lever-stackone-partner-integration) |
|    `403`   | Forbidden           | The Lever account settings don't authorize the oauth app to perform the requested operation.                                           | Talk to a Super Admin on your Lever account to update your API settings.                                                                                                           |
|    `429`   | Too many requests   | Lever imposes a limit of the number of requests a client can make in a short time. Read more about our rate limiting here.             | Implement a retry strategy (you can do this easily via `retryConfig` of the StackOne `sdk`)                                                                                        |
|    `500`   | Server Error        | There was an error on Lever or StackOne's end.                                                                                         | Contact StackOne via your dedicated slack channel or [support@stackone.com](mailto:support@stackone.com)                                                                           |
|    `503`   | Service Unavailable | Lever is temporarily down for maintenance. Please retry your requests with exponential backoff.                                        | Implement a retry strategy (you can do this easily via `retryConfig` of the StackOne `sdk`)                                                                                        |

## Bullhorn (ATS)

Bullhorn's ATS system is a crossover with a traditional CRM based tool. It has relaxed validation rules that means some operations can fail silently or create records with invalid relationships.

It is possible to supply an invalid or missing `id` when creating `candidates/notes`. When you create a Note with an invalid/missing:

1. `candidate_id` - the note is still created in the BH db with the invalid reference. This means it's successful and retrievable but won't appear anywhere in the UI.
2. `author_id` - the author is defaulted to the api user `id`

## Workable

Candidates created without an associated application will be added to a generic talent pool that appears in the Workable UI. These candidates will not be returned in the API response as the provider does not support returning talent pool candidates at time of writing.

## Workday(LMS)

### Content

**Upsert**

Workday have 2 unique identifiers per item of content to help dedupe.

One of them is the `external_reference` in our model, the other is the content `title`.

When creating content, if either one of these identifiers exists in the system already then Workday will not allow the creation of the content.

In the upsert flow we will look to get content by both of the identifiers. If the `external_reference` matches an existing piece of content we will update the content by that identifier.

If the `external_reference` doesn’t match but the `title` matches we will update the existing content using the `title` as the identifier.

In this use case, the piece of content would be updated with the content data passed in that request, including the `external_reference`.

**Content in Workday**

Within Workday, a piece of externally hosted content only exists in the context of a course. As a result when we create content we also create a course wrapper which is given the same title and description as the content.

**Assumed Values**

There are some required values for Workday which don’t correspond to a field in our content model, so we apply these under the hood. They are:

**Lesson Order**

Within the context of a single piece of content, this is not applicable - so we assume this to be 1 if no value for order is passed in.

**Make Lesson Mandatory**

It is a requirement of creating a course within Workday that at least one piece of content within the course is mandatory - we apply this to the content by default.

**Registrable Status Reference**

This is a mandatory field and so we make this value ‘Open’ by default. Note that this is different from making content Active.

**Additional Quirks**

Workday doesn’t support an externally hosted `cover_image`, instead we must provide a base64 image string.

We handle this under the hood by downloading the provided image URL and deriving the image file name from either the metadata or the url string.

If this image download fails, the content create request will also fail.

**Rate-Limiting**

We haven’t explicitly come across rate limiting with Workday previously but we suggest making create content requests sequentially for better safety.

**Categories**

Workday content create requires the input of a pre-existing category in the customer Workday system.

In order to make this information available we have exposed a list and get endpoint so you are able to retrieve this information and apply it as necessary.

### Completions

For Workday - we allow the creation of using the `content_external_reference` that is a required field when you upsert content. This means that you will always have a reference to the content which matches the reference in the LMS system.

`content_id` is not a required field for creating a completion.

## SAP SuccessFactors (LMS)

### Content

**Upsert**

SAP has upsert behavior as default. We use `external_reference` as the only identifier to dedupe content.

**Content in SAP**

In order to create content in SAP we must also create a course wrapper. This holds some of the content metadata and we apply the same title, description and id to this course wrapper as the content.

**Active status on initial create**

If content is created initially with the status set to inactive then it will not show in the import menu (even though there is a filter to view ‘not active’ content).

As a result the content won’t be able to be manually imported.

If the content is already imported and the OCN synchronization is set up, and then it is set to inactive - it will show under the ‘not active’ filter and show as inactive in its imported form.

**Rate-Limiting**

For SAP when using the OCN there is a rate limit of 1 request every 5 minutes

It also has a limit of 1000 content items per request.

**Open Content Network**

We upload content to SAP via the Open Content Network (OCN) - this has a separate content management flow for content and completions from imported content that appears within the SAP hub.

Part of this flow is that when uploading content it is put into the OCN area of the system where it then needs to be manually imported to appear as available to consume for users.

Once the automatic OCN synchronization system is set up, the imported content will automatically update once updated are made through the api without requiring additional manual processing.

There is also some additional configuration required in order to get the OCN Content create flow working which are outlined in the connector guide docs.

**Assumed Values**

We make some assumptions on fields when uploading content

**Launch Method**

This is required as part of the content upload. We set this to browser under the hood as this is consistent with external content launch methods across other LMS platforms.

**Languages**

SAP allows the ability to upload the content title and description in multiple languages. When viewing the content from the dashboard it will only show the title if it has been added for the specific locale the user is in. So you should ensure you add the languages for all locales you are expected to serve.

<br />

### Completions

For SAP - we allow the creation of using the `content_external_reference` that is a required field when you upsert content. This means that you will always have a reference to the content which matches the reference in the LMS system.

`content_id` is not a required field for creating a completion.

## Go1 (LMS)

### Content

**Upsert**

We use the external\_reference to find content that already exists. If content already exists then we will update using `external_reference` as the identifier.

Otherwise we will create a new content item with the `external_reference` as the identifier.

### Completions

For GO1 - we allow the creation of using the `content_external_reference` that is a required field when you upsert content. This means that you will always have a reference to the content which matches the reference in the LMS system.

**Result**

When passing a source value for the result, the underlying system will only accept a boolean.

`content_id` is not a required field for creating a completion.


# Embedding the Integration Hub
Source: https://docs.stackone.com/guides/embedding-stackone-hub



Integrating multiple services into your web app is now easier with the StackOne Hub, which provides a streamlined way for your customers to authenticate and configure the [integrations enabled](/guides/managing-integrations) in your StackOne projects.

<div class="flex justify-center gap-4">
  <Frame>
    <img alt="StackOne Integration Hub (Listing)" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/05b5f07-app.stackone.com_accounts.png" class="border border-gray-300" />
  </Frame>

  <Frame>
    <img alt="StackOne Integration Hub (Credentials Form)" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/d10b5fe-app.stackone.com_accounts_1.png" class="border border-gray-300" />
  </Frame>
</div>

This guide will walk you through the process of embedding the StackOne Hub into your application whether you're using React (via the [@stackone/react-hub](https://www.npmjs.com/package/@stackone/react-hub) package) or by using directly the underlying StackOne "Connect" library.

<Accordion title="With React">
  ## Step 1: Install the StackOne React Hub Package

  First, add the @stackone/react-hub package to your project using either npm or yarn

  ### Using npm

  `npm install --save @stackone/react-hub`

  ### Using Yarn

  `yarn add @stackone/react-hub`

  ## Step 2: Implement a function to retrieve the connect session token

  The React Hub needs to retrieve a connect session token to be able to securely communicate with the StackOne Portal. This is achieved by making a POST request to StackOne API `/connect_sessions` endpoint.

  Since this involves sending the API Key and other sensitive data, the recommended approach is to make this request through your application backend avoiding the need for exposing credentials in the frontend code.

  As an example, assuming that the application backend already has that endpoint a function to retrieve the connection session token could be as simple as:

  ```typescript javascript
  export const retrieveConnectSessionToken = async ({ username, provider }) => {
    const payload = {
      originUsername: username, // eg: jane@customer.com (the username trying to connect)
      provider, // optional - (specifying a provider will make the stackone hub load directly the  provider's connection screen and bypass the integrations listing screen)
    };

    const headers = {
      'Content-Type': 'application/json',
    };

    const connectSessionResponse = await fetch(
      'https://your-application.com/stackone_connect_session', // your back-end implementation for forwarding the request with the relevant API key to StackOne's /connect_sessions endpoint
      {
        method: 'POST',
        headers,
        body: JSON.stringify(payload),
      },
    );

    const response = await connectSessionResponse.json();

    return { token: response.token };
  };

  ```

  This example is only calling the endpoint that will communicate with the StackOne API and getting the token from the response so that it can be used in the react hub hook in the next step.

  For instructions on how to build the backend endpoint that communicates with the StackOne API please refer to the guide to connect your backend with StackOne API.

  ### Customising the hub behaviour

  Per the [Connect Sessions](/platform/api-reference/connect-sessions/) documentation and the associated back-end implementation example [Connect your Backend with StackOne](guides/connect-your-backend-with-stackone), you can  specify a `provider` property so the integration hub will directly filter or load the given provider or category instead of displaying a list of all integrations enabled.

  ## Step 3: Create a Link Account Button

  Create a button component that users can click to link their accounts. The button will utilize the useStackOneHub hook to initiate the Connect flow.

  ```typescript Typescript
  import { useStackOneHub } from '@stackone/react-hub';

  const LinkAccountButton = () => {
    const { startConnect } = useStackOneHub();

    const startFlow = useCallback(async () => {
      const sessionToken = await retrieveConnectSessionToken({ username: 'jane@example.com' });
      startConnect({ sessionToken });
    }, [startConnect]);

    return (
      <button onClick={startFlow}>Connect Account</button>
    );
  };
  ```

  Your application is now ready to start connecting accounts\\\\\\!
</Accordion>

<Accordion title="Without React">
  ## Step 1 - install the connect script

  You should insert the a script tag wherever you intend to display the StackOne hub.

  This can be done one of two ways

  * Adding the following script in the \<body> of your page:

    ```html HTML
    <script src="https://app.stackone.com/stackone/connect.js"></script>
    ```
  * Alternatively you can also add the script tag via javascript, for example via the following code:

    ```javascript
    const script = document.createElement('script');
    script.src = 'https://app.stackone.com/stackone/connect.js';
    document.body.appendChild(script);
    ```

  ## Step 2 - Implement the function to generate a session token

  To use the Connect library, you will also need to generate a session token. Refer to the documented step [here](/guides/embedding-stackone-hub#step-2-implement-a-function-to-retrieve-the-connect-session-token).

  ## Step 3 - Use the connect library

  ```javascript JavaScript

  const connectSessionToken = await retrieveConnectSessionToken();

  // The code below will open the StackOne Hub
  // Depending on the session token generated - the hub can be opened on the listing page or directly on the set-up screen of a specified provider.
  // The onSuccess callback will be called if the user interacting with the StackOne Hub sucessfully links an account
  Connect.start({
    sessionToken: connectSessionToken,
    onSuccess: (e) => {
      console.log('> stackone - new account linking', e);
    }
  });
  ```
</Accordion>

<Accordion title="Customizing the hub style">
  You can add hub styling to the start options via the `styles` property:

  ```typescript Typescript
  // Example of styles object
  const styles = {
    inline: { // Removes the dropshadow and z-index from the iframe
      containerId: 'my-container-id', // Your page container where the iframe will be appended to
      height: '500px', // Height of the Hub
      width: '300px', // Width of the Hub
    },
    options: {
      back: false, // Removes the back arrow from the Hub
      close: false, // Removes the close button from the Hub
      bgColor: 'white', // The background color of the Hub (This only changes the background,
      									// the font color will remain the same, so be aware of that)
    },
  };
  ```

  ### Default look of the Hub

  <Frame>
    ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/b3d5dc92935d8c19d75075054e15452c7eba8553238ad3946689086481146982-image.png)
  </Frame>

  #### Customised Style Hub (with Inline and custom width)

  <Frame>
    ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/8d379164573ef8fd8909faee369d500342f105ce04a1c4bcb4ff986d033ee10d-image.png)
  </Frame>

  This can be very helpful if you want the hub to be inline on your page, disable back/close buttons, etc. All of these properties are optional so you can customize the best user experience for your users.
</Accordion>

## Generating a connect session token

Connecting with the StackOne API must be done server-side. This is required to keep your [API keys](/guides/api-keys) secure and prevent them from being exposed in the frontend code.

You will need a StackOne API Key to successfully request a token via the [Connect Sessions Endpoint](/platform/api-reference/connect-sessions/).

When using the API to generate the connect session token, several supported scenarios exist. The fields `origin_owner_id` and `origin_owner_name` are required, while `origin_username` is optional. If the `origin_owner_id`, `origin_owner_name`, and `provider` have been used previously, the existing account will be updated; otherwise, a new account will be created.

Additionally, you can add the following fields to control the behavior of the connect session token.

| Field       | Description                                                                                                                                                                        |
| :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| label       | A  label is a text field that can be used to store any string data against the account                                                                                             |
| category    | The hub page will open at the category selector (HRIS, ATS etc) where the user can go through the remaining steps to complete adding the new account.                              |
| provider    | The Hub page will open directly at the final stage where the user can enter the credentials and complete the last steps to complete adding the new account.                        |
| account\_id | If an existing account id is included in the connect session then the hub will open on the Edit Account page where the credentials can be updated and the account can be re-linked |

The following code demonstrates a basic implementation with all the required parameters:

<CodeGroup>
  ```javascript Javascript
  app.post('/stackone_connect_sessions', jsonParser, async (req, res) => {
    const STACKONE_API_KEY = 'YOUR_STACKONE_API_KEY';

    const headers = {
      Authorization:
        'Basic ' + Buffer.from(STACKONE_API_KEY + ':' + '').toString('base64'),
    };

    // optional - metadata to be associated with the connection
    const metadata = { source: 'my-backend' };

    const { originUsername, provider } = req.body;

    const payload = {
      origin_owner_id: 'customer-123', // The organization id of the customer in your system
      origin_owner_name: 'Acme Inc', // The organization name to easily identify the owner of the connected account in StackOne
      origin_username: originUsername, // eg: 'jane@customer.com' - an identifier for the user initiating the connection
      provider,
      metadata,
    };

    const requestOptions = {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        ...headers,
      },
      body: JSON.stringify(payload),
    };

    try {
      const responseWithToken = await fetch(
        'https://api.stackone.com/connect_sessions',
        requestOptions,
      );
      const { token } = await responseWithToken.json();
      res.send({ token });
    } catch (e) {
      res.status(500).send('error when trying to fetch session');
    }
  });
  ```

  ```python Python
  from flask import Flask, request, jsonify
  import requests
  import json
  import base64

  app = Flask(__name__)

  @app.route('/stackone_connect_sessions', methods=['POST'])
  def stackone_connect_sessions():
      STACKONE_API_KEY = 'YOUR_STACKONE_API_KEY'
      headers = {
          'Authorization': 'Basic ' + base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode(),
      }
      metadata = {'source': 'my-backend'}
      req_data = request.json
      originUsername = req_data['originUsername']
      provider = req_data.get('provider', None)

      payload = {
          'origin_owner_id': 'customer-123',
          'origin_owner_name': 'Acme Inc',
          'origin_username': originUsername,
          'provider': provider,
          'metadata': metadata
      }

      try:
          response = requests.post(
              'https://api.stackone.com/connect_sessions',
              headers={**headers, 'Content-Type': 'application/json'},
              json=payload
          )
          token = response.json().get('token')
          return jsonify({'token': token})
      except Exception as e:
          return ('error when trying to fetch session', 500)

  if __name__ == '__main__':
      app.run(debug=True)
  ```

  ```csharp C#
  using Newtonsoft.Json;
  using Microsoft.AspNetCore.Mvc;
  using System;
  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  [ApiController]
  [Route("[controller]")]
  public class StackOneConnectSessionsController : ControllerBase
  {
      [HttpPost]
      public async Task<IActionResult> Post([FromBody] dynamic reqBody)
      {
          string STACKONE_API_KEY = "YOUR_STACKONE_API_KEY";
          string authHeader = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{STACKONE_API_KEY}:"));

          HttpClient client = new HttpClient();
          client.DefaultRequestHeaders.Add("Authorization", $"Basic {authHeader}");

          dynamic payload = new
          {
              origin_owner_id = "customer-123",
              origin_owner_name = "Acme Inc",
              origin_username = reqBody.originUsername,
              provider = reqBody.provider,
              metadata = new { source = "my-backend" }
          };

          try
          {
              var response = await client.PostAsync(
                  "https://api.stackone.com/connect_sessions",
                  new StringContent(JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json")
              );
              dynamic data = JsonConvert.DeserializeObject(await response.Content.ReadAsStringAsync());
              return Ok(new { token = data.token });
          }
          catch (Exception)
          {
              return StatusCode(500, "error when trying to fetch session");
          }
      }
  }
  ```
</CodeGroup>

If the combination of origin\_owner\_id and origin\_owner\_name for a given provider has not previously been used this will create a new Account. If the origin\_owner\_id and origin\_user\_name values have already been used for a given provider then the existing account will be updated.

In summary, the endpoint will send a POST request to the StackOne API `/connect_sessions` endpoint with the credentials and the request data. If the request is successful, it will respond with an object that contains a `token` property. This token will be returned and can then be used by the frontend to connect the [React Hub](/guides/embedding-stackone-hub) with your application. When the frontend process is completed an Account will either be created or updated.

<Warning>
  The `origin_owner_id` should always be set via server-side logic and not be passed through directly via the client-side request.
</Warning>

<Accordion title="Advanced Use Case">
  For most scenarios the simple use case described above should meet all requirements. To support some more advanced use cases we have introduced a new *multiple* flag. The multiple flag allows more control over the upsert behaviour on Accounts. In the simple use case above we saw how using an unused combination of origin\_owner\_id and origin\_owner\_name for a given provider would create a new Account but if we reused those values or specified an existing account\_id then the existing account would be updated.

  In some limited use cases you may wish to have multiple connected accounts for a given provider that are configured with the same origin\_owner\_id and origin\_owner\_name. If this behaviour is desired then you need to pass the \_multiple\_ flag set to true when the Connect Session is created. If the multiple flag is set then then any existing account with the same settings will be left untouched and a new account will be created.

  <table>
    <thead>
      <tr>
        Fields

        Details Used Before?

        Description

        Account Action
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>
          `origin_owner_id`
          `origin_user_name`
          `origin_name`
          `category` (optional)
          `provider` (optional)
        </td>

        No

        <td>
          A new account will be created. If the `category` is specified, the hub will open in the provider selection screen; otherwise, it will open with the selected provider.
        </td>

        Create
      </tr>

      <tr>
        <td>
          `origin_owner_id`
          `origin_user_name`
          `origin_name`
        </td>

        Yes

        <td>
          The existing account will be opened in edit mode.
        </td>

        Update
      </tr>
    </tbody>
  </table>

  ### Customising the hub behaviour

  Per the [Connect Sessions](/platform/api-reference/connect-sessions/) documentation, you can also specify a `provider` or `categories`property so the integration hub will directly filter or load the given integration (`provider`) or `categories`.

  The values accepted in the `provider` property can be found in the [Supported Providers](https://app.stackone.com/field_coverage) list in the `Provider Key` column.

  If the `provider` is left undefined, the StackOne integrations hub will display a list of all integrations enabled for the project associated with the given API key.
</Accordion>

<Warning>
  Any provider specified when generating the connect session token must be enabled in the [integrations page](https://app.stackone.com/integrations) of the associated project.
</Warning>


# Expression language syntax
Source: https://docs.stackone.com/guides/expression-language-syntax

Custom unified fields use an expression language that can be used to create more complex field mappings

There are three types of expressions supported:

### JSON Path Expressions

When the expression starts with `$`, it is treated as a JSON Path expression and will be evaluated as such.

#### JSON Path Syntax

| JSON Path              | Description                                                        |
| ---------------------- | :----------------------------------------------------------------- |
| `$`                    | The root object                                                    |
| `.`                    | Child operator                                                     |
| `@`                    | The current object                                                 |
| `*`                    | Wildcard. All elements in an array, or all properties of an object |
| `..`                   | Recursive descent                                                  |
| `[]`                   | Subscript operator                                                 |
| `[,]`                  | Union operator                                                     |
| `[start : end : step]` | Array slice operator                                               |
| `?(expression)`        | Filter expression                                                  |
| `()`                   | Script expression                                                  |

Examples:

```js
// Given the context: { user: { name: "John", age: 30 }, "info/email": "info@email.com" }
'$.user.name'         // Returns "John"
'$.user.age'          // Returns 30
'$.user[*]'           // Returns ["John", 30]
'$["info/email"]'     // Returns "info@email.com"
```

For more information on JSON Path syntax, refer to the original [JSON Path documentation](https://goessner.net/articles/JsonPath/).

### JEXL Expressions

This kind of expression is enclosed in double brackets `{{expression}}`. It supports variables and operators.

#### Operators

| Operator | Description                    |
| :------- | :----------------------------- |
| `!`      | Logical NOT                    |
| `+`      | Addition, string concatenation |
| `-`      | Subtraction                    |
| `*`      | Multiplication                 |
| `/`      | Division                       |
| `//`     | Floor division                 |
| `%`      | Modulus                        |
| `^`      | Exponentiation                 |
| `&&`     | Logical AND                    |
| `\|`     | Logical OR                     |
| `==`     | Equal                          |
| `!=`     | Not equal                      |
| `>`      | Greater than                   |
| `>=`     | Greater than or equal          |
| `<`      | Less than                      |
| `<=`     | Less than or equal             |
| `in`     | Element of string or array     |
| `? :`    | Ternary operator               |

Examples:

```js
// Given the context: { x: 10, y: 5 }
'{{x + y}}'                  // Returns 15
'{{x * 2}}'                  // Returns 20
'{{x > y}}'                  // Returns true
'{{x == 10 ? "yes" : "no"}}' // Returns "yes"
'{{x in [1, 2, 3]}}'         // Returns false
'{{x != y}}'                 // Returns true
```

#### Identifiers

Identifiers can be used to reference variables in the context.

```js
// Given the context:
// { 
//     name: {
//         first: "John",
//         last: "Smith"
//     },
//     jobs: ["Developer", "Designer"]
// }
`{{name.first}}`          // Returns "John"
`{{jobs[1]}}`             // Returns "Designer"
```

#### Collections

Collections, or arrays of objects, can be filtered by including a filter expression in brackets.

```js
// Given the context:
// {
//     users: [
//         { name: "John", age: 30 },
//         { name: "Jane", age: 25 }
//     ]
// }
`{{users[.name == "John"].age}}` // Returns 30
`{{users[.age > 25].name}}`      // Returns ["John"]
```

### String Interpolation

To simplify strings usage, a more straightforward syntax is provided for string interpolation of variables using the `${var}` syntax.

Examples:

```js
// Given the context: { name: "John", age: 30 }
"Hello ${name}"       // Returns "Hello John"
"User is ${age}"    // Returns "User is 30"
```

Note: If the expression is a string without any of the patterns described above, it will be returned as is.

```js
// Given the context: { name: "John", age: 30 }
"Hello world"       // Returns "Hello world"
```

For more information on the JEXL syntax, refer to the [JEXL Syntax documentation](https://commons.apache.org/proper/commons-jexl/reference/syntax.html).


# Introduction
Source: https://docs.stackone.com/guides/field-mapping

Custom Unified Fields enable users to create and unify bespoke fields to extend the existing Unified API models & resources.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/81fc298-Field_Mapping_Cover_Image.png)
</Frame>

# Overview

Custom Unified Fields enables you to create bespoke fields that and implement them across any connector already supported on the StackOne platform.

This gives you greater flexibility and control over any unified API and integrations available on StackOne, allowing you to tailor each integration to meet your specific product needs.

➡️ Custom unified fields can only leverage data that is already returned by underlying integrations. You cannot fetch additional requests or use data not already present in the underlying provider requests that StackOne default unified operations perform under the hood.

➡️ Custom unified fields are, like any other unified fields, real-time by default meaning that the data returned by the StackOne unified API will reflect the latest values from the source fields.

> 🙋 Reach out to StackOne's support to get Custom Unified Fields enabled for your organization

# Use-cases

Use-cases are broad and entirely dependant on the product and feature you're building and what type of integrations you're using, some example of custom unified fields may be:

* A new `emergency_contact_number` to be retrieved when listing [Employees](/hris/api-reference/employees/list-employees) (HRIS)
* A multi\_factor\_authentication` `boolean\` variable on IAM [Users](/iam/api-reference/users/list-users) on top of the existing array (IAM)
* Support for an LMS [Content](/lms/api-reference/content/list-content) `label` surfacing label ant tag data from LMS systems that support it (LMS)

# Nomenclature:

We'll refer throughout the guides and user interface to various properties

* **Custom Unified Field:** A user-defined field that can be mapped and unified across various integrations by a Project Admin
* **Variable Key:** The unique identifier for the custom field.
* **Display Name:** The user-friendly name for the custom field.
* **Variable Type:** The data type of the custom field (currently only primitive data types are supported).
* **Field Mapping:** The process of linking a custom unified field to fields from different HR systems.

# Creating and managing fields

Project admins can access the field mapping section by clicking on ["Field Mapping"](https://app.stackone.com/field_mapping) in the left-hand menu.:

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/e9690c5-CleanShot_2024-07-31_at_22.21.352x.png)
</Frame>

To create the Custom Unified Field, you will need to specify the necessary details such as the Variable Key (which will be the actual property key in the returned JSON, an associated Type and a name & description to go with it (meant more for documentation and readability purposes as these latter two will not be returned in the request's response). All these details can be updated later via the `edit` button.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/e240ef2-CleanShot_2024-07-30_at_15.24.502x.png)
</Frame>

### Limitations

* **Data Types:** Only primitive data types (string, number, boolean) are supported. Values will be typecasted when possible.
* **Operations:** Initially, only read operations (List and Get) are supported. Write operations will be introduced in future updates.

# Future capabilities of custom unified fields

Currently, Custom Unified Field mapping allows you to pull and use information that is already returned by the provider. Here's what we'll enable and add in future release

* Ability to update and add underlying provider requests so you can leverage more data from the underlying tools
* Creation of brand new operations and unified models
* Operations, formulas and functions so you can create more complex, derived fields and values.
* Account specific overrides so you can have different mapping per account and leverage tenant-based custom fields for specific field mappings when relevant

# FAQ

**Why can't I see the `Field Mapping` section in the side-menu?**\
The feature is only available to Project Admin and needs to first be enabled by StackOne (reach out to StackOne support for it to be enabled for your organization)

**Why can't I see the unified model I want to add custom unified for in the `Field Mapping` page?**\
Only pre-selected unified models have been enabled, if you would like to access another model available in our API but not visible in the custom unified fields section, reach out to our support team.

**How can I map a complex object like an array, enum or object?**\
This is currently not supported in the beta version but will come shortly with the global release of this feature.


# Integration Field Mapping
Source: https://docs.stackone.com/guides/integration-field-mapping

Define what source fields, the custom unified field will use for each integration.

Once you've created a [custom unified field](/guides/field-mapping), you need to define the "mapping" for each of the integration you want this field to be enabled and usable for.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/aab065d-CleanShot_2024-07-30_at_15.54.262x.png)
</Frame>

Adding an integration field mapping is done via the *integration-level* mapping tab after selecting a specific custom unified field.

<Info>
  Only integrations configured and enabled on the [integrations](https://app.stackone.com/integrations) page can be mapped.
</Info>

# Configuring the mapping

Although it's possible to map without using an underlying linked account, it's always advised to use a connected linked account (eg. a sandbox account) to have the most realistic view of what type of properties and fields may be available on the underlying integration.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/e8ca181-CleanShot_2024-07-30_at_15.20.562x.png)
</Frame>

## Preview & Test

1. **Preview Fields:** *(optional)*
   * Select a source from the dropdown list to pull a sample set of field data.
   * Click on "Request" to preview the data.
   * Example preview JSON response:
     ```json
     {
       "employees": [
         {
           "id": "5",
           "firstName": "Anna",
           "lastName": "Skywalker",
           "terminationDate": "2024-05-28"
         }
       ]
     }
     ```
2. **Field Mapping Steps:**
   * **Step 1:** Select the source field you want to map from the integration.
   * **Step 2:** Enter the target custom field name.
   * **Step 3:** Use the expression language syntax to point to the relevant integration field
     * Example: `$.employees.output.data.terminationDate`

***

### Tips & Tricks

#### Mapping array values

Some origin data will return a list of resources instead of a single resource (eg: all the documents instead of a specific document). In this case, you should make sure to use one of the provided default variables (eg: `id`) to find the element in the array that matches the ID.

#### Expression language

Custom unified fields can be mapped using the StackOne's expression language. This language supports JSON path syntax, JEXL expressions for more complex use cases or simple string interpolation. For more information about all the expression language capabilities please refer to the [Expression language syntax documentation](/guides/expression-language-syntax).

***

## Additional Features:

* **Typecasting:** Values will be automatically typecasted to the defined variable type when possible (eg: if the variable type is a `string` but the underlying integration returns a `number` the number will be return as a string and vice-versa).
* **Viewing Mappings:** : once an integration mapping is configured, the source will be visible directly in the integration-level mapping list:

  <Frame>
    ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/787495d-CleanShot_2024-07-30_at_16.09.482x.png)
  </Frame>

# Using a Custom Unified Field

Once you have configured an integration custom field mapping you will need to make sure the field is enabled:

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bf3b4ef-CleanShot_2024-07-31_at_19.52.012x.png)
</Frame>

You can retrieving the data via any `GET` or `LIST` API request for the model you created the field on:

The unified custom field will be embedded in an property called `unified_custom_fields`.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/3dc2314-CleanShot_2024-07-31_at_20.03.512x.png)
</Frame>

<Info>
  When using SDKs (ie: Typescript SDK) the property may be camel cased instead (ie: `unifiedCustomFields`). The SDK will not have types for the individual properties contained in this object given it is fully customizable.
</Info>


# Making Your First API Request
Source: https://docs.stackone.com/guides/making-your-first-api-request

Learn how to make your first API request with StackOne

## Overview

You've recently received StackOne access and want to initiate your first <Tooltip tip="API - Application Programming Interface is simply software that sends information bidirectionally between a website or app and a user">API</Tooltip> call using our <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip>. As an introduction to the StackOne Unified API, you've tested account connection through the StackOne Dashboard.

Now, you want to integrate a specific provider into your existing application and test the integration. In this guide, you will learn how to:

* [List Applications for a Greenhouse Account](#ats-list-applications-in-greenhouse)

* [Get a Specific Contact from a HubSpot Account](#crm-get-contact-in-hubspot)

* [Create an Employee in a BambooHR Account](#hris-create-employee-in-bamboohr)

## Prerequisites

1. [**API Key created in StackOne Dashboard**](./api-keys) and copied to a secure location

2. Required provider integration enabled

3. Account linked successfully

4. (Optional) Use an [SDK or Postman](./stackone-api-sdks)

## Getting Account ID

1. Specify the request type, URL, and API Key in the Authorization section (append to the header). <Tooltip tip="cURL - Client URL is a command-line tool that developers use to transfer data to and from a server">cURL</Tooltip> example:

```curl
   curl --request GET
        --url https://api.stackone.com/accounts
        --header 'accept: application/json'
        --header 'authorization: Basic your_api_key'
```

1. To filter results by a specific provider account (e.g., <Tooltip tip="ATS - Applicant Tracking Systems help companies match candidates to their recruitment and hiring goals">ATS</Tooltip> Greenhouse), define the `provider` parameter:– `provider=greenhouse`– `provider=hubspot`– `provider=bamboohr`

2. From the `/accounts` API call response, copy the `id` value.

### ATS: List Applications in Greenhouse

1. Specify the List Applications URL and header details:– [`https://api.stackone.com/unified/ats/applications`](https://api.stackone.com/unified/ats/applications)– `x-account-id:<id_from_Accounts_call>`

   <Note>
     Note:

     Authorization header remains the same
   </Note>

2. The response will contain a collection of existing applications with crucial data including:– Application ID– Candidate ID– Job ID– Location ID– Status– Created and Updated timestamps

3. (Optional) Use the data from the previous step to create new applications by making POST requests via the API.

### CRM: Get Contact in HubSpot

1. Specify the List Contacts URL and header details:– [`https://api.stackone.com/unified/crm/contacts/`](https://api.stackone.com/unified/crm/contacts/)– `x-account-id:<id_from_Accounts_call>`

2. Select the required contact from the contacts collection and copy its ID.

3. Include the ID in the URL path.

4. The response will contain all available data for the specified contact, including:– First Name, Last Name– Company Name– Email(s)– Phone Number(s)– Associated Account ID– Created and Updated timestamps

### HRIS: Create Employee in BambooHR

1. Specify the List Employees URL and header details to see a sample employee array:– [`https://api.stackone.com/unified/hris/employees`](https://api.stackone.com/unified/hris/employees)– `x-account-id:<id_from_Accounts_call>`

2. In a separate tab, open a POST method request with the same URL, Authorization, and `x-account-id` header.

3. Specify employee details in the request body, for example:

```json
{
  "first_name": "John",
  "last_name": "Doe",
  "name": "John Doe",
  "display_name": "Dr. John Doe",
  "work_email": "john@stackone.com",
  "job_title": "Consultant",
  "gender": {
    "value": "male"
  },
  "ethnicity": {
    "value": "white"
  },
  "marital_status": {
    "value": "single"
  },
  "employment_type": {
    "value": "full_time"
  },
  "employment_contract_type": {
    "value": "full_time"
  },
  "employment_status": {
    "value": "active"
  },
  "home_location": {
    "country": {
      "value": "AF"
    },
    "state": {
      "value": "AD-07"
    }
  },
  "work_location": {
    "country": {
      "value": "AF"
    },
    "state": {
      "value": "AD-07"
    }
  }
}
```

1. Upon successful creation, you'll receive a 🟢 `201 Status Code` with the message "Record created successfully" and its timestamp.

2. (Optional) To verify the record creation, modify the GET request from step 1 to include the newly created Employee ID.

## References

1. [List Accounts](../platform/api-reference/accounts/list-accounts)

2. [List Applications](../ats/api-reference/applications/list-applications)

3. [Create Application](../ats/api-reference/applications/create-application)

4. [Get Contact](../crm/api-reference/contacts/get-contact)

5. [Create an Employee](../hris/api-reference/employees/creates-an-employee)

6. [Integrations List](https://app.stackone.com/integrations)

7. [Libraries & SDKs](./stackone-api-sdks)


# Managing Integrations
Source: https://docs.stackone.com/guides/managing-integrations

Enable, disable and manage integrations for any StackOne Project

The [*Integrations*](https://app.stackone.com/integrations) section of the StackOne dashboard allows you to manage integration (aka `provider`) for a [StackOne Project](./managing-projects).

On the integrations page, you can:

* **View** the list of all integrations for all the categories supported by StackOne (eg. `HRIS` `ATS` `IAM` `CRM` `Marketing` and `LMS`. Some integrations and categories are only available based on your plan/contract. If you do not see a category or integration that you would like, contact support manager
* **Enable**,  configure and disable integrations.
* Quickly \*\*access \*\*linked accounts and logs related to the integrations

## Integrations Listing

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/62ef27d-CleanShot_2024-05-02_at_00.37.002x.png)
</Frame>

### Enabling and disabling integrations

**Setting up** an integration for the first time  `confirm` will automatically set its state as `enabled`, meaning it will be displayed in the Integrations Hub and you will be able to retrieve [Connect Sessions token](/platform/api-reference/connect-sessions/) with the associated provider key.

When **disabling** an integration by toggling the radio button, a warning will appear. Note that disabling an integration with accounts linked for it will make all these accounts go into an `inactive` status and API request to these accounts will not be permitted. You will be able to switch any integration back to an **enabled** state just as easily, which will reset all associated linked accounts to an `active` status.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/7e20854-CleanShot_2024-05-02_at_01.10.432x.png)
</Frame>

<Note>
  Integration settings are scoped to a specific project. If you need an integration to be configured on multiple StackOne projects you will have to configure for all individual projects.
</Note>

## Configuring an integration

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/487568b-CleanShot_2024-05-02_at_00.50.422x.png)
</Frame>

When setting up or updating an integration you are configuring a specific **authentication type**. The authentication type decides what will be the process for your end-user to link their account for that provider, specifically which details/credentials they will need to submit.

In most instances you will see `API Key` or `Basic Token` in which case the end-user will need to generate the required secret (eg. [Ashby](https://hub.stackone.com/en/articles/7727335-ashby) or [Hibob](https://hub.stackone.com/en/articles/8233374-hibob-service-user-authentication)). For other integrations, you may have a choice of `OAuth` (and similar, eg. `OIDC`) in which case, your user may experience a more streamlined login-like flow (eg. [Lever](https://hub.stackone.com/en/articles/7992510-lever) or [Hubspot](https://hub.stackone.com/en/articles/8005663-hubspot).

### Integrations with OAuth-based authentications

Some Integrations will prompt for  Oauth based fields such (commonly `Client ID` & `Client Secret`).

Although you can use StackOne-provided secrets this may mean your end-user journey will see StackOne's branding (ie. StackOne's logo or name) when linking an account. StackOne can assist you in retrieving your own oauth / partner credentials for such integrations - contact StackOne's support team via your channel of choice to request additional assistance.

<Info>
  When configuring an oauth application with a provider, you may be asked for a Callback or Redirect URI. Make sure to use`https://api.stackone.com/connect/oauth2/{provider key}/callback` (replace `{provider key}` with the actual key, for example: `hubspot` or `bamboohr`).
</Info>


# Managing Projects
Source: https://docs.stackone.com/guides/managing-projects

Page functionality described in detail

## Overview

A StackOne Project is a logical container within the StackOne platform designed to isolate and manage API keys, integrations, and associated data according to your organizational needs.

Each project serves as an independent workspace, allowing you to segment user access and integrations by various criteria such as geographical data storage requirements or different development environments.

For example, you may have:

* a separate project where data of linked accounts will be processed in EU and another one where for data that should be processed in US

* a separate project matching your development lifecycle (environments) such as dev, staging, production

* additional temporary projects for an individual engineer or QA member in order to work in isolation

* a separate project where data of linked accounts will be processed in EU and another one where for data that should be processed in US

* a separate project matching your development lifecycle (environments) such as dev, staging, production

* additional temporary projects for an individual engineer or QA member in order to work in isolation

### Creating a new project

To create a new project, In the left-side panel, click the top left of the menu and select *Create New Project*.
Alternatively, you can directly open [https://app.stackone.com/project/new](https://app.stackone.com/project/new).
To create a new project, In the left-side panel, click the top left of the menu and select *Create New Project*.
Alternatively, you can directly open [https://app.stackone.com/project/new](https://app.stackone.com/project/new).

<Note>
  Only users with the Organization Admin role can create new projects
</Note>

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/5ea4e3a-CleanShot_2024-07-16_at_23.42.432x.png)
</Frame>

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/create-new-project.png)
</Frame>

#### Project Regions

The chosen region will determine where any data related to the project will be stored or processed.

This ensures that any data processed and transferred stays within the specific region, meeting your customers' data locality requirements. If you need a new region, our unified API can be deployed within a week. Contact your StackOne account manager for more details.

StackOne currently offers the following region:

| Area                             | Region                                | Associated  Data Center | Availability                    |
| :------------------------------- | :------------------------------------ | :---------------------- | :------------------------------ |
| Europe                           | 🇮🇪 Ireland (Dublin)                 | AWS EU-WEST-1           | ✔️  Available for all customers |
| Europe                           | 🇬🇧 United Kingdom (London)          | AWS EU-WEST-2           | ➕ add-on                        |
| North America                    | 🇺🇸 United States (Northern Virgina) | AWS US-EAST-1           | ✔️ Available for all customers  |
| APAC                             | 🇦🇺 Australia (Sidney)               | AWS AP-EAST-2           | ⏳ Coming soon (ETA  Q2 2025)    |
| Custom Regions or hybrid hosting |                                       |                         | Available upon request          |

### Viewing and switching Projects

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/list-projects.png)
</Frame>

You can access the list of project at any time by clicking on the top left of the menu as indicated in the screenshot. This will list all projects you are allowed to access.

Organization Admins can see all projects by organization with `basic` role will only see project they have been added to.

The region associated with the project is automatically listed at the right of the project (eg. `(EU1)` means the EU region was selected while `(US1)` means this project's data is processed/hosted in the US).

### Project settings

#### Updating project details

You can update some project details via the `Details` section. Note that the region of a project cannot be updated but you can change its name at any time without impacting any linked account or other settings.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/project-details.png)
</Frame>

#### Managing Project Members

Managing project members can be done through the project settings interface. Here, you can add, disable, remove members or modify their project-level role.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/project-members.png)
</Frame>

<Note>
  There are 2 Access Roles available:

  * Viewer 👶- can only review Dashboard, Accounts, and existing Integrations' configuration. They cannot access API keys, nor edit or delete integrations, webhooks, and project settings.
  * Project Admin 👨‍💻- can manage Accounts, use the request tester, enable or disable integrations, create new API Keys, create and update Webhooks & update the Project Settings.
</Note>

#### Advanced logs

The Advanced logs settings can be toggled ON/OFF for your project, with options to set both an expiration date for the setting itself and a retention period for the logs. After the retention period, logs will be automatically deleted.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/project-advanced-logs.png)
</Frame>

<Note>
  Log data will be stored for the duration selected in your settings. Once the retention period expires, the logs will be automatically removed. Any changes to the retention period will only apply to new logs - existing logs will keep their original retention period.
</Note>

#### Deleting a project

Projects can be permanently deleted from the Project Settings page, with a 7-day grace period during which the deletion can be reversed by contacting StackOne support.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/project-delete.png)
</Frame>

<Note>
  * Deleting a project will schedules the project (and everything contained within it including every linked account) for permanent deletion within 7 days.
  * If you've accidentally deleted a project and you are still within the 7 days grace period, reach out to StackOne's support to cancel the deletion
</Note>


# Managing your Organization
Source: https://docs.stackone.com/guides/managing-your-organization

Detailed instructions

## Overview

StackOne allows adding multiple members inside your organization. You can invite all necessary users by specifying their email addresses and selecting the access role.

**Table of contents**:

1. [Manage team](#manage-team)
2. [Authentication & Security logs](#authentication-security-logs)
3. [Connection with Project settings & Accounts](#connection-with-project-settings-accounts)

## Manage Team members

If you have been assigned the "Org Admin" role, you will see an additional section, "Organization," in the left-side panel. For role "Basic", the section is hidden.

With "Org Admin" role, you can:

* Add a new member, as well as resend or cancel a previously sent invitation (via the `invites` tab)
* Change a user's role
* Disable/Enable or Delete any other organization user
  * Unlock locked user accounts (eg. if the account has been locked for failed login attempts)
  * Reset another user's multi factor authentication
* Create and access any project
* View and update additional organization security settings

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/3329ca2-CleanShot_2024-07-16_at_22.43.382x.png)
</Frame>

## Authentication & Security logs

As an admin user, you can access organization wide security settings by clicking on `security` upon clicking on your user.

The **Security** page allows you to enable OTP (One Time Password) MFA (Multi Factor Authentication) for all users currently inside the Organization and for any future users that will be added.

### Setting Up MFA

Once enabled, if you yourself haven't enabled MFA, you will be prompted to configure MFA for your own account. You can scan the QR code or enter the Authentication Secret manually using any authenticator app supporting Time-based One-Time Password (eg. Google Authenticator or Microsoft Authenticator, or password managers such as 1Password or Bitwarden).\
After successfully adding it your authenticator of choice, enter the Authenticator Code from the Auth app and click Confirm.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/c0822bc-CleanShot_2024-07-20_at_18.53.002x.png)
</Frame>

<Warning>
  Important:

  All organization members that have not yet already enabled multi factor authentication will be required to do so the next time they log in the platform.
</Warning>

### Security Logs

The **[Security Logs](https://app.stackone.com/organization/security_logs)** tab shows a log of every log-in attempts (success or failures). This allows you to monitor users' login activity to identify potential authentication issues and help meet your compliance & audit requirements.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/a67ac2d-CleanShot_2024-07-20_at_18.57.572x.png)
</Frame>

### Connection with Project settings & Accounts

Organization admins can also [Create Projects](/guides/managing-projects). For each project created, project admins can decide who from their organization can access that project.

For example, one user can have a `basic` organization role but be made `Project Admin` on any project within the organization.


# Dashboard Overview
Source: https://docs.stackone.com/guides/overview

A basic introduction to the dashboard, logging in etc

## Overview

🎆 Hooray! You've got access to the StackOne platform. The first page that loads on any project is the  [Dashboard](https://app.stackone.com/) page. This is the place to see the activity of your StackOne project at a glance, including requests made to StackOne's Unified API (or via webhooks). The main goal of the dashboard is to monitor the health and growth of your integrations.

Once you start using various [available StackOne integrations](https://www.stackone.com/integrations), the dashboard will populate the data respectively.

## Dashboard graph

You can configure multiple projects, and each will have its own dashboard statistics.

<Frame>
  ![Dashboard Overview Page](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/dashboard_overview_page.png)
</Frame>

By default, the API requests period is selected as 1 month from the current date. You can also select a custom range – last day, 7 days, 90 days, or any desirable date range from the calendar view.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/e4c1b3c-image3.png)
</Frame>

The graph table view shows the total number of API requests to StackOne's Unified API which also include the total number webhook requests.

* 🟢 Successful count, HTTP response code 200 or 201 (200s)

* 🔴 Failed count, any request which returned an error status code (400s or 500s)

You can review detailed information by hovering over individual bars in the chart. You can change the granularity of the data you're looking at via the relevant dropdown to view `hourly`, `weekly` or `monthly` data points.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/5e518c2-image4.png)
</Frame>

<Info>
  Additional Info

  The graph will count requests made to one of the supported unified API endpoint regardless of the source of the request as long as it was properly authenticated. This means requests made via [Postman requests](/guides/using-postman), the docs.stackone.com API Reference test UI, or any request made via the [request tester in the accounts page](https://app.stackone.com/accounts) will also be included within the graph.
</Info>

## Linked Accounts & Integrations

**Linked Accounts** shows the graph of active configured accounts in total. The graph and the delta number are for the last 7 days.

**Integrations** section beneath the main graph shows the list of all providers for which there is at least 1 linked account. Since you can enable or disable particular providers via the [integrations page](https://app.stackone.com/integrations), the counter shows the **In-Use**/Enabled number.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/eec4203-image5.gif)
</Frame>


# Pagination
Source: https://docs.stackone.com/guides/pagination



## Overview

StackOne's <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip> allows paginating the API requests. Pagination is a modern way to fetch the data in bulk. Iterating through thousands of data pages can be done using the advanced optional `next` parameter.

It is often called cursor pagination.

## Mechanism

The legacy approach of StackOne API was to pass `page` parameter to identify which page of data has to be returned in response. Now, when making the first API request and if the response contains over 25 records, you will get `next` value of a **string** type. This property can be passed as a query string parameter for subsequent requests until the `next` value becomes NULL.

## Sample scenario

For example, you want to [list all employees](../hris/api-reference/employees/list-employees) for the BambooHR integration. You have around 525 employees configured. In such a case, StackOne returns the `next` parameter string value on the first request. Then, you can iteratively get the new value of `next` parameter to get all the remaining employee records.

<iframe width="100%" height="500px" src="https://demo.arcade.software/AxLa6TppmtNl1ZrP2Lbu?embed" title="StackOne - Pagination" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen allow="clipboard-write" />

## Sample response

In the response payload, you can find the `next` cursor.

```json
"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]
```

Once the cursor reaches the end of the data list, both values become NULL.

## Page Size

By default, the `page_size` parameter is set to 25 results per page. You can increase page size to up to 100. If fewer records remain in the underlying connected provider than a given page\_size, you will not receive a `next`  cursor value on the next request.

For example, if you have 17 records in total, all of them will be shown on one page with `next` parameter being empty. Then you specify the `page_size` = 10, you'll get the `next`value. If you use this `next` value, you will get a stripped array of the last 7 records.

<Frame>
  ![Bypassed Records scenario](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/cd9e2c8-pagination_stripped.gif)
</Frame>


# Rate Limiting
Source: https://docs.stackone.com/guides/rate-limiting



## Understanding Rate Limiting

In the context of APIs, **rate limiting** controls how many requests a client can make to a service in a specified period of time. It's a way of ensuring that individual users or services don't monopolize resources by making excessive or unnecessary requests. Rate limiting is especially important for shared services or public APIs where multiple users may be accessing the same resources.

When a service reaches its rate limit, it will typically respond with a **429 Too Many Requests** HTTP status code, indicating that the client needs to wait before retrying their request.

## StackOne's Rate Limiting Policy

At StackOne, we impose rate limits on API keys to ensure fair access to the API and maintain the performance and reliability of our systems. Each API key is limited to a maximum of **1000 requests per minute**. This means that any API key making more than 1000 requests in a 60-second window will receive a rate limit response.

<Info>StackOne's current rate limit is 1000 requests per minute. Please note that this rate limit may be adjusted in the future as needed.</Info>

### What Happens When You Hit the Rate Limit?

If your API key exceeds the rate limit, StackOne will return a standard **429 Too Many Requests** response. This response indicates that you have hit the rate limit and need to wait before sending more requests.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

The Retry-After header is included in the response when a rate limit is triggered. It provides guidance on how long the client should wait before making a subsequent request. The Retry-After value can be expressed either as a value in seconds or as a specific date/time. At StackOne we will return the value in seconds.

## Handling Rate Limiting in Your Application

To properly handle rate limiting, you need to read the 429 response code and the Retry-After header in your application, then implement backoff logic to pause and retry the request after the specified wait time.

If you consistently hit the rate limit, consider optimizing your API usage, such as by caching responses or batching requests, to reduce the number of calls made.

For more information on handling rate limits or troubleshooting specific issues, feel free to reach out to StackOne support.

[^1]: My reference.


# Request Logs
Source: https://docs.stackone.com/guides/request-logs

Page functionality described in detail

StackOne registers relevant information of requests made to the connected provider to fulfill any Unified API requests it receives. This can be useful for:

* Debugging issues with a particular account or integration
* Auditing the operations that StackOne performs under the hood

The [Request Logs](https://app.stackone.com/request_logs) page offers efficient find, filter, and analysis of API requests and HTTP status codes.

> ⏳ logs are only persisted up to 90 days after the original request occurred.

## Troubleshooting via Request Logs

When you execute an API query and want to investigate an API response, that's when the realization comes – logs review is inevitable.

The page shows all requests made to the Stackone <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip> and also allows you to see all requests that StackOne made to the [underlying providers](https://www.stackone.com/integrations) to fullfil the unified request. By default, it shows the logs in descending order per when the request occured.

<iframe width="100%" height="520px" src="https://demo.arcade.software/htWJYsOsC1mTmZapAJFK?embed" title="app.stackone.com/request_logs" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen allow="clipboard-write" />

The possible filtering options are:

| Filter              | Description                                                                                                                                                                                                                                               | Example values                                                   |
| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| Account             | The linked accounts' `origin_owner_name` for the current project. You can also see & search within that filter for a specific provider in case multiple accounts have been linked for the same `origin_owner_name`                                        | `Acme Inc.` `Sample Organization`                                |
| Provider            | The specific integration (aka [Provider](https://app.stackone.com/field_coverage)) associated with the request                                                                                                                                            | `Workday``Ashby``Salesforce`                                     |
| Resource            | The type of resource (and optionally sub resource requested and the action done on the resource.                                                                                                                                                          | `List Employees``Create Candidates Note``Get Applications Offer` |
| Source              | The source that originated the request - specifically the type of source allowing you to filter for requests made via the StackOne U.I. or an API key                                                                                                     | `API Request` `Dashboard UI` `Webhook`                           |
| Status              | The response's [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) - refer to additional documentation here regarding the meaning behind the [Unified API Error Codes](guides/unified-api-error-codes-and-troubleshooting-guide) | `200` `201` `400` `404` `502`                                    |
| Method              | The HTTP method used to make the request                                                                                                                                                                                                                  | `post``get``patch`                                               |
| Start/End date time | A date and time window                                                                                                                                                                                                                                    | `Jan 01, 2023 01:01`                                             |

<Tip>
  New Features:

  1. You can now investigate each successful request in detail by clicking ➡️ for the respective request. This request is coming from StackOne directly to Provider's API.
  2. It's now possible to view the source of the request – Dashboard, Test Connection, or Other (Postman, API docs, etc).
  3. Since all filters are now grouped inside 1 search bar, you can easily remove multiple filters by clicking ❌ on the search bar's hover-over.
</Tip>

## Accessing the request logs page

After configuring Account integration and testing its connection, you can also access its specific request logs directly by clicking the `View Logs` option in the ellipsis menu.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/4ff92ba-CleanShot_2024-07-16_at_23.04.572x.png)
</Frame>

<br />

You will be redirected to the logs page with a filter pre-applied in the search bar

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/request-logs.png)
</Frame>

## Viewing Log Details

When you click on a log entry, a detailed view opens up with two tabs:

1. **Details**: Shows the details of the unified API request made to StackOne, including request/response headers, body, query parameters, and status.

   > Note: Log storage duration can be configured in the [Advanced logs](./managing-projects#advanced-logs) section of your project Settings.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/request-logs-details.png)
</Frame>

2. **Underlying Requests**: Displays all API calls made to the provider's API to fulfill your unified request to enable better debugging.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/underlying-requests.png)
</Frame>


# Introduction
Source: https://docs.stackone.com/guides/stackone-api-sdks

Outline the list of supported SDKs to use the API with language-native libraries

# Open API

StackOne publishes Open API spec which can be used in conjunction with your OAS consumer of choice: [HRIS](https://api.eu1.stackone.com/oas/hris.json), [ATS](https://api.eu1.stackone.com/oas/ats.json), [CRM](https://api.eu1.stackone.com/oas/crm.json), [IAM](https://api.eu1.stackone.com/oas/iam.json), [LMS](https://api.eu1.stackone.com/oas/lms.json), [Marketing](https://api.eu1.stackone.com/oas/marketing.json), [Documents](https://api.eu1.stackone.com/oas/documents.json)

# Postman

StackOne maintains a Postman collection to more easily test & interact with the StackOne internal API and unified APIs:  [***Run in Postman***](https://god.gw.postman.com/run-collection/25987823-c68540f2-7aba-475e-89d2-77625c6a6424?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D25987823-c68540f2-7aba-475e-89d2-77625c6a6424%26entityType%3Dcollection%26workspaceId%3Df291b2e0-d0cb-4dc2-93c4-c2d4f581da3f)[\_  \_](https://god.gw.postman.com/run-collection/25987823-c68540f2-7aba-475e-89d2-77625c6a6424?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D25987823-c68540f2-7aba-475e-89d2-77625c6a6424%26entityType%3Dcollection%26workspaceId%3Df291b2e0-d0cb-4dc2-93c4-c2d4f581da3f)

* You can also directly Download / import the Postman collection [via our github repository](https://github.com/StackOneHQ/stackone-client-postman)

# Unified API SDKs

StackOne maintains and publishes the following SDKs:

* **Ruby** [RubyGems](https://rubygems.org/gems/stackone_client) [Github](https://github.com/StackOneHQ/stackone-client-ruby)
* **Typescript** ( [npm](https://www.npmjs.com/package/@stackone/stackone-client-ts), [github](https://github.com/StackOneHQ/stackone-client-typescript))
* **PHP** ([Packagist](https://packagist.org/packages/stackone/client-sdk),[github](https://github.com/stackoneHQ/stackone-client-php))

Additionally, our Documentation (eg: [Connect Sessions](/platform/api-reference/connect-sessions/)) generates easily copyable code to interact with our API in various languages:

# AI  Tools

StackOne makes it easy for AI agents to interact with any connected SaaS via its AI SDKs:

* Node/Typescript SDK: [https://github.com/StackOneHQ/stackone-ai-node](https://github.com/StackOneHQ/stackone-ai-node)
* Python: [https://github.com/stackoneHQ/stackone-ai-python](https://github.com/stackoneHQ/stackone-ai-python)

Reach out to our team via your dedicated Slack channel or at [support@stackone.com](mailto:support@stackone.com) to request access to any other SDK.


# StackOne Basics
Source: https://docs.stackone.com/guides/stackone-basics

Get started with the StackOne Dashboard and Unified APIs

In this guide, we will show you how to easily get started using the StackOne <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip>. Let's start with some key terminology:

<Card title="Project">
  A Project is the construct that binds all of your StackOne integrations together. This is where your integration settings and linked account credentials are stored.
</Card>

<Card title="StackOne API Key">
  The API Key that you will use to authenticate all calls to StackOne.
</Card>

<Card title="Integration (aka Provider or Connector)">
  A company with a SaaS offering in any of our supported verticals such as HRIS, ATS, CRM, etc.
</Card>

The overall model can be summarized in the following diagram:

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/b3b67a4-image.png)
</Frame>

There are 4 steps to set up your first integration:

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/20ba295-image.png)
</Frame>

The rest of this document will walk you through the process of configuring your first StackOne Integration.

## Making Your First StackOne API Request

### Create a Project

To create a Project, navigate to the StackOne [Dashboard](https://app.stackone.com/) and select **Create New Project** in the top-left dropdown. Give your Project a name and select the geographic region where you would like the transferred data to be processed.

<Frame>
  ![Create your first project](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/create-new-project.png "Create your first project")
</Frame>

Click the blue **Create** button to continue.

<Info>
  A single StackOne Organization can contain multiple Projects. Learn more about this in the [Managing Projects](./managing-projects) section.
</Info>

### Configure an Integration

In this step, we will configure an Integration for your newly created Project.

From the StackOne Dashboard, click on the Integrations menu in the left-hand side. You will see several tabs, each containing the available Integrations for the selected software category.

<Frame>
  ![Integrations Categories](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/integrations-categories-tabs.png "Integrations Categories")
</Frame>

<Info>
  Some Integrations may require additional details such as Client ID or Client Secret. These may have a slightly different setup process and may require partnerships.
</Info>

Find any Integration you'd like to enable. We recommend getting started with systems like BambooHR, as it is easy to [create a demo account](https://www.bamboohr.com/signup/). For BambooHR, we do not need any further information. If you do not have a partnership, select the `API Key` authentication type and click **Save Changes**.

You can now link any BambooHR tenant in your Project. To do this, click on **Accounts** in the left navigation and create an [Auth Link](./auth-link) or click **Link Account**.

You will be presented with a selection showing any enabled Integrations which will allow you to connect relevant systems you have access to.

<Info>
  Step-by-step instructions on how to use the Accounts page are detailed in the [Accounts](./accounts-section) guide.
</Info>

In your **Accounts** section, you should now see the tenant you have connected.

Click on the **Test Connection** option in the ellipsis menu for that account to open the Test Account Connection sidepanel. From this dialog, you can select different actions to perform against the StackOne Unified API, which will now be retrieving and transforming data directly from BambooHR on your behalf:

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/test-connection.png)
</Frame>

When you click **Send Request**, the StackOne Dashboard will make a request to the StackOne Unified API as if you were using a StackOne API Key. StackOne's Unified API server converts the request into a format that the Integration can understand and injects the relevant tenant credentials configured during the account linking process. Finally, the response data is transformed into the StackOne Unified API format and returned to you.

### Using the StackOne Unified APIs

Once you've set up a Project and enabled Integrations, you can start using StackOne programmatically and via your user interface:

* Create your first [API Key](./api-keys) and start using the Unified API programmatically

* [Embed the StackOne Integration Hub](https://stackone-60.mintlify.app/integrating-with-stackone/connect-your-frontend-via-the-stackone-react-hub)

* Connect your AI agent via StackOne's AI interfaces *(early access)*


# StackOne Identifiers
Source: https://docs.stackone.com/guides/stackone-identifiers



# Understanding Synthetic IDs in Our API

We often need to combine data from multiple sources to create unified responses. For instance, consider Workday's Applications. To create a unified application with the data provided by Workday, we need to link Job Requisitions with Candidates. Here, a candidate can be associated with multiple job requisitions and vice versa. Consequently, we can't use either of these IDs to identify a specific record.

## What Are Synthetic IDs?

To address this, we've introduced the concept of synthetic IDs. These IDs do not match an ID in the underlying provider, but allow you (and us) to identify the combined resources that were used to create this unified response. You can then use these IDs across our unified API. For example, you could use a `job_id` from a listing to search for candidates matching that value.

For simplicity, all IDs provided by the API will be synthetic IDs. These IDs are easy to identify because they are prefixed with `c28xIQ`. In most cases, you’ll still be able to see the underlying ID from the provider in a field prefixed by `remote_`. For example, in the case of `job_id`, the underlying ID will be in `remote_job_id`.

## Using Synthetic and Regular IDs

When it comes to writing or fetching data, both types of IDs can be used interchangeably.

### Fetching Data

For reading, let's say we have the synthetic and regular IDs:

```jsx
{
  job_id: 'c28xIQaWQ6MQ',
  remote_id: '1'
}

```

You can make either of these calls and expect the same response:

```bash
# Using a regular ID
curl --request GET \
--url https://api.stackone.com/unified/ats/jobs/1 \
--header 'accept: application/json'

# Using a synthetic ID
curl --request GET \
--url https://api.stackone.com/unified/ats/jobs/c28xIQaWQ6MQ \
--header 'accept: application/json'

```

This applies to any query parameters as well:

```bash
# Using a regular ID
curl --request GET \
     --url https://api.stackone.com/unified/ats/applications?raw=false&filter[job_id]=1&page_size=25 \
     --header 'accept: application/json'

# Using a synthetic ID
curl --request GET \
     --url https://api.stackone.com/unified/ats/applications?raw=false&filter[job_id]=c28xIQaWQ6MQ&page_size=25 \
     --header 'accept: application/json'

```

### Writing Data

When it comes to writing, the behavior is similar. You can use the ID field as usual and provide either a regular ID or a synthetic ID:


# Unified API Error Codes and Troubleshooting  Guide
Source: https://docs.stackone.com/guides/unified-api-error-codes-and-troubleshooting-guide

StackOne Unified API: Error Codes & Resolution Guide

Encountering errors while interacting with APIs is a common occurrence. Although the StackOne unified API will try to remediate issues automatically, it is important to understand what each error code signifies.

This guide lists the error codes you may encounter while using the StackOne Unified API, the possible reasons behind these errors, and possible steps for resolution.

## Understanding Error Codes

Below is a table detailing common error codes returned by the Unified API, their meanings, and common remediation steps:

<table>
  <thead>
    <tr>
      <th>Error Code</th>
      <th>Description</th>
      <th>Probable Cause</th>
      <th>Remediation Steps</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`400`</td>
      <td>Bad Request</td>
      <td>Incorrectly formatted request parameters (request parameters do not follow expected schema and fail validation)</td>

      <td>
        Ensure all request parameters are correctly formatted and try again.

        * Verify that the endpoint URL is correct.
        * Ensure the request body is well-formed and all required parameters are included.
      </td>
    </tr>

    <tr>
      <td>`401`</td>
      <td>Unauthorized</td>
      <td>Invalid API key or access token.</td>
      <td>Double-check your credentials and ensure they're valid.</td>
    </tr>

    <tr>
      <td>`403`</td>
      <td>Forbidden</td>
      <td>StackOne API key provided or linked account token lacks required permissions or the linked account tokens</td>
      <td>Verify the scopes of your API token and request necessary permissions.</td>
    </tr>

    <tr>
      <td>`404`</td>
      <td>Not Found</td>
      <td>The requested resource doesn't exist, possibly due to an invalid ID.</td>
      <td>Double-check the resource IDs in your request and ensure they are valid.</td>
    </tr>

    <tr>
      <td>`408`</td>
      <td>Request Timed Out</td>
      <td>The request took too long to complete (>60 seconds) and has been aborted - this could be due to provider rate limits.</td>
      <td>Respect received `Retry-After` headers to alleviate pressure on provider systems and avoid concurrent requests to the unified API.</td>
    </tr>

    <tr>
      <td>`409`</td>
      <td>Conflict</td>
      <td>The resource to be created already exists</td>
      <td>Check that the resource doesn't already exist before creating it.</td>
    </tr>

    <tr>
      <td>`412`</td>
      <td>Precondition Failed</td>
      <td>Endpoints using `x-account-id` may return `412` if the linked account is disabled.</td>
      <td>Check the status of the linked account and enable it if necessary.</td>
    </tr>

    <tr>
      <td>`422`</td>
      <td>Unprocessable Entity</td>
      <td>The payload data for creating a resource doesn't match what the endpoints expect</td>
      <td>Verify that the data sent follows the StackOne API reference. Look at the additional details if available in `provider_errors` for any additional information from the provider.</td>
    </tr>

    <tr>
      <td>`429`</td>
      <td>Too Many Requests</td>
      <td>Rate limits exceeded. Can be returned by the underlying provider or StackOne.</td>
      <td>Implement exponential backoff for retries and ensure your requests are within rate limits. See [Rate Limiting](/guides/rate-limiting) for more information.</td>
    </tr>

    <tr>
      <td>`500`</td>
      <td>Server Error</td>
      <td>Internal StackOne server issue.</td>
      <td>Notify StackOne support if the issue persists.</td>
    </tr>

    <tr>
      <td>`501`</td>
      <td>Not Implemented</td>
      <td>This endpoint hasn't been implemented for this connected provider</td>
      <td>Skip the call or contact StackOne support for more information. View endpoint support via the <a href="/platform/api-reference/accounts/get-meta-information-of-the-account">Meta endpoint</a>.</td>
    </tr>

    <tr>
      <td>`502`</td>
      <td>Bad Gateway</td>
      <td>The underlying Provider API has returned a 500 error</td>
      <td>Read any additional details available in the response data and ensure the resource exists.</td>
    </tr>
  </tbody>
</table>

<Note>
  Note:

  For any unresolved issues or further assistance, feel free to contact our support team directly via your dedicated slack channel or at [support@stackone.com](mailto:support@stackone.com).
</Note>

The above guide aims to provide a comprehensive yet concise overview of the error codes you might face while interacting with StackOne Unified API, along with actionable troubleshooting steps to resolve them. The structured table facilitates quick reference, while the detailed explanations under each error code ensure a deeper understanding of the issues and their solutions.

<Info>
  `provider_errors`

  When the underlying provider API returns an error, the StackOne unified API will include any data returned by the provider related to the error in the response data (in the `provider_errors` array). For example, 404 error is returned, because an employee with `id = 250` does not exist.

  <Frame>
    ![Provider Error Example](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/de1d150-Screenshot_2023-10-25_at_17.54.25.png)
  </Frame>
</Info>


# Using Expand & Include API Parameters
Source: https://docs.stackone.com/guides/using-expand-and-include-api-parameters



## Overview

While getting familiar with <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip>, you want to extend API functionality. StackOne API allows joining data from different objects into one combined response.

The StackOne implementation adds advanced <Tooltip tip="Query Parameters - A defined set of parameters attached to the end of a URL; begins with '?'">query parameters</Tooltip>, `include` or `expand`, to obtain the required information.

## Example scenario

Let's imagine an example:

1. You've acquired a [list of your available Accounts](/platform/api-reference/accounts/list-accounts) integrations (account `id`)

2. Then you've retrieved a [list of employees](/hris/api-reference/employees/list-employees) for a specific `x-account-id` and selected one particular employee by specifying the resource`id` in the path

3. Next you want to [get all available information of that employee](/hris/api-reference/employees/get-employee)

At this point, you're getting basic info, such as name, gender, birthday, email, etc. However, you may be missing information documented in the API reference such as `avatar_url` or additional information about the `work_location` and `employment`. This is where the `include ` and `expand` parameters become handy.

## Including optional params

`include` and `expand` reserved keywords allow retrieving additional information about the employee. As an example, the usage of `include`=`avatar_url` and `expand`=`work_location` returns a link to the employee's avatar and details of work location.

**Include**

Include is meant to return additional fields not included by default for privacy or performance reasons. For example, the `avatar_url` field may require the hosting of the underlying image, which can slow down the response unnecessarily if you do not need it.

**Expand**

Expand, on the other hand, is used to expand objects (also called `models`) for which only the ID would otherwise be given and would therefore require a call to another resource to retrieve the underlying data (such as an employee's employment or work location details )

<Frame>
  ![Expand and Include API Parameters](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/f3b8929-optional_api_params.gif)
</Frame>

## Supported parameter-value mapping

The supported include and expand parameters are specific to the unified API endpoints. They can be seen within the individual endpoints in the API references (e.g., [List Employees](/hris/api-reference/employees/list-employees))


# Using Postman
Source: https://docs.stackone.com/guides/using-postman

Postman is a tool that allows developers to send API requests and receive responses to verify whether an API works correctly. This document describes how to use Postman to call the StackOne Unified API.

<Warning>
  **Prerequisites**

  Before using Postman to test out the StackOne Unified API you should have already configured an integration and linked your account following the instructions in the [Getting Started with StackOne](./stackone-basics) guide.
</Warning>

### Installing Postman

Postman comes in two versions: an installed version and a browser-based version. Our Postman collection works equally well with both. We recommend setting up a Postman account to store all your configurations, which is quick and easy to do by following the instructions on the Postman website.

To install the desktop version of Postman, visit this link: [https://www.postman.com/downloads/](https://www.postman.com/downloads/).

### Setting up the StackOne collection

A Postman collection is a group of pre-configured requests that you can use to test an API. At StackOne, we've put together a collection for our Unified API, including all the configurations you need to quickly get started and connect using Postman. This collection lets you easily try out various aspects of our API.

<Note>To learn more about Postman collections including how to create your own see [here](https://learning.postman.com/docs/collections/collections-overview)</Note>

To download the StackOne Postman Collection go here: [<Frame>
![Run in Postman](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/button.svg)
</Frame>](https://app.getpostman.com/run-collection/25987823-22e17d29-d96a-4b0d-a0ac-ea18a32213da?action=collection%2Ffork\&source=rip%5Fmarkdown\&collection-url=entityId%3D25987823-22e17d29-d96a-4b0d-a0ac-ea18a32213da%26entityType%3Dcollection%26workspaceId%3Df291b2e0-d0cb-4dc2-93c4-c2d4f581da3f#?env%5BProduction%5D=W3sia2V5IjoiQVBJX0JBU0VfVVJMIiwidmFsdWUiOiJodHRwczovL2FwaS5zdGFja29uZS5jb20iLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6Imh0dHBzOi8vYXBpLnN0YWNrb25lLmNvbSIsInNlc3Npb25JbmRleCI6MH0seyJrZXkiOiJBUElfS0VZIiwidmFsdWUiOiI8WU9VUl9BUElfS0VZPiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiPFlPVVJfQVBJX0tFWT4iLCJzZXNzaW9uSW5kZXgiOjF9LHsia2V5IjoiT1JJR0lOX09XTkVSX0lEIiwidmFsdWUiOiJzYW1wbGVfYWNjb3VudCIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoic2FtcGxlX2FjY291bnQiLCJzZXNzaW9uSW5kZXgiOjJ9LHsia2V5IjoiT1JJR0lOX09XTkVSX05BTUUiLCJ2YWx1ZSI6IlNhbXBsZSBPcmdhbml6YXRpb24iLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IlNhbXBsZSBPcmdhbml6YXRpb24iLCJzZXNzaW9uSW5kZXgiOjN9LHsia2V5IjoiT1JJR0lOX1VTRVJOQU1FIiwidmFsdWUiOiJ1c2VyQGV4YW1wbGUuY29tIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQiLCJzZXNzaW9uVmFsdWUiOiJ1c2VyQGV4YW1wbGUuY29tIiwic2Vzc2lvbkluZGV4Ijo0fSx7ImtleSI6IlNFU1NJT05fVE9LRU4iLCJ2YWx1ZSI6IjxWQUxJRF9TRVNTSU9OX1RPS0VOPiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiPFZBTElEX1NFU1NJT05fVE9LRU4+Iiwic2Vzc2lvbkluZGV4Ijo1fSx7ImtleSI6IlBST1ZJREVSIiwidmFsdWUiOiJhc2hieSIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiYXNoYnkiLCJzZXNzaW9uSW5kZXgiOjZ9LHsia2V5IjoiQ0FURUdPUklFUyIsInZhbHVlIjoiXCJocmlzXCIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IlwiaHJpc1wiIiwic2Vzc2lvbkluZGV4Ijo3fSx7ImtleSI6Ik9SR0FOSVpBVElPTl9JRCIsInZhbHVlIjoiPFlPVVJfT1JHQU5JWkFUSU9OX0lEPiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiPFlPVVJfT1JHQU5JWkFUSU9OX0lEPiIsInNlc3Npb25JbmRleCI6OH0seyJrZXkiOiJQUk9KRUNUX0lEIiwidmFsdWUiOiI8WU9VUl9QUk9KRUNUX0lEPiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJkZWZhdWx0Iiwic2Vzc2lvblZhbHVlIjoiPFlPVVJfUFJPSkVDVF9JRD4iLCJzZXNzaW9uSW5kZXgiOjl9LHsia2V5IjoiQUNDT1VOVF9JRCIsInZhbHVlIjoiPFlPVVJfQUNDT1VOVF9JRD4iLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCIsInNlc3Npb25WYWx1ZSI6IjxZT1VSX0FDQ09VTlRfSUQ+Iiwic2Vzc2lvbkluZGV4IjoxMH1d)

You will be shown a message to fork the collection into your workspace. Forking is the process of creating a copy of the collection in your workspace while maintaining a link back to the original version making it easier to receive updates in future. Click the **Fork Collection** button to continue.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/7301221-image.png)
</Frame>

You will now be presented with a final confirmation page for forking the collection. You can provide your own Fork label and Workspace name if you wish, but generally the defaults should suffice. Click the **Fork Collection** button to continue.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/498ee8b-image.png)
</Frame>

When the fork process is complete the **StackOne Unified API** configuration will be displayed in the main Postman window as shown:

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/15d9757-image.png)
</Frame>

You have successfully copied the StackOne Unified API collection into your Postman workspace.

### Calling the StackOne Unified API

Now that the Postman collection is configured you are ready to make calls to the StackOne API.

#### Select an Environment

First select a StackOne environment to send your requests to. This must be the same environment that you have previously created your Project in as described in the **Getting Started with StackOne** guide.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/0226f68-image.png)
</Frame>

In this example we will use the **Production** environment.

#### Configuring your API key and Account ID

Before we make any calls to the Unified API we need to configure the collection with both the API Key and the Account ID. The API key is the StackOne API key that you created in the **Getting Started with StackOne** guide.

Click on the **Environments** section in the left hand navigation and then select the environment that you wish to configure; this will normally be *Production*. On the right side set the value for API\_KEY to the value of your StackOne API key and save the change.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/5b03037-image.png)
</Frame>

Now that the API\_KEY is configured we can retrieve the Account ID for our targeted endpoint. To retrieve all the Account IDs for the Project click on GET for **Accounts** and then **Send**. Look through the response for the Account ID needed for the particular endpoint you wish to make queries to. In this example we will be using Salesforce CRM so we will use the value returned in the **id** field for the provider **salesforce** as our ACCOUNT\_ID.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/14b1b80-image.png)
</Frame>

Again, click on the **Environments** section on the left hand and select the environment and on the right side set the value for ACCOUNT\_ID to the value of the Account ID you just retrieved and save the change.

Note: These values are stored against the *environment* so that they can be reused for all API calls made from Postman for that particular environment. As Projects and Account IDs are specific to each environment if you change the environment you should configure the correct values for that particular environment.

#### Calling the API

You are now ready to make calls to the StackOne Unified API. Start by expanding the StackOne section and explore the various parts of the Unified API. In this example our Project has been integrated with a CRM endpoint provided by Salesforce so we will make some test calls against the CRM part of the Unified API.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/5e67a08-image.png)
</Frame>

Click on **List Contacts** and you should see the URL update to read:

```
{{API_BASE_URL}}/unified/crm/contacts?raw=true&page=1&page_size=3
```

Clicking on the **Send** button will send the request to the StackOne endpoint and the results will be displayed in the response panel at the bottom of the screen.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/4f369b4-image.png)
</Frame>

Congratulations, you have successfully made a call to the StackOne Unified API.

### Troubleshooting

This section includes some common errors the you may encounter and steps to fix them.

#### \{"error":"Invalid authentication token"}

If you see this error it is likely that you have not configured your API\_KEY properly. Ensure that the steps above have been followed and that you are using the correct environment.


# Using the Passthrough (Proxy) query parameters
Source: https://docs.stackone.com/guides/using-the-passthrough-query-parameters

Use filters that are supported by the underlying provider requests

Passthrough query parameters allow users to inject custom parameters directly into underlying provider APIs. This feature enhances flexibility, enabling more specific and customizable API calls without needing to be supported by our <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip>.

## What is a Passthrough Query Parameter?

When invoking our unified API, you can provide query parameters to customize the API response. A passthrough query parameter is a special parameter that can be included in your API request, which will be directly passed on to the underlying provider API.

## How Does it Work?

The passthrough query mechanism uses a specific parameter pattern – the keyword "proxy" followed by brackets. If any parameter in this format is present in the API call, it will be extracted and passed as a query parameter to the underlying provider API.

**Pattern**: `proxy[custom-query-name]=custom-query-value`

* `custom-query-name`: The name of the custom query parameter.
* `custom-query-value`: The value assigned to the custom query parameter.

<Note>
  Note:

  More advanced filters are also supported: `proxy[filter[eq][age]]=25`.
</Note>

<Warning>
  Using the `proxy` passthrough parameter to set page-related parameter (eg: page limits, offsets, size etc.) may result in unexpected behaviour as it will override the values that StackOne sends with every provider request
</Warning>

## Example

Suppose you use the unified API to get all candidates for <Tooltip tip="ATS - Application Tracking Systems help comapanies match candidates to their recruitment and hiring goals">ATS</Tooltip> category. This API already supports some optional filters, such as the `page_size` query parameter. If you know that one of the underlying providers supports a specific filter called `my-custom-filter`, you can use the passthrough query parameter to include this in your request, and it will be used when calling the provider API.

API Request: `https://api.stackone.com/unified/ats/candidates?proxy[my-custom-filter]=123`

With the above request, while the `page_size=20` parameter will be interpreted by our unified API, the `proxy[my-custom-filter]=123` will be extracted and passed directly to the underlying provider API as `my-custom-filter=123`.

<Frame>
  ![Proxy Parameter Mechanism](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/0d948b1-proxy_mechanism.png)
</Frame>

Sorting candidates by the First Name for [TeamTailor API](https://docs.teamtailor.com/):

`https://api.stackone.com/unified/ats/candidates?page_size=20&proxy[sort]=first_name`

<Frame>
  ![TeamTailor sort filter parameter](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/b1a8ca6-proxy_param.gif)
</Frame>

## Benefits

1. **Flexibility**: Developers can maximize the use of underlying provider APIs by tapping into specific features or filters that the unified API might not support directly.
2. **Future-Proofing**: As underlying provider APIs evolve and introduce new query parameters, developers can start using those without waiting for the unified API to offer built-in support.

## Caveats

Although it's great to have the flexibility to use all the filters that the underlying provider supports, you should consider the following caveats when using this functionality:

* These requests will not benefit from the unified vision, so a specific custom request with proxy parameters will not likely be supported between different providers;
* We often need to use some filters in the underlying requests to support the unified models. To keep the response data as unified as possible between different providers, if you passthrough query parameters that are already being used by default, the values that you pass will have less precedence and will not be overridden;
* The filters might be removed or deprecated by the underlying provider without the intervention of the StackOne team, which might break your custom use cases without notice.

## Conclusion

Passthrough query parameters provide a powerful way to enhance the capabilities of your API calls, giving you direct access to features and filters of underlying provider APIs. Developers can create more customized API requests by understanding the tradeoffs and leveraging this mechanism.


# Webhooks
Source: https://docs.stackone.com/guides/webhooks

Page functionality described in detail

## Overview

StackOne allows configuring <Tooltip tip="Webhook - HTTP request, triggered by an event in a source system and sent to a destination system, often with a data payload">webhooks</Tooltip> to establish event communication between your application and StackOne servers. After creating a webhook, you can test them by specifying:

* [Example payload](#example-payload)

* [Your customized webhook integration code](#sample-webhook-consumer-code)

<iframe width="100%" height="450px" src="https://demo.arcade.software/fuzAsV0u1JnOaM5ZOIf9?embed&embed_mobile=inline&embed_desktop=inline&show_copy_link=true" title="StackOne - Accounts - Auth Link" loading="lazy" webkitallowfullscreen mozallowfullscreen allowfullscreen allow="clipboard-write" />

## Webhook Listing

Navigate to the webhook section by going to [https://app.stackone.com/webhooks.](https://app.stackone.com/webhooks.) On that section you can:

* view any configured webhook and clickthrough to update their configuration

* copy the signing secret to use in your codebase accordingly

* create a new webhook

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/86b4bc6b7694743969ea99afd3eb0957993dd4369f3f41734d84bf85fa2cce9e-CleanShot_2024-11-19_at_22.26.262x.png)
</Frame>

<br />

## Setting up a new webhook

1. After selecting a StackOne project, you will see the `Webhooks` section in the left-hand-side menu.

2. Create and configure a new webhook by clicking the `Add Webhook` button

3. Input in the `Webhook URL` field a valid URL that StackOne should send a request to whenever one of the previously selected event occurs.

4. Select the events that your webhook should be triggered on (native or synthetic events)

   1. **Native events**: are events generated by the underlying provider which are then associated with a StackOne unified event/resource, parsed and forwarded to the configured webhook URL. Subscribing to native event will, once the configuration saved, programmatically create an event subscription for each current and future linked account of the selected provider

   2. **Synthetic Events:** StackOne periodically polls the underlying provider records every hour and comparing stored hashes. The poll time can be adapted based on your needs and no PII is stored as part of this process.

5. Finally, click on the `Save Webhook` button. You should now see your newly configured Webhook on the `webhooks` page.

6. Take note of the webhook secret displayed in the webhook listing page as it will allow you to authenticate more securely webhooks coming from StackOne

   1. As a relatively less secure but simpler alternative, you can also authenticate events sent by StackOne by adding a custom query parameter to your webhook URL eg `?token=unique_secret_token ` and verify this parameter's presence when receiving the request.

### Overview Tab

The overview tab shows you at a glance the number of events sent to the configured webhook URL within the timeframe selected on the right-hand side (whether these events were successfully sent or if the request to the configured webhook URL failed)

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/6fd077d409022c9a2c72e690a893b12ff109439210c817c5137473607ffbab0c-CleanShot_2024-11-19_at_22.15.042x_copy.png)
</Frame>

### Events Tab

#### Account Events

Account Events are events originating from StackOne related to a linked account connection and not to any underlying resource (eg: employee or candidates). Account events can be useful for your application/server to be notified of any new Accounts being linked (`account.created` event) or updated (`account.updated`) allowing you to trigger relevant workflow on your end (eg. syncing data from the underlying tenant).

#### Unified Events

The Events tab of the webhook configuration allows you to view and update the unified events this webhook is subscribed to. Any "green" in the table indicates that the webhook is currently subscribed to native or synthetic event for one or more underlying provider. Anything in orange represent an event subscription that has been modified but not yet saved.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/7845d98d799178d27157bf9850c17c4ec626d613c01d4effa6b79c4f32b49197-CleanShot_2024-10-15_at_17.36.392x.png)
</Frame>

<br />

### Health Tab

The health tab of the new webhook allows you to see at a glance the status of each underlying native webhook subscription for each linked account

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/b883c4fb379f87714ec9179f61dc67af36cd15f736092bd8d8deb063219b113e-CleanShot_2024-10-15_at_17.37.262x.png)
</Frame>

#### `event` list and associated `record_type`

| Category | Resource     | Events                                                                             |
| -------- | ------------ | ---------------------------------------------------------------------------------- |
| Accounts | Accounts     | `account.created`, `account.updated`, `account.deleted`                            |
| HRIS     | Employees    | `hris_employees.created`, `hris_employees.updated`, `hris_employees.deleted`       |
|          | Employments  | `hris_employments.created`, `hris_employments.updated`, `hris_employments.deleted` |
| ATS      | Assessments  | `ats_assessments.created`, `ats_assessments.updated`, `ats_assessments.deleted`    |
|          | Candidates   | `ats_candidates.created`, `ats_candidates.updated`, `ats_candidates.deleted`       |
|          | Applications | `ats_applications.created`, `ats_applications.updated`, `ats_applications.deleted` |
|          | Interviews   | `ats_interviews.created`, `ats_interviews.updated`, `ats_interviews.deleted`       |
|          | Jobs         | `ats_jobs.created`, `ats_jobs.updated`, `ats_jobs.deleted`                         |
|          | Job Postings | `ats_job_postings.created`, `ats_job_postings.updated`, `ats_job_postings.deleted` |
|          | Lists        | `ats_lists.created`, `ats_lists.updated`, `ats_lists.deleted`                      |
|          | Users        | `ats_users.created`, `ats_users.updated`, `ats_users.deleted`                      |
| CRM      | Accounts     | `crm_accounts.created`, `crm_accounts.updated`, `crm_accounts.deleted`             |
|          | Contacts     | `crm_contacts.created`, `crm_contacts.updated`, `crm_contacts.deleted`             |
| LMS      | Assignments  | `lms_assignments.created`, `lms_assignments.updated`, `lms_assignments.deleted`    |
|          | Completions  | `lms_completions.created`, `lms_completions.updated`, `lms_completions.deleted`    |
|          | Content      | `lms_content.created`, `lms_content.updated`, `lms_content.deleted`                |
|          | Courses      | `lms_courses.created`, `lms_courses.updated`, `lms_courses.deleted`                |
|          | Users        | `lms_users.created`, `lms_users.updated`, `lms_users.deleted`                      |

<Note>
  Note:

  The webhook settings such as `URL` and `Events` can be updated at any point after creating the webhook by returning to the Webhooks page and clicking on the webhook you would like to update.\
  You can also delete the webhook if it's no longer needed (irreversible action).
</Note>

## Testing Webhooks

### Example Payload

Accounts-based webhooks <Tooltip tip="Webhook - HTTP request, triggered by an event in a source system and sent to a destination system, often with a data payload">webhook</Tooltip> will follow the following interface:

```typescript
{
  project_id: string, // the ID of the StackOne project
  event: 'account.updated' | 'account.created' | 'account.deleted' | 'hris_employees.updated', 'hris_employees.created',
  event_date: 'string', // date as ISO string (eg: '2023-07-03T01:55:47.217Z')
  record_type: 'account',
  record_id: string | number, // In the case of accounts-based events - this will be the account ID
  sent_at: 'string', // date as ISO string (eg: '2023-07-03T01:55:47.217Z')
  account_id: string, // This will always be the Account ID
  origin_owner_id?: string, // unique indentifier used to track customers or organizations
  origin_owner_name?: string, // human-readable name associated with Origin Owner ID
  origin_username?: string, // username responsible for connecting the tool
  setup_information?: object, // extra information used to setup the account
}
```

**Account event (account.updated)** example

```json
{
  "project_id": "acmeinc-27270",
  "account_id": "41220118784113397989",
  "event": "account.updated",
  "event_date": "2023-11-01T13:10:31.408Z",
  "record_type": "account",
  "record_id": "41220118784113397989",
  "sent_at": "2023-11-01T13:10:31.418Z",
  "origin_owner_id": "unique-org-identifier",
  "origin_owner_name": "Test organization",
  "origin_username": "sample-user",
  "setup_information": {
    "domain": "companytest"
  }
}
```

**Employee Synthetic Event (employee.updated)** example

```json
{
  "project_id": "acmeinc-27270",
  "account_id": "41260118784113327989",
  "event": "hris_employees.updated",
  "event_date": "2023-11-01T15:09:22.961Z",
  "record_type": "employees",
  "record_id": "3223323715753018140",
  "sent_at": "2023-11-01T15:09:22.978Z"
}
```

**Job Postings Native Event (job\_postings.updated)** example

```json JSON
{
  "project_id": "dev-56501", // StackOne Project ID
  "account_id": "44250964874717348401", // StackOne Linked Account ID
  "event": "ats-job_postings.updated", // Unified Event name
  "event_date": "2024-11-13T17:01:16.0007", // Datetime string of when the event was received by StackOne from the provider
  "record_type": "ats_job_postings", // Unified Resource Type
  "record_id": "cxIQam9iX2lkOjEzMmM3ZWRjLWNmMTktNDdjMy1hODdlLTUxMzU3NDI4ZDVmZA", // Stackone Identifier for the resource
  "record_remote_id": "132c7edc-cf19-47c3-a87e-51357428d5fd", // Original (remote) Identifier for the resource
  "sent_at": "2024-11-1317:01:16.844Z", // Timestamp of when the event was sent to the configured webhook URL

  // original event data including original payload
  "raw_event": {
    "headers": {
      "smartrecruiters-timestamp": "1731517276",
      "content-type": "application/json"
    },
    "body": {
      "job_id": "18dedcd5-2509-4363-a565-7b63b2ablaf1",
      "job_ad_id": "132c7edc-cf19-47c3-a87e-51357428d5fd"
    }
  }
}
```

A `x-stackone-signature` header will be added to all webhook requests, e.g.,`'x-stackone-signature': 'jqzLV78Lkg5RhZgx6nRA1FLIYBkqoclBdRrNizjlZcU'`. This header will contain a [hmac](https://www.okta.com/identity-101/hmac/#:~:text=Hash%2Dbased%20message%20authentication%20code,use%20signatures%20and%20asymmetric%20cryptography.) `sha256` hash of the given payload using the `Signature Secret` previously given as a secret key during hashing.

<Warning>
  3rd party Webhook generators:

  You can easily test the account-based webhooks by using a third-party webhook creation tool such as [https://webhook.site](https://webhook.site) or [https://typedwebhook.tools/](https://typedwebhook.tools/) or by setting-up a proxy to your localhost via [ngrok](https://ngrok.com/).

  StackOne is not affiliated with these websites.
</Warning>

### Sample Webhook consumer code

```javascript
// index.js
import express from 'express';
import bodyParser from 'body-parser';
import { createHmac } from 'crypto';
const app = express();

// Replace with the signing secret string displayed on the Stackone webhooks details page
const STACKONE_WEBHOOK_SIGNATURE =
  'S-gQTtwraolKVsY88OvQNZ-TlGrHw9mvHKp-ls8Co9CkOADQc1VSeCZ_2hDK6oWuKUd_4qxjRLzoEGYA9JVCNg';


/**
 * The function checks if a given signature is valid by comparing it with the payload hash using a signing secret.
 * @param signature - The `signature` parameter is the signature value that you want to validate. It is typically a string
 * representing the cryptographic signature of the `payload` parameter.
 * @param payload - The payload is the data that needs to be signed. It can be any string or object that you want to verify
 * the integrity of.
 * @param signingSecret - The `signingSecret` parameter is a secret key used for generating the signature. It is a string
 * value that should be kept confidential and known only to the parties involved in the signature verification process.
 * @returns a boolean value indicating whether the calculated hash is equal to the provided signature.
 */
function isSignatureValid(signature, payload, signingSecret) {
  const hash = createHmac('sha256', signingSecret)
    .update(payload)
    .digest('base64url');
  return hash === signature;
}

const jsonParser = bodyParser.json();

app.post('/integrations/webhook/accounts', jsonParser, (req, res) => {
  const signature = req.headers['x-stackone-signature'];
  if (
    !signature ||
    !isSignatureValid(
      req.headers['x-stackone-signature'],
      JSON.stringify(req.body),
      STACKONE_WEBHOOK_SIGNATURE,
    )
  ) {
    return res.status(401).send('Unauthorized');
  }
  // Do something with the payload
  console.log(req.body);

  // The webhook URL should return a 200 upon successful processing of the event. The response does not need to include anything else.
  return res.status(200).send(`Thank you for the account webhook event ❤️`);
});

console.log('listening on port 3333');
app.listen(3333);

// This sample server can be run via `node index.js`
```

<br />

## Signing Secret Rotation

You can rotate the webhook signing secret by following this process

1. Create a new signing secret by clicking on the existing secret to view and click with the `Add Signing Secret` button

   <Frame>
     ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/52accdf38697adbd52e71fbfb0da55b6206d070c83c0ee7bbcb2055b1b0332bf-CleanShot_2024-12-13_at_17.25.19.png)
   </Frame>

   The new signing secret will be flagged as inactive and requests sent to your webhook URL will only be signed with the active signing secret

   <Frame>
     ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/96daecf4d01f37d5d19b2d974fd8df45ea46a8b46a7091a97ddfa22e6c7c3677-CleanShot_2024-12-13_at_17.29.48.png)
   </Frame>

2. In StackOne: Copy this new (currently inactive) signing secret value

   <Frame>
     ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/080d698302b218359854cf76abe66496c5d474158d47180c58e8316f13d6f1dd-CleanShot_2024-12-13_at_17.30.30.png)
   </Frame>

3. In your own codebase:**update the verification logic to verify the request with both the current secret and the new one copied in the previous step.**

4. In StackOne: Activate the new webhook signing secret by clicking on it and confirming the activation. Once activated all requests sent to your webhook URL by StackOne will be signed using this new secret.

5. In StackOne: Once you've verified that new requests are being verified as expected, you may delete the old secret. *You will not be able to retrieve it or activate it again once deleted.*

6. In your own codebase: remove the logic responsible for verifying the request with the now inactive / deleted signing secret


# Get Benefit
Source: https://docs.stackone.com/hris/api-reference/benefits/get-benefit

get /unified/hris/benefits/{id}



# List benefits
Source: https://docs.stackone.com/hris/api-reference/benefits/list-benefits

get /unified/hris/benefits



# Get Company
Source: https://docs.stackone.com/hris/api-reference/companies/get-company

get /unified/hris/companies/{id}



# List Companies
Source: https://docs.stackone.com/hris/api-reference/companies/list-companies

get /unified/hris/companies



# Get employee Custom Field Definition
Source: https://docs.stackone.com/hris/api-reference/custom-field-definitions/get-employee-custom-field-definition

get /unified/hris/custom_field_definitions/employees/{id}



# List employee Custom Field Definitions
Source: https://docs.stackone.com/hris/api-reference/custom-field-definitions/list-employee-custom-field-definitions

get /unified/hris/custom_field_definitions/employees



# Get Employee Document Category
Source: https://docs.stackone.com/hris/api-reference/documents/get-employee-document-category

get /unified/hris/documents/employee_categories/{id}



# List Employee Document Categories
Source: https://docs.stackone.com/hris/api-reference/documents/list-employee-document-categories

get /unified/hris/documents/employee_categories



# Creates an employee
Source: https://docs.stackone.com/hris/api-reference/employees/creates-an-employee

post /unified/hris/employees



# Batch Upload Employee Document
Source: https://docs.stackone.com/hris/api-reference/employees/documents/batch-upload-employee-document

post /unified/hris/employees/{id}/documents/upload/batch



# Download Employee Document
Source: https://docs.stackone.com/hris/api-reference/employees/documents/download-employee-document

get /unified/hris/employees/{id}/documents/{subResourceId}/download



# Get Employee Document
Source: https://docs.stackone.com/hris/api-reference/employees/documents/get-employee-document

get /unified/hris/employees/{id}/documents/{subResourceId}



# List Employee Documents
Source: https://docs.stackone.com/hris/api-reference/employees/documents/list-employee-documents

get /unified/hris/employees/{id}/documents



# Upload Employee Document
Source: https://docs.stackone.com/hris/api-reference/employees/documents/upload-employee-document

post /unified/hris/employees/{id}/documents/upload



# Create Employee Employment
Source: https://docs.stackone.com/hris/api-reference/employees/employments/create-employee-employment

post /unified/hris/employees/{id}/employments



# Get Employee Employment
Source: https://docs.stackone.com/hris/api-reference/employees/employments/get-employee-employment

get /unified/hris/employees/{id}/employments/{subResourceId}



# List Employee Employments
Source: https://docs.stackone.com/hris/api-reference/employees/employments/list-employee-employments

get /unified/hris/employees/{id}/employments



# Update Employee Employment
Source: https://docs.stackone.com/hris/api-reference/employees/employments/update-employee-employment

patch /unified/hris/employees/{id}/employments/{subResourceId}



# Get Employee
Source: https://docs.stackone.com/hris/api-reference/employees/get-employee

get /unified/hris/employees/{id}



# Invite Employee
Source: https://docs.stackone.com/hris/api-reference/employees/invite-employee

post /unified/hris/employees/{id}/invite



# List Employees
Source: https://docs.stackone.com/hris/api-reference/employees/list-employees

get /unified/hris/employees



# Create Employee Skill
Source: https://docs.stackone.com/hris/api-reference/employees/skills/create-employee-skill

post /unified/hris/employees/{id}/skills



# Get Employee Skill
Source: https://docs.stackone.com/hris/api-reference/employees/skills/get-employee-skill

get /unified/hris/employees/{id}/skills/{subResourceId}



# List Employee Skills
Source: https://docs.stackone.com/hris/api-reference/employees/skills/list-employee-skills

get /unified/hris/employees/{id}/skills



# Get Employee Time Off Balance
Source: https://docs.stackone.com/hris/api-reference/employees/time-off-balances/get-employee-time-off-balance

get /unified/hris/employees/{id}/time_off_balances/{subResourceId}



# List Employee Time Off Balances
Source: https://docs.stackone.com/hris/api-reference/employees/time-off-balances/list-employee-time-off-balances

get /unified/hris/employees/{id}/time_off_balances



# List Assigned Time Off Policies
Source: https://docs.stackone.com/hris/api-reference/employees/time-off-policies/list-assigned-time-off-policies

get /unified/hris/employees/{id}/time_off_policies



# Create Employee Time Off Request
Source: https://docs.stackone.com/hris/api-reference/employees/time-off/create-employee-time-off-request

post /unified/hris/employees/{id}/time_off



# Get Employees Time Off Request
Source: https://docs.stackone.com/hris/api-reference/employees/time-off/get-employees-time-off-request

get /unified/hris/employees/{id}/time_off/{subResourceId}



# List Employee Time Off Requests
Source: https://docs.stackone.com/hris/api-reference/employees/time-off/list-employee-time-off-requests

get /unified/hris/employees/{id}/time_off



# Update Employee Time Off Request
Source: https://docs.stackone.com/hris/api-reference/employees/time-off/update-employee-time-off-request

patch /unified/hris/employees/{id}/time_off/{subResourceId}



# Updates an employee
Source: https://docs.stackone.com/hris/api-reference/employees/updates-an-employee

patch /unified/hris/employees/{id}



# Create Employee Work Eligibility Request
Source: https://docs.stackone.com/hris/api-reference/employees/work-eligibility/create-employee-work-eligibility-request

post /unified/hris/employees/{id}/work_eligibility



# Get Employees Work Eligibility
Source: https://docs.stackone.com/hris/api-reference/employees/work-eligibility/get-employees-work-eligibility

get /unified/hris/employees/{id}/work_eligibility/{subResourceId}



# List Employee Work Eligibility
Source: https://docs.stackone.com/hris/api-reference/employees/work-eligibility/list-employee-work-eligibility

get /unified/hris/employees/{id}/work_eligibility



# Update Employee Work Eligibility Request
Source: https://docs.stackone.com/hris/api-reference/employees/work-eligibility/update-employee-work-eligibility-request

patch /unified/hris/employees/{id}/work_eligibility/{subResourceId}



# Get Employment
Source: https://docs.stackone.com/hris/api-reference/employments/get-employment

get /unified/hris/employments/{id}



# List Employments
Source: https://docs.stackone.com/hris/api-reference/employments/list-employments

get /unified/hris/employments



# Get Cost Center Group
Source: https://docs.stackone.com/hris/api-reference/groups/get-cost-center-group

get /unified/hris/groups/cost_centers/{id}



# Get Department Group
Source: https://docs.stackone.com/hris/api-reference/groups/get-department-group

get /unified/hris/groups/departments/{id}



# Get Group
Source: https://docs.stackone.com/hris/api-reference/groups/get-group

get /unified/hris/groups/{id}



# Get Team Group
Source: https://docs.stackone.com/hris/api-reference/groups/get-team-group

get /unified/hris/groups/teams/{id}



# List Cost Center Groups
Source: https://docs.stackone.com/hris/api-reference/groups/list-cost-center-groups

get /unified/hris/groups/cost_centers



# List Department Groups
Source: https://docs.stackone.com/hris/api-reference/groups/list-department-groups

get /unified/hris/groups/departments



# List Groups
Source: https://docs.stackone.com/hris/api-reference/groups/list-groups

get /unified/hris/groups



# List Team Groups
Source: https://docs.stackone.com/hris/api-reference/groups/list-team-groups

get /unified/hris/groups/teams



# Get Job
Source: https://docs.stackone.com/hris/api-reference/jobs/get-job

get /unified/hris/jobs/{id}



# List Jobs
Source: https://docs.stackone.com/hris/api-reference/jobs/list-jobs

get /unified/hris/jobs



# Get Work Location
Source: https://docs.stackone.com/hris/api-reference/locations/get-work-location

get /unified/hris/locations/{id}



# List Work Locations
Source: https://docs.stackone.com/hris/api-reference/locations/list-work-locations

get /unified/hris/locations



# Get Time Entry
Source: https://docs.stackone.com/hris/api-reference/time-entries/get-time-entry

get /unified/hris/time_entries/{id}



# List Time Entries
Source: https://docs.stackone.com/hris/api-reference/time-entries/list-time-entries

get /unified/hris/time_entries



# Get Time Off Policy
Source: https://docs.stackone.com/hris/api-reference/time-off-policies/get-time-off-policy

get /unified/hris/time_off_policies/{id}



# List Time Off Policies
Source: https://docs.stackone.com/hris/api-reference/time-off-policies/list-time-off-policies

get /unified/hris/time_off_policies



# Creates a time off request
Source: https://docs.stackone.com/hris/api-reference/time-off/creates-a-time-off-request

post /unified/hris/time_off

<Warning>
  **This endpoint is deprecated**   <Icon icon="triangle-exclamation" color="#fbbf24" size={19} />
</Warning>


# Get time off request
Source: https://docs.stackone.com/hris/api-reference/time-off/get-time-off-request

get /unified/hris/time_off/{id}



# Get time off type
Source: https://docs.stackone.com/hris/api-reference/time-off/get-time-off-type

get /unified/hris/time_off_types/{id}

<Warning>
  **This endpoint is deprecated**   <Icon icon="triangle-exclamation" color="#fbbf24" size={19} />
</Warning>


# List time off requests
Source: https://docs.stackone.com/hris/api-reference/time-off/list-time-off-requests

get /unified/hris/time_off



# List time off types
Source: https://docs.stackone.com/hris/api-reference/time-off/list-time-off-types

get /unified/hris/time_off_types

<Warning>
  **This endpoint is deprecated**   <Icon icon="triangle-exclamation" color="#fbbf24" size={19} />
</Warning>


# Update time off request
Source: https://docs.stackone.com/hris/api-reference/time-off/update-time-off-request

patch /unified/hris/time_off/{id}

<Warning>
  **This endpoint is deprecated**   <Icon icon="triangle-exclamation" color="#fbbf24" size={19} />
</Warning>


# null
Source: https://docs.stackone.com/hris/common-guide/pagination



StackOne's <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip> allows paginating on API requests that return multiple records using a page cursor.

The following optional URL parameters are used for pagination:

<ParamField query="page_size" type="string" default="25">
  The number of records per page.
</ParamField>

<ParamField query="next" type="string">
  The `next` parameter is used to iterate through data pages.
</ParamField>

<Warning>
  It is recommended to keep the same page\_size throughout the sequence of pagination requests otherwise unexpected behaviour may occur.
</Warning>

## Sample URL

```
https://api.stackone.com/unified/hris/employees?page_size=25&next=eyJyIjphAsHHere
```

## Sample Response

In the response payload, you can find the `next` cursor. To get the next page of data send a new request with the `next` parameter set to this value.

```json
"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]
```

Once the cursor reaches the end of the data list, both values become NULL.

<Frame>
  ![Bypassed Records scenario](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/cd9e2c8-pagination_stripped.gif)
</Frame>

For further information see [Guides - Pagination](/guides/pagination)


# Overview
Source: https://docs.stackone.com/hris/introduction



A unified HRIS API overcomes typical integration challenges by standardizing inconsistent data models, normalizing varied terminology, and creating a consistent entity structure where employee records, compensation details, time-off balances, and organizational relationship exist predictably regardless of which HRIS provider your customer uses.

## Benefits of the HRIS API

Here are some benefits of using our HRIS API that simplifies and enhances human resources management:

<AccordionGroup>
  <Accordion title="Sandbox Access for Seamless Testing">
    Developers can utilize sandbox environments to test integrations without affecting live data, ensuring a smooth deployment process.
  </Accordion>

  <Accordion title="Real-Time Data Synchronization">
    StackOne's APIs support real-time data polling, allowing for immediate updates and synchronization across platforms.
  </Accordion>

  <Accordion title="Privacy-First Design Ensuring Compliance">
    With a [focus on security](https://www.stackone.com/blog/why-your-choice-of-unified-api-could-make-or-break-compliance), StackOne's architecture avoids unnecessary data storage, maintaining compliance with data protection regulations.
  </Accordion>

  <Accordion title="Synthetic and Native Webhooks for Updates">
    The platform provides both [synthetic and native webhooks](/guides/webhooks), enabling real-time notifications for employee and payroll changes.
  </Accordion>

  <Accordion title="Comprehensive HRIS Integration Coverage">
    StackOne offers [out-of-the-box integrations](https://www.stackone.com/integrations) with a wide range of HRIS platforms, simplifying the integration process.
  </Accordion>
</AccordionGroup>

## Key Features

The table below shows key features of the HRIS API that make human resources management easier, from real-time employee tracking to payroll management:

| **Feature**                         | **Description**                                                                                               |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Comprehensive Employee Management   | Easily create, update, and retrieve employee profiles, including personal information and employment history. |
| Payroll and Compensation Management | Manage payroll data, track compensation ranges, and update salary information for employees.                  |
| Leave and Attendance Tracking       | Monitor and update employee attendance, time-off requests, and manage leave balances.                         |
| Real-Time Webhooks                  | Receive instant notifications for changes in employee profiles, payroll, or leave data.                       |
| Document Management                 | Upload, download, and manage employee documents such as contracts and performance reviews.                    |
| Benefits Management                 | Record and manage employee benefits, including health, retirement, and wellness programs.                     |
| Employee Onboarding and Offboarding | Handle employee onboarding, document signing, and offboarding processes, tracking key milestones.             |

## Entity Model and Relationships

The following diagram illustrates the key entities within the HRIS API:

```mermaid
erDiagram
    Employee {
        string id
        string company_id
        string manager_id
        string job_id
        string department_id
    }

    Employment {
        string id
        string employee_id
    }

    TimeOff {
        string id
        string employee_id
        string approver_id
        string time_off_policy_id
    }

    TimeOffPolicies {
        string id
    }

    Company {
        string id
    }

    TimeOffBalances {
        string id
        string employee_id
        string policy_id
    }

    TimeEntries {
        string id
        string employee_id
    }

    Document {
        string id
        string employee_id
        string category_id
    }

    Location {
        string id
    }

    Benefit {
        string id
    }

    Group {
        string id
    }

    Job {
        string id
    }

    WorkEligibility {
        string id
        string employee_id
    }

    DocumentCategory {
        string id
    }

    CustomFieldDefinition {
        string id
    }

    Employee ||--o{ Employment : ""
    Employee ||--o{ TimeOff : ""
    Employee ||--o{ TimeOffBalances : ""
    Employee ||--o{ WorkEligibility : ""
    Employee ||--o{ Document : ""
    Employee ||--o{ TimeEntries : ""

    Company ||--o{ Employee : ""
    Company ||--o{ Location : ""

    Job ||--o{ Employee : ""

    Location ||--o{ Employee : ""

    Group ||--o{ Employee : ""
    Group ||--o{ Employment : ""

    Benefit ||--o{ Employee : ""

    TimeOffPolicies ||--o{ TimeOff : ""
    TimeOffPolicies ||--o{ TimeOffBalances : ""

    DocumentCategory ||--o{ Document : ""
```

The following table outlines key entities within the HRIS system and provides a brief description of each.

| Entity            | Description                                                                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Companies         | Represents the high-level organizational details of companies present in the underlying system, such as name, display name, and other identifiers. |
| Employees         | Contains comprehensive information about employees, including personal details, contact information, and relationship to other entities.           |
| Employments       | Details the employment records of each employee including job positions, start and end dates, compensation details, and more.                      |
| Locations         | Manages information about the work locations. Location may contain a name associated contact details.                                              |
| Time Off          | Manages records of employee leave requests and their approval status, including request type, duration, and related policies.                      |
| Time Off Balances | Tracks the available balance of time off for employees according to specific policies.                                                             |
| Time Off Policies | Defines the policies governing time off requests, including types of leave, duration units, and associated reasons.                                |
| Benefits          | Manages information about employee benefits programs, providers, and descriptions.                                                                 |
| Groups            | Organizes employees into logical groupings such as departments, teams, and cost centers.                                                           |
| Jobs              | Represents job positions available within the organization, including titles and statuses.                                                         |
| Time Entries      | Records employee work time entries, including start and end times, breaks, and status.                                                             |
| Work Eligibility  | Tracks employee work authorization documents such as visas, passports, and other legal identification.                                             |
| Documents         | Manages employee-related documentation including personal identification, contracts, and administrative forms.                                     |
| Skills            | Represents employee professional skills, proficiency levels, and related attributes.                                                               |

## Use cases

<CardGroup cols={3}>
  <Card title="User Syncing" href="/hris/use-cases/sync-users">
    Ensure your system is up to date with all the employees details in your customers' HRIS system.&#x20;
  </Card>

  <Card title="Automated Employee Provisioning" href="/hris/use-cases/employee-provisioning">
    After the recruitment process, automate the provisioning and management of employees in your customer's HRIS system.
  </Card>
</CardGroup>


# Automated Employee Provisioning
Source: https://docs.stackone.com/hris/use-cases/employee-provisioning

Automate the creation of employees in your customer's HRIS and keep the employee details updated.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/banner-creating-employees-hris.png)
</Frame>

Think about your SaaS platform helping HR teams make onboarding easier by connecting to different HRIS systems. You want to make it simple to set up employee profiles, sync recruitment data, and upload important documents. However, working with multiple HRIS systems can quickly get complicated.

Each HRIS has its own way of handling data and different methods to keep things updated. Without a single solution to bring everything together, keeping employee records accurate across different systems takes a lot of time and effort. This can lead to messy data and extra work for HR teams.

<ResponseField name="StackOne simplifies all of this by offering:">
  <Expandable title="StackOne Features">
    <ResponseField name="Why StackOne?">
      * **Unified API** connects multiple HRIS systems, making it easy to sync employee data across platforms.

      * **Scalability** to add more HRIS providers as your organization’s needs grow.

      * **Standardized data formats** to keep data consistent and organized across different HRIS platforms.
    </ResponseField>
  </Expandable>
</ResponseField>

## Automate Employee Onboarding in Your SaaS: Key Steps and System Interactions

Enhancing your SaaS system with intelligent employee onboarding allows for seamless data transfer from recruitment platforms to HRIS providers, automating the creation of employee profiles, mapping of recruitment data, and uploading of essential documents. This enables HR teams to manage new hires more efficiently, reducing manual work and enhancing accuracy.

### Steps for Automating Employee Provisioning in Your SaaS

Below are the steps to set up automated employee onboarding in your SaaS, allowing you to sync recruitment data, create employee profiles, and link onboarding documents efficiently.

<Steps>
  <Step title="Set Up HRIS Connector and Retrieve Metadata">
    Start by connecting to a HRIS (guide on making your first API request [here](../../guides/making-your-first-api-request)) and enable admins to retrieve essential metadata to your dashboard.

    This includes data such as **employees**, **job roles**, **work locations**, and **document categories** to ensure accurate mapping of recruitment data.

    * **API Endpoint**: [GET /hris/employees](../api-reference/employees/list-employees)

    * **API Endpoint**: [GET /hris/jobs](../api-reference/jobs/list-jobs)

    * **API Endpoint**: [GET /hris/groups/departments](../api-reference/groups/list-department-groups)

    * **API Endpoint**: [GET /hris/locations](../api-reference/locations/list-locations)

    * **API Endpoint**: [GET /hris/documents/employee\_categories](../api-reference/documents/list-employee-document-categories)
  </Step>

  <Step title="Map Recruitment Data to HRIS">
    Allow admins to map each the key metadata such as **job roles**, **teams**, and other **recruitment-specific data** from the SaaS platform to the relevant fields in selected HRIS provider. This mapping step ensures data alignment between systems.
  </Step>

  <Step title="Provision New Hires in HRIS">
    After a candidate is hired in the recruitment platform, enable admins to create a new employee record in a selected HRIS by making a request to the Create Employee endpoint.

    * **API Endpoint**: [POST /hris/employees](/hris/api-reference/employees/creates-an-employee)
  </Step>

  <Step title="Upload Required Documents">
    Allow admins to upload necessary documents such as the signed offer letter and proof of eligibility to the employee profile in a selected HRIS provider using using the employee `id`of the newly created employee.

    * **API Endpoint**: [POST /hris/employees/{id}/documents/upload](../api-reference/employees/documents/upload-employee-document)

    Alternatively, allow admins to upload multiple documents, such as offer letters, eligibility proofs, and other onboarding files, in a single action for the given employee.

    * **API Endpoint**: [POST /hris/employees/{id}/documents/batch-upload](../api-reference/employees/documents/batch-upload-employee-document)
  </Step>
</Steps>

The diagram below illustrates the key steps in automating employee onboarding with StackOne, including retrieving HRIS data, setting up employee profiles, and uploading and syncing essential documents.

<Frame>
  ![creating-employees-in-hris-flow-diagram](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/creating-employees-hris-flow-diagram.png)
</Frame>

## Conclusion

This walkthrough showed how StackOne makes employee onboarding easier by connecting your SaaS to multiple HRIS providers. With StackOne, you can sync recruitment data, set up employee profiles, and manage document uploads across different HRIS systems. This saves time, keeps data accurate, and gives your team the flexibility to work with various HRIS providers as needed.


# User Syncing from HRIS
Source: https://docs.stackone.com/hris/use-cases/sync-users

Leverage StackOne to sync user details from your customer's HRIS system into your SaaS system. 

<Steps>
  <Step title="Pull Employee data through StackOne">
    Make a request to the [List Employees](/hris/api-reference/employees/list-employees) endpoint to get detailed information of employees from your customers HRIS system. Leverage the filters to only return recently updated records.
    Endpoints like [List Employee Documents](/hris/api-reference/employees/documents/list-employee-documents), [List Locations](/hris/api-reference/locations/list-locations), and [List Employee Time Off](/hris/api-reference/employees/time-off/list-employee-time-off-requests), can help you understand additional dimensions about employees for grouping in your product, or auto-provisioning.
  </Step>

  <Step title="Update Employees">
    If any updates are required to the employee information use the [Update Employee](/hris/api-reference/employees/updates-an-employee) endpoint to make any changes.
  </Step>

  <Step title="Configure a Webhook (optional)">
    Configure a Webhook to keep notified of any new employees created, updated or deleted to keep your system in sync.
  </Step>
</Steps>

To find out more about the StackOne HRIS API click [here](/hris/introduction)


# Get Group
Source: https://docs.stackone.com/iam/api-reference/groups/get-group

get /unified/iam/groups/{id}



# List Groups
Source: https://docs.stackone.com/iam/api-reference/groups/list-groups

get /unified/iam/groups



# Get Policy
Source: https://docs.stackone.com/iam/api-reference/policies/get-policy

get /unified/iam/policies/{id}



# List Policies
Source: https://docs.stackone.com/iam/api-reference/policies/list-policies

get /unified/iam/policies



# Get Role
Source: https://docs.stackone.com/iam/api-reference/roles/get-role

get /unified/iam/roles/{id}



# List Roles
Source: https://docs.stackone.com/iam/api-reference/roles/list-roles

get /unified/iam/roles



# Delete User
Source: https://docs.stackone.com/iam/api-reference/users/delete-user

delete /unified/iam/users/{id}



# Get User
Source: https://docs.stackone.com/iam/api-reference/users/get-user

get /unified/iam/users/{id}



# List Users
Source: https://docs.stackone.com/iam/api-reference/users/list-users

get /unified/iam/users



# Update User
Source: https://docs.stackone.com/iam/api-reference/users/update-user

patch /unified/iam/users/{id}



# null
Source: https://docs.stackone.com/iam/common-guide/pagination



StackOne's <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip> allows paginating on API requests that return multiple records using a page cursor.

The following optional URL parameters are used for pagination:

<ParamField query="page_size" type="string" default="25">
  The number of records per page.
</ParamField>

<ParamField query="next" type="string">
  The `next` parameter is used to iterate through data pages.
</ParamField>

<Warning>
  It is recommended to keep the same page\_size throughout the sequence of pagination requests otherwise unexpected behaviour may occur.
</Warning>

## Sample URL

```
https://api.stackone.com/unified/hris/employees?page_size=25&next=eyJyIjphAsHHere
```

## Sample Response

In the response payload, you can find the `next` cursor. To get the next page of data send a new request with the `next` parameter set to this value.

```json
"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]
```

Once the cursor reaches the end of the data list, both values become NULL.

<Frame>
  ![Bypassed Records scenario](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/cd9e2c8-pagination_stripped.gif)
</Frame>

For further information see [Guides - Pagination](/guides/pagination)


# Overview
Source: https://docs.stackone.com/iam/introduction



Our Unified API simplifies IAM integration and governance, enabling seamless management of identities across multiple providers. By offering standardized endpoints for users, roles, groups, and policies, our API empowers organizations to implement consistent access control regardless of the underlying identity platforms. Whether conducting automated user access reviews, synchronizing user profiles across systems, or enforcing role-based access controls, our Unified API provides the flexibility and standardization needed to optimize security operations effectively.

## Benefits of the IAM API

Here are some benefits of using our IAM API that simplifies and strengthens identity management:

<AccordionGroup>
  <Accordion title="Unified Identity Governance">
    Manage users, roles, groups, and policies through a single standardized API, regardless of the underlying identity providers.
  </Accordion>

  <Accordion title="Automated Access Reviews">
    Easily implement automated user access reviews across multiple systems, ensuring compliance with [security policies](https://www.stackone.com/blog/why-your-choice-of-unified-api-could-make-or-break-compliance) and regulatory requirements.
  </Accordion>

  <Accordion title="Simplified Multi-Provider Management">
    StackOne's unified approach eliminate the complexity of integrating with multiple IAM providers, reducing development time and maintenance costs.
  </Accordion>

  <Accordion title="Detailed User Status Tracking">
    Monitor user activity with comprehensive status tracking, including last login times, active status, and multi-factor authentication details.
  </Accordion>

  <Accordion title="Rich Role and Permission Mapping">
    Easily map roles to permissions and resources, providing granular control over access rights across different systems and applications.
  </Accordion>
</AccordionGroup>

## Key Features

The table below shows key features of the IAM API that make identity and access management more efficient, from real-time synchronization to comprehensive user control:

| **Feature**                             | **Description**                                                                                            |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Comprehensive User Management           | Easily create, update, and retrieve user profiles, including personal information, roles, and permissions. |
| Role, Policy, and Permission Management | List and manage roles, assign permissions, and define access control policies for various resources.       |
| Group Management                        | Organize users into groups, assign roles and permissions, and manage group memberships.                    |
| Resource Access Control                 | Control access to resources and ensure users have the appropriate permissions for their roles.             |

## Entity Model and Relationships

The following diagram illustrates the key entities within the IAM API:

```mermaid
erDiagram
    User ||--o{ Role : ""
    User ||--o{ Group : ""
    Role ||--o{ Policy : ""
    Group ||--o{ Role : ""
    Policy ||--o{ Permission : ""
    Permission ||--o{ Resource : ""

  User {
      string id
      string remote_id
      string primary_email_address
      string first_name
      string last_name
      string name
      string username
      boolean is_bot_user
      string status
      datetime last_active_at
      datetime last_login_at
      datetime created_at
      datetime updated_at
      array multi_factor_enabled
      object avatar
  }

  Role {
      string id
      string remote_id
      string name
      string description
      string type
      datetime created_at
      datetime updated_at
  }

  Group {
      string id
      string remote_id
      string name
      string description
      string type
      string parent_id
      string remote_parent_id
      datetime created_at
      datetime updated_at
  }

  Policy {
      string id
      string remote_id
      string name
      string description
      datetime created_at
      datetime updated_at
  }

  Permission {
      string id
      string remote_id
      string name
      string type
      string description
      datetime created_at
      datetime updated_at
  }

  Resource {
      string id
      string remote_id
      string name
      string location
      string type
      string description
      datetime created_at
      datetime updated_at
  }
```

The following table outlines key entities within the IAM system and provides a brief description of each:

| Entity      | Description                                                                                                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Users       | Represents individuals with system access, including their personal information, username, email, status, activity timestamps, and multi-factor authentication settings.     |
| Roles       | Defines sets of permissions and access levels that can be assigned to users or groups, with types such as admin, viewer, editor, etc.                                        |
| Groups      | Organizes users into collections for easier management, with properties like name, description, type (team, department, organization, etc.), and hierarchical relationships. |
| Policies    | Contains rules that define access controls, with associated permissions determining what actions can be performed.                                                           |
| Permissions | Specifies the allowed actions on resources, such as read, read\_write, approve, delete, etc.                                                                                 |
| Resources   | Represents the objects that users can access, such as files, folders, projects, or other system components that are protected by permissions.                                |


# Bullhorn Assessment or Background Check Custom Tab Integration
Source: https://docs.stackone.com/integration-guides/ats/bullhorn-assessment-or-background-check-custom-tab-integration

Learn how to set up and use the Bullhorn custom tab integration for assessments and background checks

## To Enable and Connect the Integration

<Steps>
  <Step title="Navigate to the ATS category">
    Navigate to the ATS category on the Integrations page and enable Bullhorn.

    <Frame>
      ![Bullhorn Integration Setup](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/bullhorn-integration-setup.png)
    </Frame>
  </Step>

  <Step title="Complete the configuration form">
    Please complete the necessary fields in the Bullhorn - Configuration model:

    * **Authentication Type** - Please select the OAuth2 or OAuth2 - Bullhorn Partner Credentials' to integrate with the Bullhorn.
    * **Partner Category** - The selection is based on your Integration category on Bullhorn custom tab. For example, if your integration is listed under the Assessments category, Please select Assessment from the dropdown.
    * **Package's List Endpoint URL** - The [endpoint URL](/ats/api-reference/assessments/packages/list-assessments-packages) that StackOne will call to retrieve the list of packages when the recruiter wants to send the test to the candidate.
    * **Package ID** - If you don't have the Package List Endpoint URL, you can add a specific package ID that will be visible to the recruiter when they want to send the test to the candidate.

    <Frame>
      ![Bullhorn Configuration Form](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/bullhorn-configuration-form.png)
    </Frame>
  </Step>

  <Step title="Save your configuration">
    Click on the `Confirm` or `Save Changes` button to enable your OAuth APIs, which allows end-users to link their accounts via the Hub.
  </Step>
</Steps>

## Enable Assessment or Background Check Integration using Bullhorn Custom Tab

<Steps>
  <Step title="Get the External-trigger-token">
    You will need the **external trigger token** to enable the Bullhorn custom tab integration feature for **assessments** or **background checks**. You can find it in the Stackone connect hub.

    <Frame>
      ![External Trigger Token](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/external-trigger-token.png)
    </Frame>

    Fill in the required information to connect an account and select the Custom Field from the dropdown to store data related to assessments and background checks. By default, it will use **customTextBlock1** if none is selected.

    <Frame>
      ![Custom Field Selection](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/custom-field-selection.png)
    </Frame>
  </Step>

  <Step title="Configure the custom tab in Bullhorn">
    To configure the custom tab in Bullhorn, you will need admin access.

    <AccordionGroup>
      <Accordion title="Log in to Bullhorn and access Admin">
        Log in to Bullhorn, then click the **Menu** button.

        <Frame>
          ![Bullhorn Menu](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/bullhorn-menu.png)
        </Frame>

        Click the **Admin** button.

        <Frame>
          ![Admin Button](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/admin-button.png)
        </Frame>
      </Accordion>

      <Accordion title="Access View Layout and select Candidate entity">
        Click **View Layout**.

        <Frame>
          ![View Layout](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/view-layout.png)
        </Frame>

        Select the **Candidate** entity.

        <Frame>
          ![Candidate Entity](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/candidate-entity.png)
        </Frame>
      </Accordion>

      <Accordion title="Add a new Custom Tab">
        Click the **Custom Tab** button.

        <Frame>
          ![Custom Tab Button](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/custom-tab-button.png)
        </Frame>

        Click the **Add New** button.

        Enter the required information in the fields:

        * **Name**: The name of the tab.
        * **Enabled**: Check this box to enable the tab.
        * **URL**: Enter the base URL from your integration partner, with the query parameter: `externalTriggerToken=${your-external-trigger-token}`
        * **User Types**: Select the types of users who will have visibility of this tab.

        <Frame>
          ![Custom Tab Configuration](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/custom-tab-configuration.png)
        </Frame>

        Click the **Save** button.

        <Frame>
          ![Save Button](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/save-button.png)
        </Frame>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Locate the Custom Tab under Candidates">
    <AccordionGroup>
      <Accordion title="Navigate to Candidates">
        Click the **Menu** button and then click the **Primary**.

        <Frame>
          ![Primary Menu](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/primary-menu.png)
        </Frame>

        Click the **Candidates** button.

        <Frame>
          ![Candidates Button](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/candidates-button.png)
        </Frame>
      </Accordion>

      <Accordion title="View Candidate Details">
        Click any **candidate** from the list.

        <Frame>
          ![Candidate List](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/candidate-list.png)
        </Frame>

        You will find the custom tab on the candidate detail page.

        <Frame>
          ![Custom Tab on Candidate Page](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/custom-tab-candidate-page.png)
        </Frame>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Add background check using the custom tab">
    Click on `Send Background Check` button

    <Frame>
      ![Send Background Check Button](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/send-background-check-button.png)
    </Frame>

    Select the test and click on `Send` button

    <Frame>
      ![Select Test](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/select-test.png)
    </Frame>

    A new record will be appended with a `Pending` status if the test notification is sent successfully.

    <Frame>
      ![Pending Status](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/pending-status.png)
    </Frame>

    The same record will be updated with the results once the candidate has submitted the test.

    <Frame>
      ![Updated Results](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/bullhorn/updated-results.png)
    </Frame>
  </Step>
</Steps>


# Greenhouse Partner API Integration
Source: https://docs.stackone.com/integration-guides/ats/greenhouse-partner-api

Learn how to set up and use the Greenhouse Partner API integration with StackOne

## To Get Greenhouse Partner Integration Credentials

1. Visit the [Greenhouse Assessment API documentation](https://developers.greenhouse.io/assessment.html#introduction) to connect with support and provide them with the *Base URL* and a sample *API Key*.
   * **Base Url** - This Base URL will be provided to you by StackOne. It will be utilized by Greenhouse to fetch the list of packages and send assessment notifications.
   * **API Key** - To get the API Key (External Trigger Token), retrieve it from the StackOne Integration Hub by connecting Greenhouse with either **Public + Partner API** or **Partner API** and selecting a Partner Category.

After obtaining the username and password from Greenhouse support, you can update the setup configuration.

## To Enable and Connect the Integration

<Steps>
  <Step title="Go to the ATS category">
    Navigate to the Integrations page and activate Greenhouse.

    <Frame>
      ![Configuration](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/greenhouse/greenhouse-integration-setup.png)
    </Frame>
  </Step>

  <Step title="Fill out the configuration form">
    Please fill out all the required fields in the **Greenhouse - Configuration** model.

    * **Authentication Type** - Please select either **Public + Partner API** or **Partner API** to integrate with Greenhouse.
    * **Partner Category** - Select the appropriate category based on your integration's classification as a partner for Greenhouse.
    * **Package's List Endpoint URL** - The [endpoint URL](/ats/api-reference/assessments/packages/list-assessments-packages.mdx) that StackOne will use to retrieve the list of packages when the recruiter intends to send a test to the candidate.
    * **Partner's Username** - You will receive the username from Greenhouse support as mentioned in the previous step.
    * **Partner's Password** - The password will also be provided by Greenhouse support, as stated earlier.
    * **Package ID** - If you do not have the Package List Endpoint URL, you can specify a particular package ID that will be visible to the recruiter when they wish to send the test to the candidate.

    <Frame>
      ![Greenhouse Configuration Form](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/greenhouse/greenhouse-configuration-form.png)
    </Frame>
  </Step>

  <Step title="Save your configuration">
    Click on the `Confirm` or `Save Changes` button to enable your Partner APIs, which allows end-users to link their accounts via the Hub.
  </Step>
</Steps>

## What will the customer see?

When a customer activates integration from StackOne Hub, they will see 'Integration' as the stage in their Interview Plan to send an assessment or background check.

<Frame>
  ![Customer view of integration stage](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/greenhouse/customer-view-integration-stage.png)
</Frame>

## What will the customer see after an assessment or background check has been sent?

When a customer sends an assessment to a candidate, they see a success message along with the application stage.

<Frame>
  ![Send Webhook Success](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/greenhouse/send-webhook-success.png)
</Frame>

## How will the results of the assessment or background check be displayed to the customer?

When a customer opens a candidate application, they will see their updated score along with the application stage.

<Frame>
  ![Updated Result](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/greenhouse/updated-result.png)
</Frame>


# Recruitee Partner API Integration
Source: https://docs.stackone.com/integration-guides/ats/recruitee-partner-api

Learn how to set up and use the Recruitee Partner API integration with StackOne

<Note>
  Note: The deletion of a partner integration on **Recruitee** is currently not supported through **StackOne** configuration. To delete an integration, please contact the **StackOne support team**.
</Note>

## To Enable and Connect the Integration

<Steps>
  <Step title="Go to the ATS category">
    Navigate to the Integrations page and activate Recruitee.

    <Frame>
      ![Configuration](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/recruitee/recruitee-integrations-setup.png)
    </Frame>
  </Step>

  <Step title="Fill out the configuration form">
    Please fill out all the required fields in the **Recruitee - Configuration** model.

    * **Authentication Type** - Please select either **Public + Partner API** to integrate with Recruitee.
    * **Environment Type** - If you have a Release Candidate (RC) environment account on Recruitee, select **Staging** as the environment type; otherwise, select **Production**.
    * **Partner Category** - Select the appropriate category based on your integration's classification as a partner for Recruitee.
    * **Package's List Endpoint URL** - The [endpoint URL](/ats/api-reference/assessments/packages/list-assessments-packages.mdx) that StackOne will use to retrieve the list of packages when the recruiter intends to send a test to the candidate.
    * **Package ID** - If you do not have the Package List Endpoint URL, you can specify a particular package ID that will be visible to the recruiter when they wish to send the test to the candidate.
    * **Partner Codename** - A unique identifier for the partner, used to identify your integration on the Recruitee marketplace. It must consist of lowercase letters and dashes (-) and be globally unique.
    * **Name** - The name of your integration that will be displayed on the Recruitee dashboard.
    * **Description** - A brief overview of your integration that will be displayed on the Recruitee dashboard.
    * **Logo** - The logo of your integration that will be displayed on Recruitee.

    <Frame>
      ![Recruitee Configuration Form](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/recruitee/recruitee-configuration-form-1.png)
    </Frame>

    <Frame>
      ![Recruitee Configuration Form](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/recruitee/recruitee-configuration-form-2.png)
    </Frame>
  </Step>

  <Step title="Save your configuration">
    Click on the `Confirm` or `Save Changes` button to enable your Partner APIs, which allows end-users to link their accounts via the Hub.
  </Step>
</Steps>

## What will the customer see?

When a customer activates the integration from the **Recruitee Marketplace**, they will have the option to select and send an **assessment** or **background check tests** for candidates.

<Frame>
  ![Recruitee Integration view for select test](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/recruitee/recruitee-integration-view-1.png)
</Frame>

## What will the customer see after an assessment or background check has been sent?

When a customer sends an **assessment** or **background check test** to a candidate, they will see a pending status for the test along with a confirmation message indicating that the test was successfully sent.

<Frame>
  ![Send Test Success](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/recruitee/recruitee-integration-view-2.png)
</Frame>

## How will the results of the assessment or background check be displayed to the customer?

When a customer opens a candidate's profile, they will see the candidate's updated score.

<Frame>
  ![Updated Result](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/recruitee/recruitee-integration-view-3.png)
</Frame>


# Teamtailor Partner API
Source: https://docs.stackone.com/integration-guides/ats/teamtailor-partner-api

To activate the Teamtailor Partner API or Public + Partner API in StackOne for integrating your Teamtailor Marketplace Integration, please follow the necessary steps.

## To Create a Teamtailor Partner

1. Go to the *Integration's Hub* page by selecting the Settings option from the top-right corner.

<Frame>
  ![navigate to settings](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/0f5ddaa3aceb519d244f1bacd0f03f9b5135bbce4315993a2472e93217def40a-create_a_partner_1.png)
</Frame>

1. To create a new partner, click on the `Create A New Partner` button.

<Frame>
  ![create a partner](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/0b17226cdb027df25dd9bba9fd0b0ecc97fb2fb60f7a36244a3bc55dc3862c46-create_a_partner_2.png)
</Frame>

1. Complete the New Partner's form by filling in the required fields: the Partner's name, base URL, and the category in the marketplace where you want your integration to be listed on Teamtailor's Marketplace page.

<Frame>
  ![new partner](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/0f7b82b6b6ba2bdba1f15aa0677e6838a9cb8270cc995c0eca95287d277f2490-new_partner.png)
</Frame>

1. Click on the `Show Advanced Settings` to expand and fill in the following JSON into the Activation form field.

<Frame>
  ![Activation Form](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/0aa6e654318c3dc39fd65964d51609d92b978d7ecc011a9422218d3dea886ebd-activation_form.png)
</Frame>

```json
{
   "config":{
      "fields":[
         {
            "type":"infobox",
            "content":"<a href='https://hub.stackone.com/integration-configuration-concepts/ats/teamtailor-assessment-or-background-check'>Click</a> here to learn how to use this integration",
            "icon":"info"
         },
         {
            "id":"externalTriggerToken",
            "type":"password",
            "label":"External Trigger Token",
            "required":true,
            "description":"The token to be used to trigger the workflow externally"
         }
      ]
   }
}
```

This External Trigger Token field will be visible to the customer when enabling the integration from the Teamtailor Marketplace.

Upon saving, the partner integration will be successfully created.

## To Get Partner Integration Credentials

1. On the Grid, next to your partner Integration's name, you will find the **Integration ID**.

<Frame>
  ![Integration Hub](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/20cbc704994cabb08d5470f3879cf4f835fd930c9486df63a86b1726a3758dab-Integration_hub_grid.png)
</Frame>

1. By clicking on Show Details, you can access the **API Key**.

<Frame>
  ![API Key](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/f762c6a11af0f8a1cc446d8fed106db773eed52dff6aacb7a77e7a58e387434d-show_details.png)
</Frame>

## To Enable and Connect the Integration

1. Navigate to the ATS category on the Integrations page and enable Teamtailor.

<Frame>
  ![To Enable Teamtailor](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/df134535d188a4158ef82eb435c0090df753825483c090cebc8ddc50f14ac2e6-teamtailor-partner-api.png)
</Frame>

1. Please complete the necessary fields in the **Teamtailor - Configuration** model:

   * **Authentication Type** - Please select the **Partner API or Public + Partner API** to integrate with the Marketplace.

   * **Partner Category** - The selection is based on your Integration category on Teamtailor's Marketplace page. For example, if your integration is listed under the Assessments category, Please select `Assessment` from the dropdown.

   * **Package's List Endpoint URL** - The [endpoint URL](/ats/api-reference/assessments/packages/list-assessments-packages) that StackOne will call to retrieve the list of packages when the recruiter wants to send the test to the candidate.

   * **Partner Integration ID** - You can find the Integration ID next to the Integration Name under Settings > Integration\`s Hub in Teamtailor.

   * **Partner Integration API Key** - You can find an API key in the Integration details under Settings > Integration\`s Hub in Teamtailor.

<Frame>
  ![Teamtailor Configuration Model](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/2cfbd3bf209b7d9652b7a57d806e89581e5fa9f918f2203ffdeb49fcb4e56d61-teamtailor_configuration_model.png)
</Frame>

Click on the `Confirm`or `Save Changes` button to enable your Partner APIs, which allows end-users to link their accounts via the Hub.

## What will the customer see?

When a customer enables Teamtailor from StackOne Hub, they will see the **External Trigger Token** used to enable the integration from the Teamtailor Marketplace.

<Frame>
  ![Teamtailor Customer view of External-trigger](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/teamtailor/teamtailor-custom-view-external-trigger.png)
</Frame>

## What will the customer see after an assessment or background check has been sent?

When a customer sends an assessment to a candidate, they will see the success message on the candidate application pop-up.

<Frame>
  ![Teamtailor sent test view](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/teamtailor/Teamtailor-sent-test-view.png)
</Frame>

## How will the results of the assessment or background check be displayed to the customer?

When a customer opens a candidate application, they will see the updated result with their score from the previous success sent via webhook.

<Frame>
  ![Teamtailor update result view](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/teamtailor/teamtailor-update-result-view.png)
</Frame>


# GoogleDrive Partner OAuth
Source: https://docs.stackone.com/integration-guides/documents/googledrive-partner-oauth

To integrate the GoogleDrive with StackOne, please follow these essentials steps

## Log in to Google Cloud Console

Log in to your Google Cloud Console at [https://console.cloud.google.com](https://console.cloud.google.com)

<Frame>
  <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Log in" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image1.png" />
</Frame>

## Create or Select a project

Create a new project or select an working project from projects list.

<Frame>
  <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Create or select project" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image2.png" />
</Frame>

## Configure Google OAuth

<Steps>
  <Step title="Navigate to OAuth consent screen">
    In the left navigation menu, click **APIs & Services > OAuth consent screen**

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Navigate to OAuth consent screen" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image3.png" />
    </Frame>
  </Step>

  <Step title="Configure Google Auth platform">
    Click on **GET STARTED** button in OAuth Overview page.

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Copy Your Domain" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image4.png" />
    </Frame>
  </Step>

  <Step title="Enter App details">
    Enter the App name and User support email, then click on next button

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Copy Your Domain" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image5.png" />
    </Frame>
  </Step>

  <Step title="Select Audience type">
    Select Audience type and click next button

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Copy Your Domain" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image6.png" />
    </Frame>
  </Step>

  <Step title="Enter Contact information">
    Enter contact email address and click on next button

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Copy Your Domain" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image7.png" />
    </Frame>
  </Step>

  <Step title="Finish the configuration process">
    Read the Google policies and click on Checkbox, then click on create button to finish.

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Copy Your Domain" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image8.png" />
    </Frame>
  </Step>

  <Step title="Select Required Application Scopes">
    Click the **Add or Remove Scopes** button, and a popup window will appear on the right titled *Update selected scopes*.

    Enable the following scope which is required for full functionality of this integration:

    * `https://www.googleapis.com/auth/drive`

    You can copy and paste the scope into the **Filter** bar to quickly locate them.

    Once the scope have been enabled, click the **Update** button to proceed.

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Update Scopes Button" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image9.png" />
    </Frame>
  </Step>
</Steps>

## Generate OAuth2 Client Credentials

<Steps>
  <Step title="Navigate to OAuth Clients">
    In the left navigation menu, click **Google Auth Platform > Clients**

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Navigate to OAuth Clients" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image10.png" />
    </Frame>
  </Step>

  <Step title="Create Client">
    Click on **CREATE CLIENT** button to create OAuth Client app

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Create Client" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image11.png" />
    </Frame>
  </Step>

  <Step title="Enter Client App details">
    Select **Web application** from Application type dropdown, Enter the Client App name and redirect URL as `https://api.stackone.com/connect/oauth2/googledrive/callback`, then click on CREATE button

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Enter Client App details" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image12.png" />
    </Frame>
  </Step>

  <Step title="Copy Client Credentials">
    Select you Client App from the the displayed **OAuth 2.0 Client IDs** list. Copy and store Client ID and Client Secret to be used in later steps.

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Copy Your Domain" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image13.png" />
    </Frame>
  </Step>
</Steps>

## Enable the Google Drive API

Google requires manually enabling APIs for your account. The [Google Drive API](https://developers.google.com/drive) provides the underlying endpoints for this Documents connection.

<Steps>
  <Step title="Navigate to the API Library">
    In the left navigation menu, click **APIs & Services > Library**

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Navigate to the API Library" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image14.png" />
    </Frame>
  </Step>

  <Step title="Locate the Google Drive API">
    Using the search bar, enter a search for *"Google Drive"*. Click the **Google Drive API** result.

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Locate the Admin SDK API" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image15.png" />
    </Frame>
  </Step>

  <Step title="Enable the Google Drive API">
    Click the **Enable** button to enable the Google Drive API for your organization.

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Enable the Admin SDK API" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image16.png" />
    </Frame>
  </Step>
</Steps>

## To Enable and Connect the Integration

<Steps>
  <Step title="Enable GoogleDrive">
    Navigate to the Documents category on the Integrations page and enable GoogleDrive.

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Enter Credentials" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image17.png" />
    </Frame>
  </Step>

  <Step title="Enter Credentials">
    Please complete the necessary fields in the **GoogleDrive - Configuration** model:

    * **Authentication Type** - Please select the **OAuth2 - Google Drive Partner Credentials** to integrate with the Google Drive Partner.
    * **Client ID**
    * **Client Secret**
    * **Scopes** - If you selected only the required scopes in the previous steps, leave the default value for this field. Otherwise, enter the space-separated list of scopes granted to your application.

    Proceed by clicking the Save Changes button.

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Enter Credentials" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image18.png" />
    </Frame>
  </Step>

  <Step title="Connect to GoogleDrive">
    Click the Connect button to start the login process. You will be redirected to Google Drive.

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Connect to GoogleDrive" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image19.png" />
    </Frame>
  </Step>

  <Step title="Grant OAuth Application Consent">
    A window will appear and may prompt you to log in to your Google Drive account.

    After logging in, you will be displayed the OAuth consent screen you configured.

    Click the **Allow** button to grant the application access to your Google Drive account.

    <Frame>
      <img className="rounded-md" style={{ margin: '0 auto', border: '1px solid #efefef' }} alt="Grant OAuth Application Consent" src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/googledrive/image20.png" />
    </Frame>
  </Step>
</Steps>


# GO1 LMS Integration
Source: https://docs.stackone.com/integration-guides/lms/go1

Content & Completion Management

## **Key Details**

### **Content Management**

* **Content Catalog:** GO1 manages the content library.

* **Publishing:** Initial content push results in an unpublished state, requiring GO1 administrator publishing.

* **Removal:** Communicate content removal to GO1; use soft delete (upsert with unpublished status) to hide content.

### **Content Upsert Behavior**

* **Deduplication:** Uses `external_reference` as the unique identifier.

  * Existing content with matching `external_reference` will be updated.

  * New content is created if no match is found.

### **Completion Push**

* Uses `content_external_reference` as the content identifier.

### **Provider-Specific Quirks**

* **Content Categorization:**

  * **Taxonomy:** GO1's category taxonomy: [https://help.go1.com/en/articles/6767512-topics-taxonomy](https://help.go1.com/en/articles/6767512-topics-taxonomy)

  * **Category Requirements:** Category and skill tagging is optional.

### **Limitations**

* **Rate Limits:** No rate limits currently.

### **Testing and Validation**

* Standard testing procedures apply.


# SAP SuccessFactors LMS Integration
Source: https://docs.stackone.com/integration-guides/lms/sap

Content & Completion Management

## **Key Details**

### **Content Upsert Behavior (Open Content Network - OCN Flow)**

* **OCN Approach:** Mimics external content provider flow, allowing customer-controlled import. Content updates and deactivation are possible.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/sap-upsert.png)
</Frame>

* **Deduplication:** Uses `external_reference` as the unique identifier.

  * Existing content with matching `external_reference` will be overwritten.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/sap-upsert-2.png)
</Frame>

* **Implementation Notes:**

  * **Launch Method:** Automatically set to "browser."

  * **Languages:** Ensure content titles and descriptions are provided for all relevant locales.

    * Accepted Enum Values:

      * Languages: Locale names (e.g., "English," "Spanish").

      * Result: "pass" or "fail."

  * **Course Wrapper:** A course wrapper with matching title, description, and ID is automatically created.

  * **Inactive Status:** Content initially created as inactive will not appear in the import menu. If set to inactive after import, it will appear under the "not active" filter.

### **Completion Push**

* Uses `content_external_reference` as the content identifier.

* **Unique Constraints:** Assignments are not supported for OCN content via API.

### **Provider-Specific Quirks**

* **Content Categorization:** OCN content is automatically categorized as MOOC.

### **Limitations**

* **Rate Limits:**

  * OCN: 1 request per 5 minutes, 1000 content items per request.

  * Use `/batch` operation for large catalogs.

  * Read operations: 1 request per 0.5 seconds.

### **Testing and Validation**

* Standard testing procedures apply.


# Workday LMS Integration
Source: https://docs.stackone.com/integration-guides/lms/workday

Content & Completion Management

## **Key Details**

### **Content Upsert**

* **Deduplication:** Workday uses both `external_reference` and content `title` for deduplication. Ensure both are unique during content creation.
  * If a title matches existing content, the `external_reference` will be updated.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/workday-upsert.png)
</Frame>

* **Implementation Notes:**
  * **Cover Images:** Workday requires base64 encoded images. The integration handles URL conversion, failing the upsert if the download fails.
  * **Accepted Enum Values:**
    * Languages: Locale codes (e.g., `en_gb`).
    * Result: `pass` or `fail`.
  * **Course Context:** All content is within a course.
    * A course wrapper is automatically created.
    * Default course settings: Lesson Order 1, Lesson Mandatory True, Registrable Status Open.
    * Content is set to require enrollment by default.
    * Content categorization is customer-specific; see the categories endpoint.

### **Completion Push**

* Uses `learning_object_external_reference` for content identification.
* Content is set to require enrollment by default. This can be configured at an account level. If Enrollment Required (Content) is set to No, users can launch content without enrollment, which will cause automatic completion creation.

###

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/workday-completions.png)
</Frame>

**Provider-Specific Quirks**

* **Content Categorization:** Content may be categorized as internal, even if it links to an external provider.
* **Enrollments and Completions:** Workday auto-creates these, potentially causing discrepancies.
  * **Mitigation:**
    * Completions update existing records rather than creating new ones.
    * A `DELETE user completion` endpoint is available.
    * A SCORM course blocker can be used.

## Integration Configurations

### Scorm Course Blocker

Workday fires automatic completions when a user launches a course from the UI. If the Workday course is a single content item (i.e. one lesson within the course) Workday will also complete the course at this point.

This means that there will often be a discrepancy between the real user progress on the course in the external content provider and the completion status in Workday.

Workday doesn't allow configuration on this but we can provide a Workday approved worka-around.

This will require your customer to upload a Scorm file to the Workday system which will contain a PDF instructing the user to return to and complete any previous lessons on the external content provider page before completion the Scorm lesson. As a result it blocks the completion of the course where it would normally auto-complete.

The flow is outlined below:

![images/diagram-export-20-03-2025-10\_40\_01.png](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/diagram-export-20-03-2025-10_40_01.png)

### Mobile Content Lesson

Workday doesn't support the use of additional mobile friendly content urls with a lesson. In order to help support this we can create an additional duplicate lesson in the content with a mobile specific url.

There are 2 steps to enabling this:

1. Configure the \*\*Create Duplicate Content for Mobile \*\*to Yes in the Integration Configuration
2. Include a value in the [Mobile Launch Content URL](https://docs.stackone.com/lms/api-reference/content/upsert-content#body-mobile-launch-content-url) field.

![images/Screenshot2025-03-20at10.57.44.png](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/Screenshot2025-03-20at10.57.44.png)

### **Limitations**

* **Rate Limits:** 5-10 requests per second.

### **Testing and Validation**

* Standard testing procedures apply.


# Overview
Source: https://docs.stackone.com/integration-guides/overview



Most API integrations work out-of-the-box with the standard StackOne API [integration configuration](/guides/stackone-basics#configure-an-integration). See our standard [integration connector guides](https://hub.stackone.com/integrations) for setting up a customer account.

For some providers additional setup is required to allow them to communicate with the StackOne platform or to enable new features to the existing integration and workflows beyond the scope of our standard integration offerings.&#x20;

The customer may also be presented with further configuration options to setup the integration to suit their particular environment. Depending on the integration they may also be expected see changes on their front end-use of the underlying systems.

These guides are usually optional and are only required for specific purposes. If there is any hesitation on the best course of action please get in touch with [integrations@stackone.com](mailto:integrations@stackone.com)


# Get Assignment
Source: https://docs.stackone.com/lms/api-reference/assignments/get-assignment

get /unified/lms/assignments/{id}



# List Assignments
Source: https://docs.stackone.com/lms/api-reference/assignments/list-assignments

get /unified/lms/assignments



# Get Category
Source: https://docs.stackone.com/lms/api-reference/categories/get-category

get /unified/lms/categories/{id}



# List Categories
Source: https://docs.stackone.com/lms/api-reference/categories/list-categories

get /unified/lms/categories



# Create Collection
Source: https://docs.stackone.com/lms/api-reference/collections/create-collection

post /unified/lms/collections



# Update Collection
Source: https://docs.stackone.com/lms/api-reference/collections/update-collection

patch /unified/lms/collections/{id}



# Get Completion
Source: https://docs.stackone.com/lms/api-reference/completions/get-completion

get /unified/lms/completions/{id}



# List Completions
Source: https://docs.stackone.com/lms/api-reference/completions/list-completions

get /unified/lms/completions



# Batch Upsert Content
Source: https://docs.stackone.com/lms/api-reference/content/batch-upsert-content

post /unified/lms/content/batch



# Get Content
Source: https://docs.stackone.com/lms/api-reference/content/get-content

get /unified/lms/content/{id}



# List Content
Source: https://docs.stackone.com/lms/api-reference/content/list-content

get /unified/lms/content



# Upsert Content
Source: https://docs.stackone.com/lms/api-reference/content/upsert-content

put /unified/lms/content



# Batch Upsert Course
Source: https://docs.stackone.com/lms/api-reference/courses/batch-upsert-course

post /unified/lms/courses/batch



# Get Course
Source: https://docs.stackone.com/lms/api-reference/courses/get-course

get /unified/lms/courses/{id}



# List Courses
Source: https://docs.stackone.com/lms/api-reference/courses/list-courses

get /unified/lms/courses



# Upsert Course
Source: https://docs.stackone.com/lms/api-reference/courses/upsert-course

put /unified/lms/courses



# Get Skill
Source: https://docs.stackone.com/lms/api-reference/skills/get-skill

get /unified/lms/skills/{id}



# List Skills
Source: https://docs.stackone.com/lms/api-reference/skills/list-skills

get /unified/lms/skills



# Create User Assignment
Source: https://docs.stackone.com/lms/api-reference/users/assignments/create-user-assignment

post /unified/lms/users/{id}/assignments



# Get User Assignment
Source: https://docs.stackone.com/lms/api-reference/users/assignments/get-user-assignment

get /unified/lms/users/{id}/assignments/{subResourceId}



# List User Assignments
Source: https://docs.stackone.com/lms/api-reference/users/assignments/list-user-assignments

get /unified/lms/users/{id}/assignments



# Create User Completion
Source: https://docs.stackone.com/lms/api-reference/users/completions/create-user-completion

post /unified/lms/users/{id}/completions



# Delete User Completion
Source: https://docs.stackone.com/lms/api-reference/users/completions/delete-user-completion

delete /unified/lms/users/{id}/completions/{subResourceId}



# Get User Completion
Source: https://docs.stackone.com/lms/api-reference/users/completions/get-user-completion

get /unified/lms/users/{id}/completions/{subResourceId}



# List User Completions
Source: https://docs.stackone.com/lms/api-reference/users/completions/list-user-completions

get /unified/lms/users/{id}/completions



# Get User
Source: https://docs.stackone.com/lms/api-reference/users/get-user

get /unified/lms/users/{id}



# List Users
Source: https://docs.stackone.com/lms/api-reference/users/list-users

get /unified/lms/users



# null
Source: https://docs.stackone.com/lms/common-guide/pagination



StackOne's <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip> allows paginating on API requests that return multiple records using a page cursor.

The following optional URL parameters are used for pagination:

<ParamField query="page_size" type="string" default="25">
  The number of records per page.
</ParamField>

<ParamField query="next" type="string">
  The `next` parameter is used to iterate through data pages.
</ParamField>

<Warning>
  It is recommended to keep the same page\_size throughout the sequence of pagination requests otherwise unexpected behaviour may occur.
</Warning>

## Sample URL

```
https://api.stackone.com/unified/hris/employees?page_size=25&next=eyJyIjphAsHHere
```

## Sample Response

In the response payload, you can find the `next` cursor. To get the next page of data send a new request with the `next` parameter set to this value.

```json
"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]
```

Once the cursor reaches the end of the data list, both values become NULL.

<Frame>
  ![Bypassed Records scenario](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/cd9e2c8-pagination_stripped.gif)
</Frame>

For further information see [Guides - Pagination](/guides/pagination)


# Overview
Source: https://docs.stackone.com/lms/introduction



The StackOne unified API simplifies content management across diverse LMS platforms, handling variations in standards (SCORM, xAPI) and content categorization while supporting tenant-specific data storage. It enables intuitive user matching and activity tracking without relying on provider-specific content IDs. With 2-way API interaction, LMS/LXB systems can seamlessly access content from multiple sources through a single integration.

## Benefits of the LMS API

Here are some benefits of using our LMS API that simplifies and enhances the recruitment process:

<AccordionGroup>
  <Accordion title="Sandbox Access for Seamless Testing">
    Developers can utilize sandbox environments to test integrations without affecting live data, ensuring a smooth deployment process.
  </Accordion>

  <Accordion title="Real-Time Data Synchronization">
    StackOne's APIs support real-time data polling, allowing for immediate updates and synchronization across platforms.
  </Accordion>

  <Accordion title="Privacy-First Design Ensuring Compliance">
    With a [focus on security](https://www.stackone.com/blog/why-your-choice-of-unified-api-could-make-or-break-compliance), StackOne's architecture avoids unnecessary data storage, maintaining compliance with data protection regulations.
  </Accordion>

  <Accordion title="Synthetic and Native Webhooks for Updates">
    The platform provides both [synthetic and native webhooks](/guides/webhooks), enabling real-time notifications for course updates and user progress tracking.
  </Accordion>

  <Accordion title="Comprehensive LMS Integration Coverage">
    StackOne offers [out-of-the-box integrations](https://www.stackone.com/integrations) with a wide range of LMS platforms, simplifying the integration process.
  </Accordion>
</AccordionGroup>

## Key Features

The table below highlights key features of the LMS API that enhance learning and content management:

| **Feature**             | **Description**                                                                                                           |    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- | :- |
| Comprehensive User Sync | Synchronize users data across LMS, HRIS and other platforms, including skills, activity and learning.                     |    |
| Course Management       | List and manage courses, access detailed descriptions, metadata, and learning objectives.                                 |    |
| Content Management      | Create, organize, and manage educational materials like videos, quizzes, and documents across multiple courses.           |    |
| Real-Time Webhooks      | Receive instant notifications for changes in data such as user progress, course updates, or content modifications.        |    |
| Assignment Tracking     | Monitor and manage user assignments, statuses, and progress across various courses.                                       |    |
| Progress Tracking       | Track user progress, completion statuses, and award certificates upon completion.                                         |    |
| Category Management     | Organize courses into categories for easy discovery and retrieval based on themes or topics.                              |    |
| Skills Management       | Enhanced skills tracking across jobs, users and learning content to help embed skills first people management more deeply |    |

## Entity Model and Relationships

The following diagram illustrates the key entities within the LMS API:

```mermaid
erDiagram
    User ||--o{ Assignment : ""
    User ||--o{ Completion : ""
    Course ||--o{ Assignment : ""
    Content ||--o{ Assignment : ""
    Collection ||--o{ Assignment : ""
    Course ||--o{ Content : ""
    Content ||--o{ Course : ""
    Course ||--o{ Completion : ""
    Content ||--o{ Completion : ""
    Collection ||--o{ Completion : ""
    Collection ||--o{ Content : ""
    Collection ||--o{ Course : ""
    Collection ||--o{ Skill : ""
    Collection ||--o{ Category : ""
        Course ||--o{ Skill : ""
    Course ||--o{ Category : ""
        Content ||--o{ Skill : ""
    Content ||--o{ Category : ""

    User {
        string id
        string remote_id
    }

    Assignment {
        string id
        string remote_id
        string user_id
        string learning_object_external_reference
    }

    Completion {
        string id
        string remote_id
        string user_id
        string learning_object_external_reference
    }

    Course {
        string external_reference
        array content_ids
        array Categories
        array Skills
    }

    Content {
        string external_reference
        array Content
        array Categories
        array Skills
    }

    Collection {
        string external_reference
        array learning_object_external_reference
        array Categories
        array Skills
    }

    Category {
        string id
    }

    Skill {
        string id
    }
```

The following table outlines the key entities within the LMS system represented in the diagram and provides a brief description of each:

| Entity     | Description                                                                                                                                                                                     |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User       | Represents an individual interacting with the LMS, encompassing attributes like unique identifiers, personal information, and roles within the system.                                          |
| Course     | Denotes a structured learning program, including details such as course ID, title, description, duration, and associated metadata.                                                              |
| Content    | Refers to the educational materials within a course, which can include various types such as videos, articles, quizzes, and documents, each with specific attributes like content type and URL. |
| Assignment | Represents tasks or activities assigned to users within a course, including details like due dates, instructions, and submission requirements.                                                  |
| Completion | Records the completion status of courses or modules by users, capturing information such as completion dates, scores, and certificates awarded.                                                 |
| Category   | Classifies courses into different groups or subjects, aiding in the organization and retrieval of courses based on topics or themes.                                                            |
| Skills     | Identifies key skills for content and users to help identify skills gaps and provide tailored content suggestions                                                                               |


# External Content Provider Testing Guide
Source: https://docs.stackone.com/lms/testing-integrations/testing



**Introduction**

This document outlines the testing procedures for ensuring seamless integration between your external content provider and our unified LMS platform. By following these steps, you can verify that content is correctly uploaded, updated, and that user completions are accurately recorded.

**Test Environment Setup**

* **Access Credentials:** Ensure you have the necessary API keys, authentication tokens, and LMS test user accounts.
* **Test LMS Environment:** Utilize a dedicated test LMS environment to avoid impacting live data.
* **External Content Provider Test Data:** Prepare test content with diverse metadata (titles, descriptions, URLs, etc.) and user completion scenarios.

**Testing Scenarios**

**1. Test Create Content (Upsert)**

* **Objective:** Verify that content can be created successfully via the Upsert API.
* **Steps:**
  1. **Prepare Test Data:** Create a JSON payload with the required content fields (title, description, URL, thumbnail image, duration, external\_reference).
  2. **Send Upsert Request:** Use your API client (e.g., Postman, curl) to send an Upsert request to the appropriate endpoint.
  3. **Verify Response:** Check the API response for a successful creation status (e.g., HTTP 201 Created).
  4. **LMS Verification:** Log in to the test LMS and navigate to the content library.
  5. **Check Core Fields:** Verify that the content item exists and that the title, description, URL, thumbnail, and duration match the test data.
  6. **Verify External Reference:** Ensure the content item's external\_reference matches the value provided in the request.
  7. **Clickable URL:** Click on the content item's URL within the LMS. Confirm it redirects to the external content provider's page.
* **Checklist:**
  * [ ] Successful API response (201 Created).
  * [ ] Content item appears in the LMS.
  * [ ] Title, description, URL, thumbnail, and duration are correct.
  * [ ] External\_reference is correct.
  * [ ] URL redirects to the external content provider.

**3. Test Update Content (Upsert)**

* **Objective:** Verify that existing content can be updated successfully via the Upsert API.
* **Steps:**
  1. **Create Initial Content:** First, create a content item using the Upsert API (as in step 1).
  2. **Prepare Update Data:** Modify the JSON payload, changing the title, description, or other fields, but keep the same external\_reference.
  3. **Send Upsert Request (Update):** Send the updated payload to the Upsert endpoint.
  4. **Verify Response:** Check for a successful update status (e.g., HTTP 200 OK).
  5. **LMS Verification:** Verify that the content item in the LMS has been updated with the new metadata.
* **Checklist:**
  * [ ] Successful API response (200 OK).
  * [ ] Content item in the LMS is updated.
  * [ ] Updated fields reflect the changes in the request.

**2. Test Create Content (Upsert Batch)**

* **Objective:** Verify that multiple content items can be created successfully via the Upsert Batch API.
* **Steps:**
  1. **Prepare Batch Test Data:** Create a JSON payload containing an array of multiple content objects, each with unique external\_references and diverse metadata.
  2. **Send Upsert Batch Request:** Send the request to the Upsert Batch endpoint.
  3. **Verify Response:** Check for a successful response (e.g., HTTP 202 Accepted).
  4. **Dashboard Logs Verification:** Check the dashboard logs to ensure each underlying request for the batch was processed successfully.
  5. **LMS Verification:** Verify each content item from the batch appears in the LMS.
  6. **Check Core Fields and External References:** Verify the metadata and external\_references for each content item in the LMS.
  7. **Clickable URL verification:** Verify each url redirects to the external content provider.
* **Checklist:**
  * [ ] Successful API response (202 Accepted).
  * [ ] Dashboard logs indicate all underlying requests were successful.
  * [ ] All content items from the batch appear in the LMS.
  * [ ] All core fields and external\_references are correct for each item.
  * [ ] All urls redirect to the external content provider.

**4. Test Activate/Deactivate Content**

* **Objective:** Verify that content can be activated and deactivated, affecting its visibility in the LMS.
* **Steps:**
  1. **Create Content:** Create a content item using the Upsert API.
  2. **Send Activation/Deactivation Request:** Use the appropriate API endpoint to change the content's active status (e.g., set "active": false).
  3. **Verify Response:** Check for a successful response.
  4. **LMS Verification:** Check the content's visibility in the LMS. If deactivated, it should be hidden or marked as inactive. If activated it should be visible.
  5. **Repeat:** Repeat the process to toggle the active status and verify the changes in the LMS.
* **Checklist:**
  * [ ] Successful API response.
  * [ ] Content visibility in the LMS matches the active status.

**5. Test User Completion**

* **Objective:** Verify that user completions are recorded accurately.
* **Steps:**
  1. **Complete Content (External Provider):** Simulate a user completing the content on your external platform.
  2. **Send Completion Request:** Send a completion request to the appropriate API endpoint, including the user ID, external\_reference, and completed\_at timestamp.
  3. **Verify Response:** Check for a successful response (e.g., HTTP 201 Created).
  4. **LMS Verification:** Check the user's completion records in the LMS to ensure the completion is registered with the correct user, content, and timestamp.
* **Checklist:**
  * [ ] Successful API response (201 Created).
  * [ ] Completion record appears in the LMS.
  * [ ] User ID, external\_reference, and completed\_at timestamp are correct.

**Troubleshooting**

* If you encounter any issues, please provide the following information:
  * API request and response details.
  * LMS screenshots or logs.
  * External content provider logs.
  * The external\_reference of the content in question.

By following this testing guide, you can confidently ensure your LMS integration functions correctly and provides a seamless experience for your users.


# Content and Completion Management
Source: https://docs.stackone.com/lms/unified-lms-features/lms-features

This document outlines the StackOne unified LMS features for external content provider content and completion management.

## **Content Management**

### **Upsert**

**Overview**

Our unified LMS API uses an "upsert" approach for content management, ensuring efficient synchronization across various Learning Management Systems (LMS). This means content creation requests will either update existing content or create new content based on matching criteria.

**Key Features and Behavior**

* **Primary Identifier: `external_reference`:** The API prioritizes `external_reference` for content matching. If content with the provided `external_reference` exists, it will be updated.

* **Enhanced Deduplication:**

  * In most cases, `external_reference` is sufficient.

  * If the target LMS supports deduplication based on other attributes (e.g., title), the API leverages these to enhance matching, allowing synchronization with systems containing pre-existing data.

* **Upsert Implementation:**

  * If the LMS supports native upsert, it's used directly.

  * Otherwise, a "get" operation checks for existing content using `external_reference` and/or other attributes.

* **Response:**

  * The API always returns the `external_reference`.

  * An `id` is also returned if the LMS requires it for completions/assignments (i.e., doesn't support `external_reference` for these operations).

**Workflow**

1. **Request Submission:** Send a content creation request with data and `external_reference`.

2. **Matching:** The API attempts to match content using `external_reference` and/or other attributes, leveraging native upsert when available, or a "get" check otherwise.

3. **Operation:** Existing content is updated or new content is created.

4. **Response:** The API returns `external_reference`, and `id` if necessary.

5. **Subsequent Operations:** Use `external_reference` (or `id`) for completions/assignments.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/upsert-flow.png)
</Frame>

**Important Considerations**

* Ensure `external_reference` is unique and consistent.

* The `id` is only provided when the LMS does not support the `external_reference` for completions/assignments.

* Matching can occur based on attributes beyond `external_reference` if the LMS supports it.

**Benefits**

* Simplified content management.

* Data consistency.

* Efficient operations.

* Enhanced synchronization with systems containing pre-existing data.

### **Batch Operations**

**Overview**

Our batch functionality streamlines bulk content creation, essential for integrations with LMS systems that impose strict rate limits or require batch processing (e.g. SAP). This allows you to efficiently upload large content catalogs.

**Key Features and Behavior**

* **Bulk Content Creation:** Simplifies the upload of numerous content items in a single request.

* **Rate Limit Management:** Handles LMS rate limits by queuing and processing requests as required. Some LMS systems have very low rate limits, and this feature is designed to handle those.

* **Native Batch Support:** If the target LMS supports native batch operations, the API utilizes them, managing batch sizes and rate limits automatically.

* **Fallback Batch Processing:** If native batch operations are not supported, the API splits the catalog into individual content requests, managing rate limits accordingly.

* **Automatic Batch Splitting:** If the submitted batch exceeds the LMS's maximum batch size, the API automatically splits it into smaller, compliant batches.

* **Underlying Upsert Support:** Each item within a batch request is processed using the same upsert logic as individual content requests. This ensures existing content is updated and new content is created as needed.

**Workflow**

1. **Request Submission:** Send a batch content creation request containing the complete catalog list.

2. **Validation and Queuing:** The API validates the request and, upon successful validation, returns a `202 Accepted` response. The request is then placed in a processing queue.

3. **Processing:** The API processes the queued requests, managing rate limits and batch sizes according to the LMS's requirements.

4. **LMS Interaction:** The API interacts with the LMS, either using native batch operations or individual requests

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/batch.png)
</Frame>

**Example Payload**

```json
{
  "items": [
    {
      "external_reference": "generic#lo123456789001",
      "title": "Learning Object 1",
      "description": "Generic description for learning object 1",
      "languages": [
        {
          "value": "en_US"
        }
      ],
      "content_url": "https://example.com/learning/object1",
      "content_type": {
        "source_value": "article"
      },
      "cover_url": "https://example.com/images/learning-object1.jpg",
      "active": true,
      "duration": "PT10M",
      "categories": [
        {
          "name": "Category A"
        }
      ]
    },
    {
      "external_reference": "generic#lo123456789002",
      "title": "Learning Object 2",
      "description": "Generic description for learning object 2",
      "languages": [
        {
          "value": "en_US"
        }
      ],
      "content_url": "https://example.com/learning/object2",
      "content_type": {
        "source_value": "article"
      },
      "cover_url": "https://example.com/images/learning-object2.jpg",
      "active": true,
      "duration": "PT15M",
      "categories": [
        {
          "name": "Category B"
        }
      ]
    },
    {
      "external_reference": "generic#lo123456789003",
      "title": "Learning Object 3",
      "description": "Generic description for learning object 3",
      "languages": [
        {
          "value": "en_US"
        }
      ],
      "content_url": "https://example.com/learning/object3",
      "content_type": {
        "source_value": "article"
      },
      "cover_url": "https://example.com/images/learning-object3.jpg",
      "active": true,
      "duration": "PT12M",
      "categories": [
        {
          "name": "Category C"
        }
      ]
    },
    ....
  ]
}
```

**Success Validation**

* Currently, success validation for **batch operations** is performed by checking the request logs in the StackOne UI. This allows you to verify that the requests were successfully made to the underlying provider.

* **Note:** This log checking is specific to batch operations. Individual upsert operations success can be determined by the 201 response.

**Future Enhancements**

* Return of content IDs upon initial batch request queuing.

* A response upon operation completion with a URL in the header linking to request logs.

**Important Considerations**

* It is best practice to include as many content items as possible in the batch request.

* Each item within the batch will be processed with our standard upsert behaviour.

### **Removing Content**

**Overview**

Content removal is handled through two methods, depending on LMS provider support: Soft Delete (universally available) and Hard Delete (provider-dependent).

**Removal Options**

* **Soft Delete (via Upsert):**

  * Sets content to an inactive state, preserving all associated records.

  * Effects:

    * Content is hidden from user views.

    * Content is inaccessible to users.

    * Content remains visible in admin views and API list responses.

    * Completion and assignment records are retained.

  * This is achieved by sending an upsert request with the content and an inactive status.

* **Hard Delete (via DELETE):**

  * Permanently removes content.

  * Availability: Dependent on LMS provider support.

  * Provider Restrictions: Often limited due to contractual requirements and the need to maintain completion record relationships.

**Key Considerations**

* Soft Delete is available across all providers.

* Hard Delete availability is subject to LMS provider capabilities.

* Soft delete is achieved through the upsert endpoint by sending an inactive status.

## **Assignment & Completion Management**

### **Creating Assignments & Completions**

The creation process for assignments and completions supports two distinct flows, depending on your needs and the desired level of control.

**Creation Flows:**

1. **User Assignment -> User Completion:**

   * **Create Assignment:** First, create an assignment for a specific user using:

     * The user ID.

     * The content external reference.

     * Any other required assignment data.

   * **Create Completion:** Subsequently, create a completion for the same user and content, using:

     * The user ID.

     * The content external reference.

     * Any required completion data.

   * This flow allows for explicit assignment creation and tracking before marking it as complete.

2. **User Completion:**

   * Create a completion directly using:

     * The user ID.

     * The content external reference.

     * Any required completion data.

   * This flow simplifies the process by directly marking content as complete for a user, handling any underlying assignment creation if necessary.

**Key Requirements:**

* All assignment and completion creation operations must be performed as a user sub-resource.

* The system uses the user ID and the content external reference to associate assignments and completions.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/diagram-export-13-03-2025-15_10_14.png)
</Frame>


# User Syncing
Source: https://docs.stackone.com/lms/unified-lms-features/user-syncing



## **User Management**

### **User Identification**

To ensure reliable user matching between your system and the LMS, we provide multiple identification points:

* LMS system ID
* Email address
* User name
* Additional system-specific identifiers (returned as `external_reference`)

**Filtering**

* We support email filtering when natively supported by the LMS.
* Currently, email filtering is supported on GO1.

**Recommended Sync Process**

* **Initial Setup:**
  * Store the StackOne ID for each matched user in your database.
  * This ID is essential for creating assignments, recording completions, and maintaining user relationships.
* **Ongoing Maintenance:**
  * Implement a regular synchronization process:
    * Fetch current user data from `/lms/users` endpoint.
    * Compare against your local user database.
    * Update local records with any changes.
    * Store new StackOne IDs for newly matched users.
  * This approach ensures consistent user identification and data accuracy.

<Frame>
  ![](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/users.png)
</Frame>


# Unified External Learning Content and Completion Sync
Source: https://docs.stackone.com/lms/use-cases/learning-content-provider-lms-use-case

Automate intelligent learning content sync and real-time completion tracking to enhance your SaaS with seamless learning updates

![learning-content-provider-banner](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/banner-learning-content-provider-lms.png)

Imagine you’re enhancing your SaaS platform to simplify learning content management and track user course completions in real-time. At first, it might seem straightforward, but keeping content updated and syncing user progress accurately in multiple LMS providers can quickly become complex.

Ensuring real-time updates for both learning content and completion data requires efficient automation and syncing, giving users a seamless experience while reducing manual tasks for your team.

<ResponseField name="StackOne simplifies all of this by offering:">
  <Expandable title="StackOne Features">
    <ResponseField name="Why StackOne?">
      * **Unified API** connecting multiple LMS to manage and sync learning content, avoiding manual integrations.
      * **Scalability** that lets you easily add new LMS providers as your needs grow.
      * **Standardized data formats** across LMS providers for consistent and simplified data management.
    </ResponseField>
  </Expandable>
</ResponseField>

## Intelligent Learning Content Management for Your Platform: Key Steps and System Interactions

Integrating intelligent learning content management into your SaaS platform allows you to automate course updates, track user progress in real-time, and maintain seamless learning experiences for your users.

### Steps for Enabling Intelligent Learning Content Sync and Completion Tracking

Below are the steps to set up intelligent learning content management and completion tracking, helping you efficiently manage course content, sync completion data, and enhance user engagement on your platform.

<Steps>
  <Step title="Set Up the LMS Connection and Sync Content">
    After setting up the account, you can make the same unified requests to all LMS providers, using the `x-account-id` to differentiate between them.

    You can use the batch endpoint to push the entire catalogue leaving StackOne to handle rate-limits, batch size and underlying LMS behaviour.

    In addition, you can use the `external_reference`, an identifier determined by you, to identify the content in the LMS removing the need to store and maintain ids.

    * **API Endpoint**: [POST lms/content/batch](https://docs.stackone.com/reference/lms_batch_upsert_content)
  </Step>

  <Step title="Select and Push Specific Content">
    You can use the same endpoint to sync and manage content updates, and you can use the `external_reference` to identify the content in the LMS.

    * **API Endpoint**: [POST lms/content/batch](https://docs.stackone.com/reference/lms_batch_upsert_content)
  </Step>

  <Step title="Sync Users from LMS">
    **Either**

    Allow admins to retrieve a list of all users from the LMS provider, including details like `id`, `name`, `email_address`, `external_reference`, etc.

    We provide as many identifier fields as possible to ensure you are able to match users across platforms.

    * **API Endpoint:** [GET /lms/users](https://docs.stackone.com/reference/lms_list_users)

    **Or**

    Use the list users filter to fetch a user by external reference. This is the most likely identifier which is provided by the LMS platform in the SSO handshake.

    * **API Endpoint:** [GET /lms/users?filter\[external\_reference\]=\{\{external\_reference}}](https://docs.stackone.com/reference/lms_list_users)
  </Step>

  <Step title="Enable Manual Content Re-Sync">
    Sometimes, admins may need to update content to selected LMS providers from the dashboard. Enable a manual re-sync button in the admin interface so they can refresh and update the content whenever needed.
  </Step>

  <Step title="Sync Course Completions for Tracking">
    You can track user progress through content and fire a completion event once the user has consumed the content, using the end user’s `id` and `learning_object_external_reference`, along with details like `result` and `completed_at`.

    This allows you to manage the completions without storing content data in a set and foget fashion.

    * **API Endpoint:** [POST /lms/users/\{id}/completions](https://docs.stackone.com/reference/lms_create_user_completion)
  </Step>
</Steps>

The diagram outlines the key steps: uploading content, choosing specific courses, and tracking user progress. Each step helps admins keep content organized and monitor user engagement effectively.

![learning-content-provider-flow-diagram](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/learning-content-provider-lms-flow-diagram.png)

## Conclusion

This guide showed how to set up smart content management and track content completions in your SaaS platform. By using the given API endpoints, admins can upload content in bulk, enable manual re-syncs, and track users’ progress in real-time. This setup helps keep easily manage content in your customer LMS, and ensures users have a smooth and engaging learning experience.


# Get campaign
Source: https://docs.stackone.com/marketing/api-reference/campaigns/get-campaign

get /unified/marketing/campaigns/{id}



# List campaigns
Source: https://docs.stackone.com/marketing/api-reference/campaigns/list-campaigns

get /unified/marketing/campaigns



# Create Content Block
Source: https://docs.stackone.com/marketing/api-reference/content-blocks/create-content-block

post /unified/marketing/content_blocks



# Get Content Blocks
Source: https://docs.stackone.com/marketing/api-reference/content-blocks/get-content-blocks

get /unified/marketing/content_blocks/{id}



# List Content Blocks
Source: https://docs.stackone.com/marketing/api-reference/content-blocks/list-content-blocks

get /unified/marketing/content_blocks



# Update Content Block
Source: https://docs.stackone.com/marketing/api-reference/content-blocks/update-content-block

patch /unified/marketing/content_blocks/{id}



# Create Email Templates
Source: https://docs.stackone.com/marketing/api-reference/templates/email/create-email-templates

post /unified/marketing/templates/email



# Get Email Templates
Source: https://docs.stackone.com/marketing/api-reference/templates/email/get-email-templates

get /unified/marketing/templates/email/{id}



# List Email Templates
Source: https://docs.stackone.com/marketing/api-reference/templates/email/list-email-templates

get /unified/marketing/templates/email



# Update Email Templates
Source: https://docs.stackone.com/marketing/api-reference/templates/email/update-email-templates

patch /unified/marketing/templates/email/{id}



# Create In-App Template
Source: https://docs.stackone.com/marketing/api-reference/templates/in-app/create-in-app-template

post /unified/marketing/templates/in_app



# Get In-App Template
Source: https://docs.stackone.com/marketing/api-reference/templates/in-app/get-in-app-template

get /unified/marketing/templates/in_app/{id}



# List In-App Templates
Source: https://docs.stackone.com/marketing/api-reference/templates/in-app/list-in-app-templates

get /unified/marketing/templates/in_app



# Update In-App Template
Source: https://docs.stackone.com/marketing/api-reference/templates/in-app/update-in-app-template

patch /unified/marketing/templates/in_app/{id}



# Create Omni-Channel Template
Source: https://docs.stackone.com/marketing/api-reference/templates/omni-channel/create-omni-channel-template

post /unified/marketing/templates/omni_channel

<Warning>
  **This endpoint is deprecated**   <Icon icon="triangle-exclamation" color="#fbbf24" size={19} />
</Warning>


# Get Omni-Channel Template
Source: https://docs.stackone.com/marketing/api-reference/templates/omni-channel/get-omni-channel-template

get /unified/marketing/templates/omni_channel/{id}

<Warning>
  **This endpoint is deprecated**   <Icon icon="triangle-exclamation" color="#fbbf24" size={19} />
</Warning>


# List Omni-Channel Templates
Source: https://docs.stackone.com/marketing/api-reference/templates/omni-channel/list-omni-channel-templates

get /unified/marketing/templates/omni_channel

<Warning>
  **This endpoint is deprecated**   <Icon icon="triangle-exclamation" color="#fbbf24" size={19} />
</Warning>


# Update Omni-Channel Template
Source: https://docs.stackone.com/marketing/api-reference/templates/omni-channel/update-omni-channel-template

patch /unified/marketing/templates/omni_channel/{id}

<Warning>
  **This endpoint is deprecated**   <Icon icon="triangle-exclamation" color="#fbbf24" size={19} />
</Warning>


# Create Push Template
Source: https://docs.stackone.com/marketing/api-reference/templates/push/create-push-template

post /unified/marketing/templates/push



# Get Push Template
Source: https://docs.stackone.com/marketing/api-reference/templates/push/get-push-template

get /unified/marketing/templates/push/{id}



# List Push Templates
Source: https://docs.stackone.com/marketing/api-reference/templates/push/list-push-templates

get /unified/marketing/templates/push



# Update Push Template
Source: https://docs.stackone.com/marketing/api-reference/templates/push/update-push-template

patch /unified/marketing/templates/push/{id}



# Create SMS Template
Source: https://docs.stackone.com/marketing/api-reference/templates/sms/create-sms-template

post /unified/marketing/templates/sms



# Get SMS Template
Source: https://docs.stackone.com/marketing/api-reference/templates/sms/get-sms-template

get /unified/marketing/templates/sms/{id}



# List SMS Templates
Source: https://docs.stackone.com/marketing/api-reference/templates/sms/list-sms-templates

get /unified/marketing/templates/sms



# Update SMS Template
Source: https://docs.stackone.com/marketing/api-reference/templates/sms/update-sms-template

patch /unified/marketing/templates/sms/{id}



# null
Source: https://docs.stackone.com/marketing/common-guide/pagination



StackOne's <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip> allows paginating on API requests that return multiple records using a page cursor.

The following optional URL parameters are used for pagination:

<ParamField query="page_size" type="string" default="25">
  The number of records per page.
</ParamField>

<ParamField query="next" type="string">
  The `next` parameter is used to iterate through data pages.
</ParamField>

<Warning>
  It is recommended to keep the same page\_size throughout the sequence of pagination requests otherwise unexpected behaviour may occur.
</Warning>

## Sample URL

```
https://api.stackone.com/unified/hris/employees?page_size=25&next=eyJyIjphAsHHere
```

## Sample Response

In the response payload, you can find the `next` cursor. To get the next page of data send a new request with the `next` parameter set to this value.

```json
"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]
```

Once the cursor reaches the end of the data list, both values become NULL.

<Frame>
  ![Bypassed Records scenario](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/cd9e2c8-pagination_stripped.gif)
</Frame>

For further information see [Guides - Pagination](/guides/pagination)


# Overview
Source: https://docs.stackone.com/marketing/overview



The StackOne unified marketing API that includes operations for campaigns and message templates offers a centralized interface to create, manage, and analyze marketing initiatives across multiple channels. By standardizing essential tasks like campaign scheduling, message design, and data collection, it ensures consistency, fosters collaboration, and streamlines marketing workflows.

Entities such as sms templates, push templates, email templates and campaigns form the backbone of our system, offering comprehensive tools to create cohesive and impactful marketing campaigns.

## Benefits of the StackOne Marketing API

<AccordionGroup>
  <Accordion title="Sandbox Access for Seamless Testing">
    Developers can utilize sandbox environments to test integrations without affecting live data, ensuring a smooth deployment process.
  </Accordion>

  <Accordion title="Real-Time Data Synchronization">
    StackOne's APIs support real-time data polling, allowing for immediate updates and synchronization across platforms.
  </Accordion>

  <Accordion title="Privacy-First Design Ensuring Compliance">
    With a [focus on security](https://www.stackone.com/blog/why-your-choice-of-unified-api-could-make-or-break-compliance), StackOne's architecture avoids unnecessary data storage, maintaining compliance with data protection regulations.
  </Accordion>

  <Accordion title="Synthetic and Native Webhooks for Updates">
    The platform provides both [synthetic and native webhooks](/guides/webhooks), enabling real-time notifications for campaign, lead, and customer interaction changes.
  </Accordion>

  <Accordion title="Comprehensive Marketing Integration Coverage">
    StackOne offers [out-of-the-box integrations](https://www.stackone.com/integrations) with a wide range of marketing platforms, simplifying the integration process.
  </Accordion>
</AccordionGroup>

## Key Features

| **Feature**                    | **Description**                                                                                   |
| ------------------------------ | ------------------------------------------------------------------------------------------------- |
| Campaign Management            | Easily retrieve marketing campaigns and manage targeted content.                                  |
| Real-Time Data Synchronization | Ensure that templates and template data are updated across systems instantly.                     |
| Real-Time Webhooks             | Receive instant notifications for changes in leads, campaign statuses, or customer interactions.  |
| A/B Testing and Optimization   | Test multiple versions of campaigns and optimize content and messaging based on performance data. |

## Entity Model and Relationships

The following diagram illustrates the key entities within the Marketing API:

```mermaid
erDiagram
    CAMPAIGN {
        string id
        string name
        string description
        string status
        string schedule_type
        boolean archived
        boolean draft
        string[] tags
    }
    CONTENTBLOCK {
        string id
        string name
        string type
        string content
        string status
    }
    EMAILTEMPLATE {
        string id
        string subject
        string body
        string from
        string reply-to
    }
    SMSTEMPLATE {
        string id
        string body
        string from
    }
    PUSHTEMPLATE {
        string id
        string title
        string subtitle
        string body
    }
    INAPPTEMPLATE {
        string id
        string body
    }
    MESSAGES {
        string id
        string name
        string message_type
        string message_content
    }

    MESSAGES ||--|{ EMAILTEMPLATE : ""
    MESSAGES ||--|{ SMSTEMPLATE : ""
    MESSAGES ||--|{ PUSHTEMPLATE : ""
    MESSAGES ||--|{ INAPPTEMPLATE : ""
    CAMPAIGN ||--o{ MESSAGES : ""
    CONTENTBLOCK ||--o{ MESSAGES : ""
```

## Entity Definitions

| Entity          | Description                                                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Campaigns       | Manages marketing campaigns, encompassing planning, execution, tracking, and analysis of marketing initiatives across various channels.    |
| Messages        | A combined array of messages that could be of any SMS, Push, Email and In app templates.                                                   |
| SMS templates   | Templates designed for targeted mobile campaigns using SMS messages                                                                        |
| Push templates  | Templates for push notifications, optimized for engagement and reach on mobile and web applications.                                       |
| Email templates | Pre-designed layouts and styles for email campaigns, simplifying the process of creating professional and consistent email communications. |
| Campaigns       | Manages marketing campaigns, encompassing planning, execution, tracking, and analysis of marketing initiatives across various channels.    |


# Delete Account
Source: https://docs.stackone.com/platform/api-reference/accounts/delete-account

delete /accounts/{id}



# Get Account
Source: https://docs.stackone.com/platform/api-reference/accounts/get-account

get /accounts/{id}



# Get meta information of the account
Source: https://docs.stackone.com/platform/api-reference/accounts/get-meta-information-of-the-account

get /accounts/{id}/meta



# List Accounts
Source: https://docs.stackone.com/platform/api-reference/accounts/list-accounts

get /accounts



# Update Account
Source: https://docs.stackone.com/platform/api-reference/accounts/update-account

patch /accounts/{id}



# Authenticate Connect Session
Source: https://docs.stackone.com/platform/api-reference/connect-sessions/authenticate-connect-session

post /connect_sessions/authenticate



# Create Connect Session
Source: https://docs.stackone.com/platform/api-reference/connect-sessions/create-connect-session

post /connect_sessions



# Get Connector Meta information for the given provider key
Source: https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information-for-the-given-provider-key

get /connectors/meta/{provider}



# List Connectors Meta Information for all providers
Source: https://docs.stackone.com/platform/api-reference/connectors/list-connectors-meta-information-for-all-providers

get /connectors/meta



# Proxy Request
Source: https://docs.stackone.com/platform/api-reference/proxy/proxy-request

post /unified/proxy



# Get a Log
Source: https://docs.stackone.com/platform/api-reference/request-logs/get-a-log

get /requests/logs/{id}



# List Logs
Source: https://docs.stackone.com/platform/api-reference/request-logs/list-logs

get /requests/logs



# List Step Logs
Source: https://docs.stackone.com/platform/api-reference/request-logs/list-step-logs

get /requests/logs/steps



# Overview
Source: https://docs.stackone.com/platform/introduction



The Platform API empowers you to programmatically retrieve information such as session tokens and account details about any linked accounts or available integrations.

## Authentication

To connect your application with StackOne securely, you need to generate [API Keys](/guides/api-keys). These keys authenticate your application and protect your data.

Once you've generated your API Key, it's essential to know how to use it for authentication.

You will need to include the API Key for every API call. You can use the API Key in the username or password field when calling any API endpoint, such as the List Accounts endpoint.

## Key Features

| **Feature**                | **Description**                                                                                     |
| -------------------------- | --------------------------------------------------------------------------------------------------- |
| Connect Session Tokens     | Generate connection session tokens or auth URLs to get your customers to connect their accounts.    |
| Listing Linked Accounts    | Fetch and manage all Linked Accounts, including retrieving specific Account IDs.                    |
| Enabled Connectors Details | Retrieve a list of enabled Connectors with detailed support information, including required fields. |
| Webhooks                   | Trigger webhooks payload (eg. to test your webhook endpoint)                                        |


# Create Screening Order
Source: https://docs.stackone.com/screening/api-reference/orders/create-screening-order

post /unified/screening/orders



# Get Screening Package
Source: https://docs.stackone.com/screening/api-reference/packages/get-screening-package

get /unified/screening/packages/{id}



# List Screening Packages
Source: https://docs.stackone.com/screening/api-reference/packages/list-screening-packages

get /unified/screening/packages



# Webhook Screening Result
Source: https://docs.stackone.com/screening/api-reference/results/webhook-screening-result

post /unified/screening/results/webhook



# null
Source: https://docs.stackone.com/screening/common-guide/pagination



StackOne's <Tooltip tip="Unified API - A Unified API is an application programming interface (API) that streamlines developers' access to information from diverse sources via a single interface">Unified API</Tooltip> allows paginating on API requests that return multiple records using a page cursor.

The following optional URL parameters are used for pagination:

<ParamField query="page_size" type="string" default="25">
  The number of records per page.
</ParamField>

<ParamField query="next" type="string">
  The `next` parameter is used to iterate through data pages.
</ParamField>

<Warning>
  It is recommended to keep the same page\_size throughout the sequence of pagination requests otherwise unexpected behaviour may occur.
</Warning>

## Sample URL

```
https://api.stackone.com/unified/hris/employees?page_size=25&next=eyJyIjphAsHHere
```

## Sample Response

In the response payload, you can find the `next` cursor. To get the next page of data send a new request with the `next` parameter set to this value.

```json
"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]
```

Once the cursor reaches the end of the data list, both values become NULL.

<Frame>
  ![Bypassed Records scenario](https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/images/cd9e2c8-pagination_stripped.gif)
</Frame>

For further information see [Guides - Pagination](/guides/pagination)


# Overview
Source: https://docs.stackone.com/screening/introduction



A unified Screening API overcomes typical integration challenges by standardizing inconsistent data models, normalizing varied terminology, and creating a consistent entity structure where candidate screening data, background checks, assessments, and results exist predictably regardless of which screening provider your customer uses.

## Benefits of StackOne Screening API

Here are some benefits of using our Screening API that simplifies and enhances candidate screening processes:

<AccordionGroup>
  <Accordion title="Sandbox Access for Seamless Testing">
    Developers can utilize sandbox environments to test screening integrations without affecting live data or triggering actual background checks, ensuring a smooth deployment process.
  </Accordion>

  <Accordion title="Standardized Endpoints for Screening Management">
    StackOne provides endpoints not just for initiating screenings but also for managing the entire screening lifecycle, making it easier to customize hiring workflows.
  </Accordion>

  <Accordion title="Privacy-First Design Ensuring Compliance">
    With a [focus on security](https://www.stackone.com/blog/why-your-choice-of-unified-api-could-make-or-break-compliance), StackOne's architecture ensures secure handling of sensitive candidate data, maintaining compliance with FCRA and data protection regulations.
  </Accordion>

  <Accordion title="Synthetic and Native Webhooks for Updates">
    The platform provides both [synthetic and native webhooks](/guides/webhooks), enabling real-time notifications for screening status changes and results.
  </Accordion>

  <Accordion title="Comprehensive Screening Provider Coverage">
    StackOne offers [out-of-the-box integrations](https://www.stackone.com/integrations) with leading background check and assessment providers, simplifying the integration process.
  </Accordion>

  <Accordion title="Scalability and Ease of Use">
    The unified API allows for scalable and efficient integration, reducing the time and resources required for implementing multiple screening providers.
  </Accordion>
</AccordionGroup>

## Key Features

The table below shows key features of the Screening API that make candidate screening easier, from background checks to skills assessments:

| **Feature**                 | **Description**                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------- |
| Background Check Management | Easily initiate, track, and retrieve results for various types of background checks.  |
| Assessment Integration      | Manage candidate assessments, from technical skills tests to personality evaluations. |
| Real-Time Webhooks          | Receive instant notifications for screening status updates and completed results.     |

## Entity Model and Relationships

The following diagram illustrates the key entities within the Screening API:

```mermaid
erDiagram
    Candidate {
        string id
        string first_name
        string last_name
        string email
    }

    ScreeningOrder {
        string id
        string remote_id
        string package_id
        string candidate_id
        object passthrough
        object unified_custom_fields
    }

    ScreeningPackage {
        string id
        string remote_id
        string name
        string description
        object unified_custom_fields
    }

    ScreeningResult {
        string id
        string remote_id
        string order_id
        string summary
        string status
        string result_url
        datetime start_date
        datetime submission_date
        object unified_custom_fields
    }

    ResultScore {
        string label
        string value
        string min
        string max
    }

    WebhookEvent {
        string event
        object data
        array raw
    }

    Candidate ||--o{ ScreeningOrder : "requests"
    ScreeningPackage ||--o{ ScreeningOrder : "uses"
    ScreeningOrder ||--o{ ScreeningResult : "produces"
    ScreeningResult ||--|| ResultScore : "has"
    ScreeningResult ||--o{ WebhookEvent : "triggers"
```

The following table outlines key entities within the Screening system and provides a brief description of each.

| Entity           | Description                                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Candidate        | Contains essential candidate information required for screening, including first name, last name, and email.                    |
| ScreeningOrder   | Represents a screening request for a candidate using a specific package, including any custom fields or provider-specific data. |
| ScreeningPackage | Defines available screening services, including name, description, and provider-specific configuration.                         |
| ScreeningResult  | Contains the outcome of a screening order, including status, summary, scoring, and access to detailed results.                  |
| ResultScore      | Represents the scoring details of a screening result, with label, value, and score range.                                       |
| Provider         | Represents the screening service providers integrated with the system.                                                          |
| WebhookEvent     | Defines the structure of webhook notifications for screening status updates and results.                                        |

The API supports the following screening result statuses:

* `pending`: Initial state when the screening is requested

* `in_progress`: Screening is currently being processed

* `completed`: Screening has been successfully completed

* `failed`: Screening process encountered an error

* `cancelled`: Screening was cancelled before completion

Webhook events are triggered for the following scenarios:

* `screening.result.created`: New screening result created

* `screening.result.updated`: Existing result updated

* `screening.result.completed`: Screening process completed

* `screening.result.failed`: Screening process failed

* `screening.result.cancelled`: Screening was cancelled

## Use cases

<CardGroup cols={3}>
  <Card title="Automated Background Checks">
    Streamline your hiring process by automatically initiating background checks when candidates reach specific stages.
  </Card>

  <Card title="Assessment Integration">
    Seamlessly incorporate skills assessments and personality tests into your hiring workflow.
  </Card>
</CardGroup>