Kombo Kombo Connect API
Endpoints for Kombo Connect, our end-user-facing flow for setting up new integrations.
OpenAPI Specification
openapi: 3.1.0
info:
title: Kombo AI Apply Kombo Connect API
version: 1.0.0
description: Endpoints for AI-powered job application features.
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: Kombo Connect
description: Endpoints for Kombo Connect, our end-user-facing flow for setting up new integrations.
paths:
/connect/create-link:
post:
operationId: PostConnectCreateLink
summary: Create connection link
description: "Generate a unique link that allows your user to enter the embedded Kombo Connect flow.\n\n> Check out [our full guide](/connect/embedded-flow) for more details about implementing the connection flow into your app.\n\n> Kombo will not deduplicate integrations for you that are created with this endpoint. You are responsible for keeping track of integrations in your system and prevent customers from connecting the same tool again. Use the [reconnection link](/v1/post-integrations-integration-id-relink) endpoint if you want a customer to update their credentials.\n\n### Example Request Body\n\n```json\n{\n \"end_user_email\": \"test@example.com\",\n \"end_user_organization_name\": \"Test Inc.\",\n \"integration_category\": \"HRIS\",\n \"integration_tool\": \"personio\",\n \"end_user_origin_id\": \"123\",\n \"language\": \"en\",\n \"link_type\": \"EMBEDDED\"\n}\n```"
tags:
- Kombo Connect
requestBody:
description: POST /connect/create-link Request body
content:
application/json:
schema:
$ref: '#/components/schemas/PostConnectCreateLinkRequestBody'
examples:
example1:
value:
end_user_email: test@example.com
end_user_organization_name: Test Inc.
integration_category: HRIS
integration_tool: personio
end_user_origin_id: '123'
language: en
link_type: EMBEDDED
responses:
'200':
description: POST /connect/create-link Positive response
content:
application/json:
schema:
$ref: '#/components/schemas/PostConnectCreateLinkPositiveResponse'
examples:
example1:
value:
status: success
data:
link: https://connect.kombo.dev/v1?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.SWYgeW91IGFyZSByZWFkaW5nIHRoaXMsIHdlIHdvdWxkIGxpa2UgdG8gbGV0IHlvdSBrbm93IHRoYXQgd2UgYXJlIGhpcmluZyBwZW9wbGUgbGlrZSB5b3UgOikuIFJlYWNoIG91dCB0byBhbGV4QGtvbWJvLmRldiB0byBnZXQgaW4gY29udGFjdCBhbmQgdGVsbCBoaW0geW91IGNvbWUgZnJvbSB0aGUgSldUIDsp._hhX5YTtHfLn9ZC806dZceRn2whzxHyrhft1ONzNgOE
default:
$ref: '#/components/responses/ErrorResponseGeneral'
/connect/integration-by-token/{token}:
get:
operationId: GetConnectIntegrationByTokenToken
summary: Get integration by token
description: "Use this endpoint with the token you get from the connection flow to retrieve information about the created integration.\n\n It works in a similar way as the OAuth2 code flow to securely retrieve information and connect the integration to your user.\n\n> Check out [our full guide](/connect/embedded-flow) for more details about implementing the connection flow into your app.\n\nThis endpoint is used to ensure users can't trick your system connecting their\naccount in your system to another customers integration. You don't get the integration ID\nfrom the `showKomboConnect(link)` function but only the short lived token used\nfor this endpoint so that users can't send you arbitrary data that you would put\ninto your system."
tags:
- Kombo Connect
parameters:
- name: token
in: path
required: true
description: GET /connect/integration-by-token/:token Parameter
schema:
$ref: '#/components/schemas/GetConnectIntegrationByTokenTokenParameterToken'
responses:
'200':
description: GET /connect/integration-by-token/:token Positive response
content:
application/json:
schema:
$ref: '#/components/schemas/GetConnectIntegrationByTokenTokenPositiveResponse'
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'
/connect/activate-integration:
post:
operationId: PostConnectActivateIntegration
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.\n\n<Warning>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.</Warning>\n\n### Example Request Body\n\n```json\n{\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXNzYWdlIjoiVGhpcyBpcyBub3QgYW4gYWN0dWFsIHRva2VuLiJ9.JulqgOZBMKceI8vh9YLpVX51efND0ZyfUNHDXLrPz_4\"\n}\n```"
tags:
- Kombo Connect
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:
GetConnectIntegrationByTokenTokenPositiveResponse:
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
PostConnectCreateLinkPositiveResponse:
type: object
properties:
status:
type: string
const: success
data:
type: object
properties:
link:
type: string
format: uri
required:
- link
examples:
- link: https://connect.kombo.dev/v1?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.SWYgeW91IGFyZSByZWFkaW5nIHRoaXMsIHdlIHdvdWxkIGxpa2UgdG8gbGV0IHlvdSBrbm93IHRoYXQgd2UgYXJlIGhpcmluZyBwZW9wbGUgbGlrZSB5b3UgOikuIFJlYWNoIG91dCB0byBhbGV4QGtvbWJvLmRldiB0byBnZXQgaW4gY29udGFjdCBhbmQgdGVsbCBoaW0geW91IGNvbWUgZnJvbSB0aGUgSldUIDsp._hhX5YTtHfLn9ZC806dZceRn2whzxHyrhft1ONzNgOE
required:
- status
- data
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
PostConnectCreateLinkRequestBody:
type: object
properties:
end_user_email:
type: string
description: The email of the user this link is meant for.
format: email
end_user_organization_name:
type: string
minLength: 1
description: The name of the user's organization.
end_user_origin_id:
type:
- string
- 'null'
minLength: 1
description: The id the user/organization has in your own database.
remote_environment:
type:
- string
- 'null'
description: If the tool you want to connect offers different environments, you can specify which one you want to connect to here. If you don't specify this, we'll assume you want to use the production environment. Note that this can only be used if you've also specified a tool through `integration_tool`.
integration_category:
type: string
enum:
- HRIS
- ATS
- ASSESSMENT
- LMS
default: HRIS
description: Category of the integration you want your customer to create.
integration_tool:
type:
- string
- 'null'
enum:
- workday
- successfactors
- smartrecruiters
- factorial
- oraclerecruiting
- lever
- icims
- cornerstonetalentlink
- recruitee
- recruiterflow
- greenhouse
- greenhousejobboard
- teamtailor
- teamtailorjobboards
- ashby
- talentsoft
- talentsoftcustomer
- concludis
- talention
- piloga
- onlyfy
- personio
- ukgpro
- ukgready
- adpworkforcenow
- taleo
- rexx
- afas
- bamboohr
- bullhorn
- bullhornlogin
- workable
- jobvite
- fountain
- softgarden
- softgardenpartner
- pinpoint
- welcometothejungle
- dvinci
- dvinciadmin
- join
- sagehr
- traffit
- erecruiter
- abacusumantis
- umantis
- jobylon
- taleez
- hrworks
- otys
- zohorecruit
- ceipal
- eploy
- jobdiva
- careerplug
- perview
- eightfold
- paylocity
- paycor
- avature
- apploi
- phenom
- paradox
- heyrecruit
- recruhr
- recruitcrm
- jazzhr
- bite
- brassring
- homerun
- mysolution
- carerix
- hroffice
- talentclue
- inrecruiting
- ubeeo
- connexys
- hr4you
- cornerstoneondemand
- zvooverecruit
- odoo
- comeet
- compleet
- compleetpitcher
- gem
- laura
- covetorest
- coveto
- mercury
- crelate
- manatal
- avionte
- mhmhr
- asymbl
- breezyhr
- flatchr
- dayforce
- digitalrecruiters
- applicantstack
- reachmee
- talentadore
- sandbox
- guidecom
- spott
- loxo
- kula
- workdaycustomreport
- workdaycustomreportsftp
- ukgprowfm
- payfitcustomer
- payfitpartner
- payfit
- employmenthero
- fourth
- kenjo
- heavenhr
- hibob
- cezannehr
- entraid
- azuread
- googleworkspace
- nmbrs
- deel
- remotecom
- iriscascade
- okta
- sagepeople
- humaans
- eurecia
- oraclehcm
- officient
- sesamehr
- charliehr
- abacus
- zohopeople
- gusto
- breathehr
- catalystone
- mirus
- alexishr
- simployer
- peple
- youserve
- hansalog
- lattice
- latticetalent
- hoorayhr
- trinet
- trinetpeo
- namely
- paycom
- insperity
- paychex
- rippling
- sapling
- peoplehr
- lucca
- zelt
- planday
- boondmanager
- haileyhr
- silae
- oysterhr
- kiwihr
- square
- perbilityhelix
- leapsome
- loket
- workforcecom
- peoplefirst
- sdworx
- itrent
- absenceio
- a3innuvanomina
- scim
- datevlauds
- datevhr
- datev
- datevlug
- sympa
- youforce
- nibelis
- peoplexd
- sftp
- sftpfetch
- 360learning
- talentlms
- udemy
- linkedinlearning
- moodle
description: Pre-define a tool this integration link can be used for.
language:
type:
- string
- 'null'
enum:
- en
- de
- fr
- it
- es
default: en
description: Language of the connection flow UI.
scope_config_id:
type:
- string
- 'null'
description: Specify a scope config that should be used for this integration. This is an advanced feature, only use it if you know what you're doing!
enable_filtering:
type: boolean
default: false
description: Enable the [filtering feature](https://docs.kombo.dev/other/filtering) for the integration. HRIS only.
enable_field_mapping:
type: boolean
default: false
description: Enable the [field mapping feature](https://docs.kombo.dev/hris/features/setup-flow/introduction#field-mapping) for this integration.
link_type:
type: string
enum:
- EMBEDDED
- MAGIC_LINK
default: EMBEDDED
description: 'The type of link you want to create. `EMBEDDED` is for the [embedded flow](../guides/connect/embedded-flow) using the Kombo Connect SDK (these links are valid for 1 hour) and `MAGIC_LINK` is for [magic links](../guides/connect/magic-links) which you send out manually to customers (there are valid for 1 year).
This defaults to `EMBEDDED`, which is our recommended method of implementing the connection flow for a seamless user experience.'
required:
- end_user_email
- end_user_organization_name
GetConnectIntegrationByTokenTokenParameterToken:
type: string
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.