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\nWe 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.\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.