### Integration Setup Example

Source: https://docs.kombo.dev/assessment/v1/post-connect-activate-integration

Example of a successful integration setup object.

```yaml
tool: personio
id: personio:CBNMt7dSNCzBdnRTx87dev4E
end_user_origin_id: '36123'
end_user_organization_name: Acme, Inc.
end_user_email: user@example.com
setup_status: COMPLETED
```

--------------------------------

### Get Integration Fields SDK Examples

Source: https://docs.kombo.dev/assessment/v1/get-integrations-integration-id-integration-fields

SDK implementation examples for retrieving integration fields in TypeScript, Ruby, and Python.

```typescript
import { Kombo } from "@kombo-api/sdk";

const kombo = new Kombo({
  api_key: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await kombo.general.getIntegrationFields({
    integration_id: "<id>",
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();
```

```ruby
require 'kombo'


Models = ::Kombo::Models

s = ::Kombo::Kombo.new(
      security: Models::Shared::Security.new(
        api_key: '<YOUR_BEARER_TOKEN_HERE>',
      ),
    )

res = s.general.get_integration_fields(integration_id: '<id>',
page_size: 100)


unless
res.get_integrations_integration_id_integration_fields_positive_response.nil?
  # handle response
end
```

```python
from kombo import Kombo


with Kombo(
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:
```

--------------------------------

### Retrieve Application Stage Information

Source: https://docs.kombo.dev/ats/implementation-guide/reading-applicants

Example response from the GET Applications endpoint showing current_stage_id and current_stage properties.

```json
{
  "status": "success",
  "data": {
    "next": "eyJwYWdlIjoxMiwibm90ZSI6InRoaXMgaXMganVzdCBhbiBleGFtcGxlIGFuZCBub3QgcmVwcmVzZW50YXRpdmUgZm9yIGEgcmVhbCBjdXJzb3IhIn0=",
    "results": [
      {
        "id": "26vafvWSRmbhNcxJYqjCzuJg",
        "remote_id": "32",
        ...
        "current_stage_id": "5J7L4b48wBfffYwek9Az9pkM",
        ...
        "current_stage": {
          "id": "5J7L4b48wBfffYwek9Az9pkM",
          "remote_id": "32",
          "name": "Initial Screening"
        },
      }
    ]
  }
}
```

--------------------------------

### Get Tools Category in Python

Source: https://docs.kombo.dev/ats/v1/get-tools-category

This Python example shows how to fetch tools by category using the Kombo client. It utilizes a context manager for client initialization and handles the response.

```python
from kombo import Kombo


with Kombo(
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:

    res = k_client.general.get_tools(category="ats")

    # Handle response
    print(res)
```

--------------------------------

### Get Integration Details by ID

Source: https://docs.kombo.dev/lms/v1/get-integrations-integration-id

Use these examples to fetch detailed information about a specific integration using its unique identifier.

```ruby
require 'kombo'

Models = ::Kombo::Models
s = ::Kombo::Kombo.new(
      security: Models::Shared::Security.new(
        api_key: '<YOUR_BEARER_TOKEN_HERE>',
      ),
    )

res = s.general.get_integration_details(integration_id: '<id>')

unless res.get_integrations_integration_id_positive_response.nil?
  # handle response
end
```

```python
from kombo import Kombo


with Kombo(
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:

    res = k_client.general.get_integration_details(integration_id="<id>")

    # Handle response
    print(res)
```

--------------------------------

### Get Filtering Setup Link via API

Source: https://docs.kombo.dev/hris/implementation-guide/filtering-employees/using-the-filtering-ui

Retrieve a link to configure filters retroactively for an integration. The `group_id` should typically be 'default', and the `X-Integration-Id` header is required.

```bash
curl --request POST \
  --url https://api.kombo.dev/v1/hris/provisioning-groups/{group_id}/setup-links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Integration-Id: <x-integration-id>' \
  --data '{ \
  "language": "en" \
}'
```

--------------------------------

### Fetch Users with Kombo SDK (TypeScript)

Source: https://docs.kombo.dev/ats/v1/get-users

Use the Kombo SDK to fetch users. This example demonstrates basic usage and iterating through paginated results. Ensure you have the SDK installed and your API key is configured.

```typescript
import { Kombo } from "@kombo-api/sdk";

const kombo = new Kombo({
  integration_id: "workday:HWUTwvyx2wLoSUHphiWVrp28",
  api_key: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await kombo.ats.getUsers({});

  for await (const page of result) {
    console.log(page);
  }
}

run();
```

--------------------------------

### Get ATS Applications (Python)

Source: https://docs.kombo.dev/ats/v1/get-applications

Fetches ATS applications in Python. This example demonstrates using a context manager for the Kombo client and iterating through paginated results.

```python
from kombo import Kombo


with Kombo(
    integration_id="workday:HWUTwvyx2wLoSUHphiWVrp28",
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:

    res = k_client.ats.get_applications(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()
```

--------------------------------

### Get Integration by Token (Ruby)

Source: https://docs.kombo.dev/assessment/v1/get-connect-integration-by-token-token

Retrieve integration details using a token from the connection flow. This Ruby example demonstrates how to initialize the Kombo client and make the request, handling potential responses.

```ruby
require 'kombo'


Models = ::Kombo::Models

s = ::Kombo::Kombo.new(
      security: Models::Shared::Security.new(
        api_key: '<YOUR_BEARER_TOKEN_HERE>',
      ),
    )

res = s.connect.get_integration_by_token(token: '<value>')


unless
res.get_connect_integration_by_token_token_positive_response.nil?
  # handle response
end
```

--------------------------------

### Add Candidate Result Link with Python

Source: https://docs.kombo.dev/ats/v1/post-candidates-candidate-id-result-links

This Python example shows how to add a result link for a candidate using the Kombo client. Ensure the Kombo library is installed and your credentials are set.

```python
from kombo import Kombo


with Kombo(
    integration_id="workday:HWUTwvyx2wLoSUHphiWVrp28",
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:

    res = k_client.ats.add_candidate_result_link(candidate_id="8Xi6iZrwusZqJmDGXs49GBmJ", label="Assessment Result", url="https://example.com/test-results/5BtP1WC1UboS7CF3yxjKcvjG", details={
        "custom_field_name_prefix": "Acme:",
        "attributes": [
            {
                "key": "Score",
                "value": "100%",
            },
            {
                "key": "Time",
                "value": "2:30h",
            },
        ],
    })

    # Handle response
    print(res)
```

--------------------------------

### Get Employees API Response Example

Source: https://docs.kombo.dev/hris/v1/get-employees?playground=open

Example of a successful JSON response structure from the Get Employees endpoint.

```JSON
{
  "status": "success",
  "data": {
    "next": "eyJwYWdlIjoxMiwibm90ZSI6InRoaXMgaXMganVzdCBhbiBleGFtcGxlIGFuZCBub3QgcmVwcmVzZW50YXRpdmUgZm9yIGEgcmVhbCBjdXJzb3IhIn0=",
    "results": [
```

--------------------------------

### POST /hris/provisioning-groups/{group_id}/setup-links

Source: https://docs.kombo.dev/assessment/v1/post-hris-provisioning-groups-group-id-setup-links

Create a new link that can be passed to the Kombo Connect SDK to open the provisioning setup UI.

```APIDOC
## POST /hris/provisioning-groups/{group_id}/setup-links

### Description
Create a new link that can be passed to the Kombo Connect SDK to open the provisioning setup UI.

### Method
POST

### Endpoint
/hris/provisioning-groups/{group_id}/setup-links

### Parameters
#### Path Parameters
- **group_id** (string) - Required - ID of the provisioning group (currently only `default` is allowed).

#### Header Parameters
- **X-Integration-Id** (string) - Required - ID of the integration you want to interact with.

#### Request Body
- **language** (string) - Optional - Language of the UI (en, de, fr, it, es). Defaults to en.

### Request Example
{
  "language": "en"
}

### Response
#### Success Response (200)
- **status** (string) - Success status.
- **data** (object) - Response data containing the URL and expiration.
  - **url** (string) - The setup link URL to pass to the Kombo Connect SDK.
  - **expires_at** (string) - When this link expires.

#### Response Example
{
  "status": "success",
  "data": {
    "url": "https://connect.kombo.dev/v1/setup?token=GinuMJCpUQ9xdpLmD2ocw8qdiK3qiPCizDCv754EXri2vAX4",
    "expires_at": "2023-10-11T12:00:00.000Z"
  }
}
```

--------------------------------

### Initialize Kombo SDK and Fetch Employees (Ruby)

Source: https://docs.kombo.dev/libraries-and-sdks

Initialize the Kombo SDK with your integration ID and API key, then fetch a list of employees. Replace '<YOUR_BEARER_TOKEN_HERE>' with your actual token.

```ruby
require 'kombo'

Models = ::Kombo::Models
s = ::Kombo::Kombo.new(
  integration_id: 'workday:HWUTwvyx2wLoSUHphiWVrp28',
  security: Models::Shared::Security.new(
    api_key: '<YOUR_BEARER_TOKEN_HERE>',
  ),
)

res = s.hris.get_employees()
```

--------------------------------

### Get HRIS Absence Types with Kombo SDK

Source: https://docs.kombo.dev/hris/v1/get-absence-types

Fetches HRIS absence types using the Kombo SDK. This example demonstrates iterating through paginated results. Ensure you have the SDK installed and your API key is configured.

```typescript
import { Kombo } from "@kombo-api/sdk";

const kombo = new Kombo({
  integration_id: "workday:HWUTwvyx2wLoSUHphiWVrp28",
  api_key: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await kombo.hris.getAbsenceTypes({});

  for await (const page of result) {

```

--------------------------------

### Initialize Kombo SDK and Fetch Employees (Python)

Source: https://docs.kombo.dev/libraries-and-sdks

Initialize the Kombo SDK with your API key and integration ID, then fetch a list of employees. Replace '<YOUR_BEARER_TOKEN_HERE>' with your actual token.

```python
from kombo import Kombo

with Kombo(
    api_key="<YOUR_BEARER_TOKEN_HERE>",
    integration_id="workday:HWUTwvyx2wLoSUHphiWVrp28",
) as kombo:
    result = kombo.hris.get_employees()

    print(result)
```

--------------------------------

### OpenAPI Specification for Get Integration Details

Source: https://docs.kombo.dev/ats/v1/get-integrations-integration-id

The OpenAPI definition for the GET /integrations/{integration_id} endpoint, including schema references and example response data.

```yaml
openapi: 3.1.0
info:
  title: Kombo API
  version: 1.0.0
servers:
  - url: https://api.kombo.dev/v1
    description: Kombo EU API
  - url: https://api.us.kombo.dev/v1
    description: Kombo US API
security:
  - ApiKey: []
tags:
  - name: General
  - name: Kombo Connect
    description: >-
      Endpoints for Kombo Connect, our end-user-facing flow for setting up new
      integrations.
  - name: Unified HRIS API
    description: Unified endpoints to access all the HR concepts you might need.
  - name: Unified ATS API
    description: Unified endpoints to access all the ATS concepts you might need.
  - name: Unified ATS (Assessment & Background Check) API
    description: >-
      Unified endpoints to operate Assessments and Background Checks for many
      applicant tracking systems.
  - name: Unified LMS API
    description: Unified endpoints to access all the LMS concepts you might need.
  - name: AI Apply
    description: Endpoints for AI-powered job application features.
  - name: Custom Endpoints
    description: Custom integration-specific endpoints.
paths:
  /integrations/{integration_id}:
    get:
      tags:
        - General
      summary: Get integration details
      description: >-
        Get the specified integration with everything you need to display it to
        your customer.
      operationId: GetIntegrationsIntegrationId
      parameters:
        - name: integration_id
          in: path
          required: true
          description: GET /integrations/:integration_id Parameter
          schema:
            $ref: >-
              #/components/schemas/GetIntegrationsIntegrationIdParameterIntegrationId
      responses:
        '200':
          description: GET /integrations/:integration_id Positive response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/GetIntegrationsIntegrationIdPositiveResponse
              examples:
                example1:
                  value:
                    status: success
                    data:
                      id: factorial:8d1hpPsbjxUkoCoa1veLZGe5
                      tool:
                        id: factorial
                        label: Factorial
                        internal_label: null
                        logo_url: >-
                          https://storage.googleapis.com/kombo-assets/integrations/factorial/logo.svg
                        icon_url: >-
                          https://storage.googleapis.com/kombo-assets/integrations/factorial/icon.svg
                      category: HRIS
                      status: ACTIVE
                      setup_status: COMPLETED
                      end_user:
                        organization_name: Acme
                        creator_email: example-integration-creator@acme.com
                        origin_id: 2DQJAUtSzzzKP9buDTvUvPk3
                      scope_config:
                        id: B1hu5NGyhdjSq5X3hxEz4bAN
                        name: Anonymous Scopes
                      data_expired_at: null
                      created_at: '2022-08-07T14:01:29.196Z'
                      beta: false
                      read_models:
                        - id: hris_employees
                          label: Employees
                          is_available: true
                          coverage_status: SUPPORTED
                          scope_config_setting: ENABLED
                          opted_out_by_customer: false
                          fields:
                            - id: date_of_birth
                              is_available: false
                              coverage_status: SUPPORTED
                              scope_config_setting: OPTIONAL
                              opted_out_by_customer: true
                      write_actions:
                        - id: hris_create_employee
                          label: Create employee
                          is_available: true
                          coverage_status: SUPPORTED
                          scope_config_setting: ENABLED
                          opted_out_by_customer: false
                          fields:
                            - id: first_name
                              is_available: true
                              coverage_status: SUPPORTED
        default:
          $ref: '#/components/responses/ErrorResponseGeneral'
```

--------------------------------

### Install Kombo Connect Library

Source: https://docs.kombo.dev/ats/guides/connect/embedded-flow

Install the required JavaScript library via your preferred package manager.

```npm
npm install @kombo-api/connect
```

```yarn
yarn add @kombo-api/connect
```

```pnpm
pnpm add @kombo-api/connect
```

--------------------------------

### Ruby SDK Initialization

Source: https://docs.kombo.dev/assessment/v1/put-packages

Initial setup for the Kombo Ruby SDK.

```ruby
require 'kombo'


Models = ::Kombo::Models

s = ::Kombo::Kombo.new(
```

--------------------------------

### GET /hris/timesheets

Source: https://docs.kombo.dev/hris/v1/get-timesheets

Retrieves a list of timesheets from the HRIS system, with optional filtering by start and end timestamps.

```APIDOC
## GET /hris/timesheets

### Description
Retrieves a list of timesheets. Supports filtering by start and end times.

### Method
GET

### Endpoint
/hris/timesheets

### Parameters
#### Query Parameters
- **started_before** (string, date-time) - Optional - Return timesheets whose start time is before the given timestamp.
- **started_after** (string, date-time) - Optional - Return timesheets whose start time is on or after the given timestamp.
- **ended_before** (string, date-time) - Optional - Return timesheets whose end time is on or before the given timestamp.
- **ended_after** (string, date-time) - Optional - Return timesheets whose end time is on or after the given timestamp.

### Response
#### Success Response (200)
- **status** (string) - Constant 'success'.
- **data** (object) - Contains pagination and results.
  - **next** (string|null) - Cursor string for the next page.
  - **results** (array) - List of timesheet objects.
    - **id** (string) - Globally unique ID generated by Kombo.
    - **remote_id** (string|null) - Raw ID from the remote system.
    - **employee_id** (string) - Kombo ID of the employee.
    - **started_at** (string|null) - Start time in UTC.
    - **ended_at** (string|null) - End time in UTC.
    - **timezone** (string|null) - ISO 8601 numeric UTC offset.
    - **payable_hours** (number|null) - Payable hours if available.
```

--------------------------------

### Get HRIS Time Off Balances

Source: https://docs.kombo.dev/hris/v1/get-time-off-balances

Examples for retrieving time off balances across different programming languages.

```typescript
import { Kombo } from "@kombo-api/sdk";

const kombo = new Kombo({
  integration_id: "workday:HWUTwvyx2wLoSUHphiWVrp28",
  api_key: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await kombo.hris.getTimeOffBalances({});

  for await (const page of result) {
    console.log(page);
  }
}

run();
```

```ruby
require 'kombo'


Models = ::Kombo::Models

s = ::Kombo::Kombo.new(
      integration_id: 'workday:HWUTwvyx2wLoSUHphiWVrp28',
      security: Models::Shared::Security.new(
        api_key: '<YOUR_BEARER_TOKEN_HERE>',
      ),
    )

res = s.hris.get_time_off_balances(page_size: 100, include_deleted:
false, ignore_unsupported_filters: false)


unless res.get_hris_time_off_balances_positive_response.nil?
  # handle response
end
```

```python
from kombo import Kombo


with Kombo(
    integration_id="workday:HWUTwvyx2wLoSUHphiWVrp28",
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:

    res = k_client.hris.get_time_off_balances(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()
```

--------------------------------

### Install @kombo-api/connect (npm)

Source: https://docs.kombo.dev/assessment/guides/connect/embedded-flow

Install the Kombo Connect JavaScript library using npm.

```bash
npm install @kombo-api/connect
```

--------------------------------

### Create Employee using Kombo Client (Python)

Source: https://docs.kombo.dev/hris/v1/post-employees-form

This is a partial example showing the initialization of the Kombo client in Python. It requires the integration ID and API key.

```python
from kombo import Kombo


with Kombo(
    integration_id="workday:HWUTwvyx2wLoSUHphiWVrp28",
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:

```

--------------------------------

### Retrieve Job Stages

Source: https://docs.kombo.dev/ats/implementation-guide/reading-applicants

Example response from the GET Jobs endpoint showing the stages object for a job.

```json
{
  "status": "success",
  "data": {
    "next": "eyJwYWdlIjoxMiwibm90ZSI6InRoaXMgaXMganVzdCBhbiBleGFtcGxlIGFuZCBub3QgcmVwcmVzZW50YXRpdmUgZm9yIGEgcmVhbCBjdXJzb3IhIn0=",
    "results": [
      {
        "id": "26vafvWSRmbhNcxJYqjCzuJg",
        "remote_id": "32",
        "name": "Backend Engineer",
        ...,
        "stages": [
          {
            "id": "3PJ8PZhZZa1eEdd2DtPNtVup",
            "remote_id": "32",
            "name": "Initial Screening",
            "index": 0
          },
          {
            "id": "HWUTwvyx2wLoSUHphiWVrp28",
            "remote_id": "38",
            "name": "Interview",
            "index": 1
          },
        ],
      }
    ]
  }
}
```

--------------------------------

### Install @kombo-api/connect (yarn)

Source: https://docs.kombo.dev/assessment/guides/connect/embedded-flow

Install the Kombo Connect JavaScript library using yarn.

```bash
yarn add @kombo-api/connect
```

--------------------------------

### GET /v1/hris/employees

Source: https://docs.kombo.dev/assessment/getting-started/querying-api

Example of fetching a paginated list of employees using cursor-based pagination and page size control.

```APIDOC
## GET /v1/hris/employees

### Description
Fetches a list of employees from the HRIS system. Supports pagination via cursors and filtering.

### Method
GET

### Endpoint
/v1/hris/employees

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - The cursor value to retrieve the next page of results.
- **page_size** (integer) - Optional - The number of results to return per page.
- **updated_after** (timestamp) - Optional - Only return objects changed after this timestamp.
- **include_deleted** (boolean) - Optional - Include objects where remote_deleted_at is set.
- **ids** (string) - Optional - Comma-separated list of Kombo IDs.
- **remote_ids** (string) - Optional - Comma-separated list of remote system IDs.

### Response
#### Success Response (200)
- **id** (string) - The Kombo ID.
- **remote_id** (string) - The ID of the object in the remote system.
- **changed_at** (timestamp) - Timestamp of the last change detected by Kombo.
- **remote_deleted_at** (timestamp) - Timestamp when the object was removed from the remote system.
- **next** (string) - Cursor for the next page of results.
```

--------------------------------

### Install @kombo-api/connect (pnpm)

Source: https://docs.kombo.dev/assessment/guides/connect/embedded-flow

Install the Kombo Connect JavaScript library using pnpm.

```bash
pnpm add @kombo-api/connect
```

--------------------------------

### Example Positive Response for Setting Application Stage

Source: https://docs.kombo.dev/ats/v1/put-applications-application-id-stage

This is an example of a successful response when updating an application's stage. It confirms the status and includes any warnings generated during the operation.

```json
{
  "status": "success",
  "data": {},
  "warnings": [
    {
      "message": "This is an example warning!"
    }
  ]
}
```

--------------------------------

### Fetch ATS Offers with Kombo SDK

Source: https://docs.kombo.dev/ats/v1/get-offers

Examples for retrieving ATS offers using the Kombo client. The Python example demonstrates handling pagination using the next cursor.

```ruby
integration_id: 'workday:HWUTwvyx2wLoSUHphiWVrp28',
                  security: Models::Shared::Security.new(
                    api_key: '<YOUR_BEARER_TOKEN_HERE>',
                  ),
                )

            res = s.ats.get_offers(page_size: 100, include_deleted: false,
            ignore_unsupported_filters: false)


            unless res.get_ats_offers_positive_response.nil?
              # handle response
            end
```

```python
from kombo import Kombo


with Kombo(
    integration_id="workday:HWUTwvyx2wLoSUHphiWVrp28",
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:

    res = k_client.ats.get_offers(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()
```

--------------------------------

### Define Performance Review Cycles

Source: https://docs.kombo.dev/hris/features/performance-data

Examples of performance review cycle objects, including cases where the start date is supported or unsupported.

```json
{
  "name": "2025 Annual Performance Review Cycle",
  "review_period_start_date": "2025-01-01T00:00:00.000Z"
}
```

```json
{
  "name": "2025 Annual Performance Review Cycle",
  "review_period_start_date": null,
}
```

--------------------------------

### Get ATS Candidates in Ruby

Source: https://docs.kombo.dev/ats/v1/get-candidates

This Ruby code demonstrates how to retrieve ATS candidates. It requires the 'kombo' gem and proper authentication setup.

```ruby
require 'kombo'


Models = ::Kombo::Models

s = ::Kombo::Kombo.new(
      integration_id: 'workday:HWUTwvyx2wLoSUHphiWVrp28',
      security: Models::Shared::Security.new(
        api_key: '<YOUR_BEARER_TOKEN_HERE>',
      ),
    )

res = s.ats.get_candidates(page_size: 100, include_deleted: false,
ignore_unsupported_filters: false)


unless res.get_ats_candidates_positive_response.nil?
  # handle response
end
```

--------------------------------

### Initial JSON Response Example

Source: https://docs.kombo.dev/hris/getting-started/fetching-data

This JSON example shows an employee record with its associated employment data, both having an initial `changed_at` timestamp. This serves as a baseline before any updates occur.

```json
{
  "id": "emp123",
  "first_name": "Sarah",
  "changed_at": "2023-10-01T08:00:00Z",
  "employments": [
    {
      "id": "employment456",
      "job_title": "Software Engineer",
      "changed_at": "2023-10-01T08:00:00Z"
    }
  ]
}
```

--------------------------------

### Get ATS Candidates in TypeScript

Source: https://docs.kombo.dev/ats/v1/get-candidates

Use this snippet to fetch candidates from an ATS. Ensure you have the Kombo SDK installed and your API key is correctly configured.

```typescript
import { Kombo } from "@kombo-api/sdk";

const kombo = new Kombo({
  integration_id: "workday:HWUTwvyx2wLoSUHphiWVrp28",
  api_key: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await kombo.ats.getCandidates({});

  for await (const page of result) {
    console.log(page);
  }
}

run();
```

--------------------------------

### Get Candidate Attachments in Python

Source: https://docs.kombo.dev/ats/v1/get-candidates-candidate-id-attachments

Retrieve candidate attachments using the Kombo Python client. This example shows basic usage and response handling.

```python
from kombo import Kombo


with Kombo(
    integration_id="workday:HWUTwvyx2wLoSUHphiWVrp28",
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:

    res = k_client.ats.get_candidate_attachments(candidate_id="8Xi6iZrwusZqJmDGXs49GBmJ")

    # Handle response
    print(res)
```

--------------------------------

### Fetch Application Stages (Ruby)

Source: https://docs.kombo.dev/ats/v1/get-application-stages

This Ruby code demonstrates fetching application stages. Ensure you have the Kombo gem installed and initialize the client with your integration ID and API key. The `get_application_stages` method allows specifying page size and filter options.

```ruby
require 'kombo'


Models = ::Kombo::Models

s = ::Kombo::Kombo.new(
      integration_id: 'workday:HWUTwvyx2wLoSUHphiWVrp28',
      security: Models::Shared::Security.new(
        api_key: '<YOUR_BEARER_TOKEN_HERE>',
      ),
    )

res = s.ats.get_application_stages(page_size: 100, include_deleted:
false, ignore_unsupported_filters: false)


unless res.get_ats_application_stages_positive_response.nil?
  # handle response
end
```

--------------------------------

### OpenAPI Specification for Provisioning Setup Links

Source: https://docs.kombo.dev/assessment/v1/post-hris-provisioning-groups-group-id-setup-links

Defines the endpoint for creating a provisioning setup link for the Kombo Connect SDK.

```yaml
openapi: 3.1.0
info:
  title: Kombo API
  version: 1.0.0
servers:
  - url: https://api.kombo.dev/v1
    description: Kombo EU API
  - url: https://api.us.kombo.dev/v1
    description: Kombo US API
security:
  - ApiKey: []
tags:
  - name: General
  - name: Kombo Connect
    description: >-
      Endpoints for Kombo Connect, our end-user-facing flow for setting up new
      integrations.
  - name: Unified HRIS API
    description: Unified endpoints to access all the HR concepts you might need.
  - name: Unified ATS API
    description: Unified endpoints to access all the ATS concepts you might need.
  - name: Unified ATS (Assessment & Background Check) API
    description: >-
      Unified endpoints to operate Assessments and Background Checks for many
      applicant tracking systems.
  - name: Unified LMS API
    description: Unified endpoints to access all the LMS concepts you might need.
  - name: AI Apply
    description: Endpoints for AI-powered job application features.
  - name: Custom Endpoints
    description: Custom integration-specific endpoints.
paths:
  /hris/provisioning-groups/{group_id}/setup-links:
    post:
      tags:
        - Unified HRIS API
      summary: Create provisioning setup link
      description: >-
        Create a new link that can be passed to the Kombo Connect SDK to open
        the provisioning setup UI.
      operationId: PostHrisProvisioningGroupsGroupIdSetupLinks
      parameters:
        - in: header
          name: X-Integration-Id
          schema:
            type: string
          description: ID of the integration you want to interact with.
          example: bamboohr:HWUTwvyx2wLoSUHphiWVrp28
          required: true
        - name: group_id
          in: path
          required: true
          description: ID of the provisioning group (currently only `default` is allowed).
          schema:
            $ref: >-
              #/components/schemas/PostHrisProvisioningGroupsGroupIdSetupLinksParameterGroupId
          examples:
            example1:
              value: n39n320clr8c5amf8v83nbch
      requestBody:
        description: POST /hris/provisioning-groups/:group_id/setup-links Request body
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PostHrisProvisioningGroupsGroupIdSetupLinksRequestBody
            examples:
              example1:
                value:
                  language: en
      responses:
        '200':
          description: >-
            POST /hris/provisioning-groups/:group_id/setup-links Positive
            response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/PostHrisProvisioningGroupsGroupIdSetupLinksPositiveResponse
              examples:
                example1:
                  value:
                    status: success
                    data:
                      url: >-
                        https://connect.kombo.dev/v1/setup?token=GinuMJCpUQ9xdpLmD2ocw8qdiK3qiPCizDCv754EXri2vAX4
                      expires_at: '2023-10-11T12:00:00.000Z'
        default:
          $ref: '#/components/responses/ErrorResponseHRIS'
components:
  schemas:
    PostHrisProvisioningGroupsGroupIdSetupLinksParameterGroupId:
      type: string
      description: ID of the provisioning group (currently only `default` is allowed).
    PostHrisProvisioningGroupsGroupIdSetupLinksRequestBody:
      type: object
      properties:
        language:
          type:
            - string
            - 'null'
          enum:
            - en
            - de
            - fr
            - it
            - es
          default: en
          description: >-
            Language of the UI. Please note that the provisioning setup UI is
            _not_ translated yet but we're working on it and setting this
            already will make sure the translations appear once released.
    PostHrisProvisioningGroupsGroupIdSetupLinksPositiveResponse:
      type: object
      properties:
        status:
          type: string
          const: success
        data:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: The setup link URL to pass to the Kombo Connect SDK.
            expires_at:
              description: When this link expires.
              type: string
              format: date-time
              externalDocs:
                url: >-
                  https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString
          required:
            - url
            - expires_at
          examples:
            - url: >-
                https://connect.kombo.dev/v1/setup?token=GinuMJCpUQ9xdpLmD2ocw8qdiK3qiPCizDCv754EXri2vAX4
              expires_at: '2023-10-11T12:00:00.000Z'
      required:
        - url
        - expires_at
```

--------------------------------

### Example API Response for Integration

Source: https://docs.kombo.dev/v1/get-integration-by-token-token

This JSON structure represents a successful response when retrieving integration details. It includes information about the connected tool, user, and setup status.

```json
{
  "status": "success",
  "data": {
    "tool": "personio",
    "id": "personio:CBNMt7dSNCzBdnRTx87dev4E",
    "end_user_origin_id": "36123",
    "end_user_organization_name": "Acme, Inc.",
    "end_user_email": "user@example.com",
    "setup_status": "COMPLETED"
  }
}
```

--------------------------------

### Get ATS Candidates in Python

Source: https://docs.kombo.dev/ats/v1/get-candidates

This Python snippet shows how to fetch ATS candidates using the Kombo client. Ensure the 'kombo' library is installed and your credentials are set.

```python
from kombo import Kombo


with Kombo(
    integration_id="workday:HWUTwvyx2wLoSUHphiWVrp28",
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:

    res = k_client.ats.get_candidates(page_size=100, include_deleted=False, ignore_unsupported_filters=False)
```

--------------------------------

### Course Enrollment Data Example

Source: https://docs.kombo.dev/lms/v1/post-course-progressions

Example of a course enrollment object including nested user and course revision details.

```yaml
id: 26vafvWSRmbhNcxJYqjCzuJg
remote_id: progress-12345
user_id: 7xPdr68N8kG9EzLwjsN9xyz
course_revision_id: 3KMdr68N8kG9EzLwjsN9aoz
status: COMPLETED
enrolled_at: '2022-08-07T14:01:29.196Z'
completed_at: '2022-08-07T14:01:29.196Z'
changed_at: '2022-08-07T14:01:29.196Z'
remote_deleted_at: null
remote_data: null
user:
  id: 26vafvWSRmbhNcxJYqjCzuJg
  remote_id: '32'
  first_name: Sarah
  last_name: Johnson
  work_email: sarah.johnson@example.com
course_revision:
  id: 3KMdr68N8kG9EzLwjsN9aoz
  remote_id: revision-12345
  title: Building LMS integrations with Kombo
  course:
    id: 26vafvWSRmbhNcxJYqjCzuJg
    remote_id: '32'
```

--------------------------------

### Retrieve Conditional Screening Questions JSON

Source: https://docs.kombo.dev/ats/features/candidate-screening-questions

Example of the screening_questions array structure returned by the Get Jobs endpoint, showing how precondition_question_id and precondition_options define conditional logic.

```json
"screening_questions": [
  {
    "id": "26vafvWSRmbhNcxJYqjCzuJg",
    "remote_id": "48b4d36a-1d4b-4c50-ada7-9519078e65b4",
    "title": "Do you have a valid driver's license?",
    "description": "Please state if you have a valid driver's license.",
    "format": {
      "display_type": "DROPDOWN",
      "type": "SINGLE_SELECT",
      "options": [
        {
          "id": "5KMj443ZBfzBkqFhDuvdoZJP",
          "remote_id": "59c5d36a-1d4b-4c50-ada7-9519078e65b4",
          "name": "Yes"
        },
        {
          "id": "H5benHrFr66wh9wU3RQegRRN",
          "remote_id": "61d6d36a-1d4b-4c50-ada7-9519078e65b4",
          "name": "No"
        }
      ]
    },
    "index": 0,
    "required": true,
    "precondition_question_id": null,
    "precondition_options": null
  },
  {
    "id": "9SmkUABUZnQdoPGeK83CdGnH",
    "remote_id": "21b4d36a-1d4b-4c50-ada7-9519078e65b4",
    "title": "How many years of driving experience do you have?",
    "description": "Please state how many years of driving experience you have.",
    "format": {
      "display_type": "DROPDOWN",
      "type": "SINGLE_SELECT",
      "options": [
        {
          "id": "AFN58qWqutLt4ZMZgykD483W",
          "remote_id": "11c5d36a-1d4b-4c50-ada7-9519078e65b4",
          "name": "Less than 1 year"
        },
        {
          "id": "6MHzLUCEaNmccbf6bP18466J",
          "remote_id": "66d6d36a-1d4b-4c50-ada7-9519078e65b4",
          "name": "1-2 years"
        }
      ]
    },
    "index": 1,
    "required": true,
    "precondition_question_id": "26vafvWSRmbhNcxJYqjCzuJg",
    "precondition_options": ["5KMj443ZBfzBkqFhDuvdoZJP"]
  }
],
```

--------------------------------

### Create Job Application (Python)

Source: https://docs.kombo.dev/ats/v1/post-jobs-job-id-applications

This Python snippet demonstrates how to create a job application using the Kombo client. It requires the kombo library and uses a context manager for client initialization. Replace placeholders with your integration ID and API key.

```python
from kombo import Kombo
from kombo.utils import parse_datetime


with Kombo(
    integration_id="workday:HWUTwvyx2wLoSUHphiWVrp28",
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:

    res = k_client.ats.create_application(job_id="BDpgnpZ148nrGh4mYHNxJBgx", candidate={
        "first_name": "Frank",
        "last_name": "Doe",
        "email_address": "frank.doe@example.com",
        "company": "Acme Inc.",
        "title": "Head of Integrations",
        "phone_number": "+1-541-754-3010",
        "location": {
            "city": "New York",
            "country": "US",
            "state": "NY",
            "zip_code": "10016",
        },
        "gender": "MALE",
        "availability_date": parse_datetime("2021-01-01T00:00:00Z"),
        "salary_expectations": {
            "period": "YEAR",
            "amount": 100000,
        },
    }, stage_id="8x3YKRDcuRnwShdh96ShBNn1", attachments=[
        {
            "name": "Frank Doe CV.txt",
            "content_type": "text/plain",

```