Kombo Kombo API

openapi: 3.2.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: Kombo API
paths: {}
webhooks:
  data-changed:
    post:
      summary: Data changed
      operationId: webhookDataChangedWebhookPayload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataChangedWebhookPayload'
            example:
              id: Cbfk5sHtDxrSrJBRjsDtbaN9
              type: data-changed
              data:
                integration_id: personio:CBNMt7dSNCzBdnRTx87dev4E
                integration_tool: personio
                integration_category: HRIS
                changed_models:
                - name: hris_employees
                - name: hris_join_employees_teams
      parameters:
      - name: X-Kombo-Signature
        in: header
        required: true
        description: HMAC signature for webhook verification. See the webhook documentation for details on how to verify this signature.
        schema:
          type: string
      responses:
        '200':
          description: Webhook received successfully
      tags:
      - Kombo API
  connection-flow-failed:
    post:
      summary: Connection flow failed
      operationId: webhookConnectionFlowFailedWebhookPayload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionFlowFailedWebhookPayload'
            example:
              id: Cbfk5sHtDxrSrJBRjsDtbaN9
              type: connection-flow-failed
              data:
                integration_tool: personio
                integration_category: HRIS
                end_user:
                  origin_id: '36123'
                  creator_email: user@example.com
                  organization_name: Acme, Inc.
                log_url: https://app.kombo.dev/env/production/logs?flowId=C3xUo6XAsB2sbKC7M1gyXaRX
      parameters:
      - name: X-Kombo-Signature
        in: header
        required: true
        description: HMAC signature for webhook verification. See the webhook documentation for details on how to verify this signature.
        schema:
          type: string
      responses:
        '200':
          description: Webhook received successfully
      tags:
      - Kombo API
  integration-created:
    post:
      summary: Integration created
      operationId: webhookIntegrationCreatedWebhookPayload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationCreatedWebhookPayload'
            example:
              id: Cbfk5sHtDxrSrJBRjsDtbaN9
              type: integration-created
              data:
                id: personio:CBNMt7dSNCzBdnRTx87dev4E
                tool: personio
                category: HRIS
                end_user:
                  origin_id: '36123'
                  creator_email: user@example.com
                  organization_name: Acme, Inc.
      parameters:
      - name: X-Kombo-Signature
        in: header
        required: true
        description: HMAC signature for webhook verification. See the webhook documentation for details on how to verify this signature.
        schema:
          type: string
      responses:
        '200':
          description: Webhook received successfully
      tags:
      - Kombo API
  integration-deleted:
    post:
      summary: Integration deleted
      operationId: webhookIntegrationDeletedWebhookPayload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationDeletedWebhookPayload'
            example:
              id: Cbfk5sHtDxrSrJBRjsDtbaN9
              type: integration-deleted
              data:
                id: personio:CBNMt7dSNCzBdnRTx87dev4E
                tool: personio
                category: HRIS
                end_user:
                  origin_id: '36123'
                  creator_email: user@example.com
                  organization_name: Acme, Inc.
                deleted_at: '2021-09-01T12:00:00.000Z'
      parameters:
      - name: X-Kombo-Signature
        in: header
        required: true
        description: HMAC signature for webhook verification. See the webhook documentation for details on how to verify this signature.
        schema:
          type: string
      responses:
        '200':
          description: Webhook received successfully
      tags:
      - Kombo API
  assessment:order-received:
    post:
      summary: 'Assessment: Order received'
      description: This event is triggered when a new assessment or background check order is created for a candidate within your customer's ATS.
      operationId: webhookAssessmentOrderReceivedWebhookPayload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssessmentOrderReceivedWebhookPayload'
            example:
              id: Cbfk5sHtDxrSrJBRjsDtbaN9
              type: assessment:order-received
              data:
                id: B5KQKhAgTv6ZwzrfAbqbhipd
                integration_id: workday:CBNMt7dSNCzBdnRTx87dev4E
                package_id: typescript_test
                status: OPEN
                candidate:
                  remote_id: '12345'
                  email: john.doe@gmail.com
                  first_name: John
                  last_name: Doe
                  phone: +1 123 456 7890
                application:
                  remote_id: '54321'
                job:
                  remote_id: '67890'
                  name: Bottle Opener
                  job_code: BO-2024-01
                  description: <p>We are looking for a skilled and energetic individual to join our team as the chief bottle open officer. This unique role requires precision, attention to detail, and the ability to handle a high volume of beverage bottles in a fast-paced environment. The ideal candidate will ensure bottles are opened swiftly and safely while maintaining hygiene standards.</p>
                  location:
                    street_1: Lohmühlenstraße 65
                    city: Berlin
                    state: Berlin
                    zip_code: '12435'
                    country: DE
                    raw: Berlin, Germany
                  hiring_team:
                  - first_name: Jane
                    last_name: Doe
                    remote_id: '78901'
                    email: jane.doe@gmail.com
                    hiring_team_roles:
                    - RECRUITER
      parameters:
      - name: X-Kombo-Signature
        in: header
        required: true
        description: HMAC signature for webhook verification. See the webhook documentation for details on how to verify this signature.
        schema:
          type: string
      responses:
        '200':
          description: Webhook received successfully
      tags:
      - Kombo API
  inline-assessment:order-received:
    post:
      summary: 'Inline assessment: Order received'
      description: This event is triggered when a candidate reaches the inline assessment step of their application process.
      operationId: webhookInlineAssessmentOrderReceivedWebhookPayload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InlineAssessmentOrderReceivedWebhookPayload'
            example:
              id: Cbfk5sHtDxrSrJBRjsDtbaN9
              type: inline-assessment:order-received
              data:
                id: B5KQKhAgTv6ZwzrfAbqbhipd
                integration_id: workday:CBNMt7dSNCzBdnRTx87dev4E
                package_id: typescript_test
                status: OPEN
                candidate:
                  remote_id: '12345'
                  email: john.doe@gmail.com
                  first_name: John
                  last_name: Doe
                  phone: +1 123 456 7890
                application:
                  remote_id: '54321'
                job:
                  remote_id: '67890'
                  name: Bottle Opener
                  job_code: BO-2024-01
                  description: <p>We are looking for a skilled and energetic individual to join our team as the chief bottle open officer. This unique role requires precision, attention to detail, and the ability to handle a high volume of beverage bottles in a fast-paced environment. The ideal candidate will ensure bottles are opened swiftly and safely while maintaining hygiene standards.</p>
                  location:
                    street_1: Lohmühlenstraße 65
                    city: Berlin
                    state: Berlin
                    zip_code: '12435'
                    country: DE
                    raw: Berlin, Germany
                  hiring_team:
                  - first_name: Jane
                    last_name: Doe
                    remote_id: '78901'
                    email: jane.doe@gmail.com
                    hiring_team_roles:
                    - RECRUITER
      parameters:
      - name: X-Kombo-Signature
        in: header
        required: true
        description: HMAC signature for webhook verification. See the webhook documentation for details on how to verify this signature.
        schema:
          type: string
      responses:
        '200':
          description: Webhook received successfully
      tags:
      - Kombo API
  integration-state-changed:
    post:
      summary: Integration state changed
      operationId: webhookIntegrationStateChangedWebhookPayload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationStateChangedWebhookPayload'
            example:
              id: Cbfk5sHtDxrSrJBRjsDtbaN9
              type: integration-state-changed
              data:
                integration_tool: personio
                integration_category: HRIS
                integration_id: personio:CBNMt7dSNCzBdnRTx87dev4E
                end_user:
                  origin_id: '36123'
                  creator_email: user@example.com
                  organization_name: Acme, Inc.
                qa_status: PASSED
                setup_status: COMPLETED
                state: ACTIVE
                updated_at: '2021-09-01T12:00:00.000Z'
      parameters:
      - name: X-Kombo-Signature
        in: header
        required: true
        description: HMAC signature for webhook verification. See the webhook documentation for details on how to verify this signature.
        schema:
          type: string
      responses:
        '200':
          description: Webhook received successfully
      tags:
      - Kombo API
  ai-apply-application-status-updated:
    post:
      summary: 'AI Apply: Application status updated'
      operationId: webhookAiApplyApplicationStatusUpdatedWebhookPayload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiApplyApplicationStatusUpdatedWebhookPayload'
            example:
              id: Cbfk5sHtDxrSrJBRjsDtbaN9
              type: ai-apply-application-status-updated
              data:
                id: ADbmw5XSkeCSE1fAucoxEGnwZ
                job_posting_id: JDn252PEYa4rMhKbJBjtn3ng
                status: PENDING
                created_at: '2025-01-01T00:00:00.000Z'
                updated_at: '2025-03-02T23:12:32.000Z'
      parameters:
      - name: X-Kombo-Signature
        in: header
        required: true
        description: HMAC signature for webhook verification. See the webhook documentation for details on how to verify this signature.
        schema:
          type: string
      responses:
        '200':
          description: Webhook received successfully
      tags:
      - Kombo API
  ai-apply-job-posting-status-updated:
    post:
      summary: 'AI Apply: Job posting status updated'
      operationId: webhookAiApplyJobPostingStatusUpdatedWebhookPayload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiApplyJobPostingStatusUpdatedWebhookPayload'
            example:
              id: Cbfk5sHtDxrSrJBRjsDtbaN9
              type: ai-apply-job-posting-status-updated
              data:
                id: 9QGNv3B98kL3hyELE1qsZ86s
                career_site:
                  id: Chc4dua5asAQ48KUERDVF1bs
                  label: Acme
                url: https://careers.acme.com/jobs/fullstack-engineer-ai-infra-14102
                job_code: ACME_13
                archived_at: null
                archived_reason: null
                created_at: '2025-01-01T00:00:00.000Z'
                updated_at: '2025-03-02T23:12:32.000Z'
                availability: PENDING
      parameters:
      - name: X-Kombo-Signature
        in: header
        required: true
        description: HMAC signature for webhook verification. See the webhook documentation for details on how to verify this signature.
        schema:
          type: string
      responses:
        '200':
          description: Webhook received successfully
      tags:
      - Kombo API
  sync-finished:
    post:
      summary: Sync finished
      operationId: webhookSyncFinishedWebhookPayload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncFinishedWebhookPayload'
            example:
              id: Cbfk5sHtDxrSrJBRjsDtbaN9
              type: sync-finished
              data:
                sync_id: B89SCXXho7Yw8PGo8AKJxLn4
                sync_state: SUCCEEDED
                sync_started_at: '2021-09-01T12:00:00.000Z'
                sync_ended_at: '2021-09-01T12:30:00.000Z'
                sync_duration_seconds: 1800
                integration_id: personio:CBNMt7dSNCzBdnRTx87dev4E
                integration_tool: personio
                integration_category: HRIS
                end_user:
                  origin_id: '36123'
                  creator_email: user@example.com
                  organization_name: Acme, Inc.
                log_url: https://app.kombo.dev/my-prod/logs?interactionId=123456
      parameters:
      - name: X-Kombo-Signature
        in: header
        required: true
        description: HMAC signature for webhook verification. See the webhook documentation for details on how to verify this signature.
        schema:
          type: string
      responses:
        '200':
          description: Webhook received successfully
      deprecated: true
      tags:
      - Kombo API
components:
  schemas:
    AssessmentOrderReceivedWebhookPayload:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this webhook event
        type:
          type: string
          enum:
          - assessment:order-received
          description: Type of the webhook event
        data:
          type: object
          properties:
            id:
              type: string
              description: The unique identifier of the assessment order.
            package_id:
              type: string
              description: The identifier of the assessment package.
            status:
              type: string
              enum:
              - OPEN
              - COMPLETED
              - CANCELLED
              - REJECTED
              description: The current status of the assessment order.
            integration_id:
              type: string
              description: The unique identifier of the integration.
            candidate:
              type: object
              properties:
                remote_id:
                  type: string
                  nullable: true
                  description: The candidate's identifier in the integrated system.
                email:
                  type: string
                  description: The candidate's email address.
                  format: email
                first_name:
                  type: string
                  nullable: true
                  description: The candidate's first name.
                last_name:
                  type: string
                  nullable: true
                  description: The candidate's last name.
                phone:
                  type: string
                  nullable: true
                  description: The candidate's phone number.
              required:
              - remote_id
              - email
              - first_name
              - last_name
              - phone
              additionalProperties: false
              description: Information about the candidate taking the assessment.
            application:
              type: object
              properties:
                remote_id:
                  type: string
                  nullable: true
                  description: The application's identifier in the integrated system.
              required:
              - remote_id
              additionalProperties: false
              description: Information about the job application.
            job:
              type: object
              properties:
                remote_id:
                  type: string
                  nullable: true
                  description: The job's identifier in the integrated system.
                name:
                  type: string
                  nullable: true
                  description: The job title.
                job_code:
                  type: string
                  nullable: true
                  description: The human readable job code. Some systems expose this as the Requisition Code/ID.
                description:
                  type: string
                  nullable: true
                  description: Description of the job. This field is usually returned as HTML.
                location:
                  type: object
                  properties:
                    street_1:
                      type: string
                      nullable: true
                      description: If we can parse the address data, this field contains the first part of the street information.
                    street_2:
                      type: string
                      nullable: true
                    city:
                      type: string
                      nullable: true
                    state:
                      type: string
                      nullable: true
                    zip_code:
                      type: string
                      nullable: true
                    country:
                      type: string
                      nullable: true
                      description: Contains the ISO2 country code if possible. If not, it contains the original value.
                    raw:
                      type: string
                      nullable: true
                      description: If we have address data, this is filled with the raw address string.
                  additionalProperties: false
                  nullable: true
                  description: The job location information.
                hiring_team:
                  type: array
                  items:
                    type: object
                    properties:
                      remote_id:
                        type: string
                        nullable: true
                        description: The team member's identifier in the integrated system.
                      email:
                        type: string
                        nullable: true
                        description: The team member's email address.
                      first_name:
                        type: string
                        nullable: true
                        description: The team member's first name.
                      last_name:
                        type: string
                        nullable: true
                        description: The team member's last name.
                      hiring_team_roles:
                        type: array
                        items:
                          type: string
                          enum:
                          - RECRUITER
                          - HIRING_MANAGER
                        description: Array of the roles of the user for this specific job.
                    required:
                    - remote_id
                    - email
                    - first_name
                    - last_name
                    - hiring_team_roles
                    additionalProperties: false
                    description: A member of the hiring team.
                  description: The hiring team allows you to provision users into your system who can access the job and its applications.
              required:
              - remote_id
              - name
              - job_code
              - description
              - location
              - hiring_team
              additionalProperties: false
              description: Information about the job posting.
          required:
          - id
          - package_id
          - status
          - integration_id
          - candidate
          - application
          - job
          additionalProperties: false
      required:
      - id
      - type
      - data
      additionalProperties: false
    IntegrationCreatedWebhookPayload:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this webhook event
        type:
          type: string
          enum:
          - integration-created
          description: Type of the webhook event
        data:
          type: object
          properties:
            id:
              type: string
              description: The unique identifier of the newly created integration.
            tool:
              type: string
              description: The name of the integrated tool.
            category:
              type: string
              enum:
              - HRIS
              - ATS
              - ASSESSMENT
              - LMS
              description: The category of the integration.
            end_user:
              type: object
              properties:
                organization_name:
                  type: string
                  description: The name of the organization that owns the integration.
                creator_email:
                  type: string
                  nullable: true
                  description: The email address of the user who created the integration.
                  format: email
                origin_id:
                  type: string
                  nullable: true
                  description: The unique identifier of the organization in the integrated system.
              required:
              - organization_name
              - creator_email
              - origin_id
              additionalProperties: false
              description: Information about the end user who created the integration.
          required:
          - id
          - tool
          - category
          - end_user
          additionalProperties: false
      required:
      - id
      - type
      - data
      additionalProperties: false
    ConnectionFlowFailedWebhookPayload:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this webhook event
        type:
          type: string
          enum:
          - connection-flow-failed
          description: Type of the webhook event
        data:
          type: object
          properties:
            integration_tool:
              type: string
              description: The name of the integrated tool (e.g., "personio", "greenhouse").
            integration_category:
              type: string
              enum:
              - HRIS
              - ATS
              - ASSESSMENT
              - LMS
              description: The category of the integration (HRIS, ATS, ASSESSMENT, or LMS).
            end_user:
              type: object
              properties:
                organization_name:
                  type: string
                  description: The name of the organization that owns the integration.
                creator_email:
                  type: string
                  nullable: true
                  description: The email address of the user who created the integration.
                  format: email
                origin_id:
                  type: string
                  nullable: true
                  description: The unique identifier of the organization in the integrated system.
              required:
              - organization_name
              - creator_email
              - origin_id
              additionalProperties: false
              description: Information about the end user who created the integration.
            log_url:
              type: string
              format: uri
              description: URL to view detailed logs for the operation.
          required:
          - integration_tool
          - integration_category
          - end_user
          - log_url
          additionalProperties: false
      required:
      - id
      - type
      - data
      additionalProperties: false
    IntegrationDeletedWebhookPayload:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this webhook event
        type:
          type: string
          enum:
          - integration-deleted
          description: Type of the webhook event
        data:
          type: object
          properties:
            id:
              type: string
              description: The unique identifier of the deleted integration.
            tool:
              type: string
              description: The name of the integrated tool.
            category:
              type: string
              enum:
              - HRIS
              - ATS
              - ASSESSMENT
              - LMS
              description: The category of the integration.
            end_user:
              type: object
              properties:
                organization_name:
                  type: string
                  description: The name of the organization that owns the integration.
                creator_email:
                  type: string
                  nullable: true
                  description: The email address of the user who created the integration.
                  format: email
                origin_id:
                  type: string
                  nullable: true
                  description: The unique identifier of the organization in the integrated system.
              required:
              - organization_name
              - creator_email
              - origin_id
              additionalProperties: false
              description: Information about the end user who created the integration.
            deleted_at:
              type: string
              format: date-time
              description: ISO 8601 timestamp when the integration was deleted.
          required:
          - id
          - tool
          - category
          - end_user
          - deleted_at
          additionalProperties: false
      required:
      - id
      - type
      - data
      additionalProperties: false
    DataChangedWebhookPayload:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this webhook event
        type:
          type: string
          enum:
          - data-changed
          description: Type of the webhook event
        data:
          type: object
          properties:
            integration_id:
              type: string
              description: The unique identifier of the integration.
            integration_tool:
              type: string
              description: The name of the integrated tool (e.g., "personio", "greenhouse").
            integration_category:
              type: string
              enum:
              - HRIS
              - ATS
              - ASSESSMENT
              - LMS
              description: The category of the integration (HRIS, ATS, ASSESSMENT, or LMS).
            changed_models:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    enum:
                    - hris_legal_entities
                    - hris_locations
                    - hris_employees
                    - hris_absence_types
                    - hris_absences
                    - hris_employments
                    - hris_teams
                    - hris_time_off_balances
                    - hris_timesheets
                    - hris_employee_document_categories
                    - hris_performance_reviews
                    - hris_performance_review_cycles
                    - hris_staffing_entities
                    - ats_users
                    - ats_jobs
                    - ats_job_postings
                    - ats_candidates
                    - ats_application_stages
                    - ats_applications
                    - ats_screening_questions
                    - ats_tags
                    - ats_interviews
                    - ats_offers
                    - ats_rejection_reasons
                    - ats_roles
                    - lms_users
                    - lms_course_providers
                    - lms_skills
                    - lms_courses
                    - lms_course_revisions
                    - lms_course_progressions
                    - hris_join_employees_teams
                    - hris_join_staffing_entities_locations
                    - hris_join_staffing_entities_legal_entities
                    - hris_join_staffing_entities_groups
                    - ats_join_candidates_tags
                    - ats_join_jobs_application_stages
                    - ats_join_jobs_screening_questions
                    - ats_join_user_job_role_assignments
                    - ats_join_jobs_users
                    - ats_join_users_roles
                    - ats_join_interviews_users
                    - lms_join_revisions_skills
                    description: The name of the Kombo model or connection that changed.
                required:
                - name
                additionalProperties: false
                description: A model or connection that has changed in the integration.
              description: List of data models and connections for which one or more records were created, updated, or deleted.
          required:
          - integration_id
          - integration_tool
          - integration_category
          - changed_models
          additionalProperties: false
      required:
      - id
      - type
      - data
      additionalProperties: false
    AiApplyApplicationStatusUpdatedWebhookPayload:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this webhook event
        type:
          type: string
          enum:
          - ai-apply-application-status-updated
          description: Type of the webhook event
        data:
          type: object
          properties:
            id:
              type: string
              description: The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.
            job_posting_id:
              type: string
              description: The globally unique ID of this object generated by Kombo. We recommend using this as a stable primary key for syncing.
            status:
              type: string
              enum:
              - SUBMITTED
              - DUPLICATE
              - PENDING
              - FAILED
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
          required:
          - id
          - job_posting_id
          - status
          - created_at
      

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kombo/refs/heads/main/openapi/kombo-kombo-api-api-openapi.yml