> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombo.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Activate integration (optional)
> Use this endpoint with the token you get from the connection flow to retrieve information about the created integration. It works in a similar way as the OAuth2 code flow to securely retrieve information and connect the integration to your user. You do not need to call this endpoint for an integration to become active.
We are deprecating this endpoint in favour of the [get integration by code endpoint](/v1/get-integration-by-token-token). To migrate you only have to change to the new API endpoint.
### Example Request Body
```json theme={null}
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXNzYWdlIjoiVGhpcyBpcyBub3QgYW4gYWN0dWFsIHRva2VuLiJ9.JulqgOZBMKceI8vh9YLpVX51efND0ZyfUNHDXLrPz_4"
}
```
## OpenAPI
````yaml POST /connect/activate-integration
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:
/connect/activate-integration:
post:
tags:
- Kombo Connect
summary: Activate integration (optional)
description: >-
Use this endpoint with the token you get from the connection flow to
retrieve information about the created integration. It works in a
similar way as the OAuth2 code flow to securely retrieve information and
connect the integration to your user. You do not need to call this
endpoint for an integration to become active.
We are deprecating this endpoint in favour of the [get
integration by code endpoint](/v1/get-integration-by-token-token). To
migrate you only have to change to the new API endpoint.
### Example Request Body
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXNzYWdlIjoiVGhpcyBpcyBub3QgYW4gYWN0dWFsIHRva2VuLiJ9.JulqgOZBMKceI8vh9YLpVX51efND0ZyfUNHDXLrPz_4"
}
```
operationId: PostConnectActivateIntegration
requestBody:
description: POST /connect/activate-integration Request body
content:
application/json:
schema:
$ref: '#/components/schemas/PostConnectActivateIntegrationRequestBody'
responses:
'200':
description: POST /connect/activate-integration Positive response
content:
application/json:
schema:
$ref: >-
#/components/schemas/PostConnectActivateIntegrationPositiveResponse
examples:
example1:
value:
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
default:
$ref: '#/components/responses/ErrorResponseGeneral'
components:
schemas:
PostConnectActivateIntegrationRequestBody:
type: object
properties:
token:
type: string
required:
- token
PostConnectActivateIntegrationPositiveResponse:
type: object
properties:
status:
type: string
const: success
data:
type: object
properties:
tool:
type: string
id:
type: string
end_user_origin_id:
type:
- string
- 'null'
end_user_organization_name:
type: string
end_user_email:
type:
- string
- 'null'
pattern: >-
^(?!\.)(?!.*\.\.)([\w'+-.]*)[\w+-]@([\da-z][\da-z-]*\.)+[a-z]{2,}$
setup_status:
type: string
enum:
- INCOMPLETE
- FINAL_SYNC_PENDING
- COMPLETED
description: >-
The setup_status is used in conjunction with the filtering and
field mapping features. If these are enabled in the connection
flow, the integration will start in an "INCOMPLETE" state and
move to "COMPLETE" once all steps are finished.
- `INCOMPLETE`: Setup is still in progress. Some steps aren’t
finished, so no data is available yet. Syncs only run as needed
for setup.
- `FINAL_SYNC_PENDING`: Setup is complete, and the final sync is
running. Data will be available after this sync is done.
- `COMPLETED`: Setup is fully finished, and the integration is
ready to use.
required:
- tool
- id
- end_user_origin_id
- end_user_organization_name
- end_user_email
- setup_status
examples:
- 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
required:
- status
- data
responses:
ErrorResponseGeneral:
description: The standard error response with just the platform error codes.
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: object
properties:
code:
type:
- string
- 'null'
enum:
- PLATFORM.RATE_LIMIT_EXCEEDED
- PLATFORM.CONCURRENCY_LIMIT_EXCEEDED
- PLATFORM.INTEGRATION_NOT_FOUND
- PLATFORM.INPUT_INVALID
- PLATFORM.UNKNOWN_ERROR
- PLATFORM.IP_NOT_WHITELISTED
- PLATFORM.AUTHENTICATION_INVALID
- PLATFORM.TASK_TIMED_OUT
example: PLATFORM.RATE_LIMIT_EXCEEDED
description: >-
Some errors include an error code that can be used to
identify their cause. See the [Error Handling
Docs](https://docs.kombo.dev/guides/errors) for more
information. For your error handling logic please use the
error `code` instead of other properties (e.g. message,
http status code, ...).
title:
type:
- string
- 'null'
description: A static, human-readable label.
message:
type: string
description: >-
A dynamic, detailed description of what went wrong in this
specific instance.
log_url:
type:
- string
- 'null'
format: uri
description: >-
The log page in the Kombo UI lists every interaction with
full details. If you need assistance, share that link with
our support team.
required:
- code
- title
- message
- log_url
description: Error details with structured code for programmatic handling.
required:
- status
- error
examples:
Error Response:
description: >-
When building error handling logic, always use the `code` field
to identify specific error types programmatically. See the
complete list of error codes in the
[docs](https://docs.kombo.dev/guides/errors).
value:
status: error
error:
code: INTEGRATION.MODEL_NOT_AVAILABLE
title: >-
This data model isn't supported for the selected
integration.
message: >-
The "employees" model is not yet available for Greenhouse.
Please reach out to Kombo if you need this functionality.
log_url: https://app.kombo.dev/my-prod/logs?interactionId=123456
Minimal Error Response:
description: >-
The "message" is always required while other fields can also be
`null`. See the [docs](https://docs.kombo.dev/guides/errors) for
more information.
value:
status: error
error:
code: null
title: null
message: The message is always in the response.
log_url: null
securitySchemes:
ApiKey:
type: http
scheme: bearer
description: >-
Create an API key on the [Secrets](https://app.kombo.dev/secrets) page
in the Kombo dashboard.
````