Sending applications through posting inquiry

Overview

A posting inquiry is the call you make at the moment a candidate wants to apply. It hands you the application form as it stands right now, together with a token that submits exactly that form, for one candidate. This is the default flow for AI Apply and has the benefit that it guarantees you use the most up-to-date version of the form and does not require you to implement complex sync logic. This flow follows three steps:

You inquire about a specific job posting when a candidate opens the application form on your side. You receive the form to show to the candidate and a token for later submission.
You show the candidate the form and collect their answers.
You send the collected answers to Kombo using the submission token.

Kombo will then deliver the application and send you a webhook once the application is completed. This guide assumes the postings already exist. Get them there with job feeds or by creating them manually.

When to use it

We recommend using this flow by default. Use the GET Job Postings Forms endpoint and flow only when you specifically need to know all application forms before the candidate interacts with your product.

Both paths end at the same POST Apply call. The only difference is where the form and the token came from.

How it works

Syncing job postings

An inquiry requires the ID of an applyable posting, so your system needs a current list of the postings in your environment. Paginate through GET Job Postings to build that list, and keep it current with the data-changed webhook and the updated_after filter as described in Data fetching.

Getting the application form

POST Inquiries takes the posting ID in the path and returns the form with a token:

{
  "application_form": [
    {
      "block_type": "SECTION",
      "label": "Personal Information",
      "children": [
        {
          "block_type": "QUESTION",
          "question_id": "6VrjehyBk685vubNydiR1hSn",
          "label": "First name",
          "required": true,
          "question_type": "TEXT",
          "unified_key": "FIRST_NAME",
          "options": null,
          "display_when": null
        }
      ]
    }
  ],
  "submission_token": "<token>"
}

See The Application Form for the full block structure, the unified keys, and how display_when drives conditional questions.

Inquiring re-checks the job posting’s availability before returning. A posting that went offline since your last sync fails here rather than after the candidate has filled out the form.

You do not need to specifically reconcile error responses due to unavailability with your stored data if you use the AI Apply data-changed webhook. You will receive a webhook instead.

The token

The submission_token is a JWT bound to three things: the job posting, the exact form version you were handed, and your environment.

It is single use. Once an application exists for it, submitting again fails.
It expires after two days.
It belongs to one form. Store it next to the form it arrived with. Your answers are validated against that exact version.

Do not fetch a token ahead of time and hold it. A token is cheap to request and tied to a form that can change, so inquire it only when a candidate is actively interacting with the form on your page.

Sending an application

POST Apply takes the token and the answers:

{
  "submission_token": "<token>",
  "candidate_email": "john.doe@gmail.com",
  "screening_question_answers": [
    {
      "question_id": "6VrjehyBk685vubNydiR1hSn",
      "answer": "John"
    }
  ]
}

Field	Required	Behavior
`submission_token`	Yes	The token from the inquiry, paired with the form you answered.
`candidate_email`	Yes	Supply this from your own system. Do not ask for it on the form. It does not prevent duplicate applications.
`screening_question_answers`	Yes	One entry per answered question. See Candidate answers for formats.
`query_params`	No	Appended to the job posting URL when applying. See Query parameters.
`additional_clicks`	No	Simulates the job being opened this many extra times, scattered over 60 minutes by default.

Answers have to match the form the token was issued with. A question ID that is not in that form, or a missing required answer, is rejected rather than ignored.

Return value and webhooks

Applying is asynchronous. The response confirms we accepted the application and queued it:

{
  "id": "ADbmw5XSkeCSE1fAucoxEGnwZ",
  "posting_id": "JDn252PEYa4rMhKbJBjtn3ng",
  "status": "PENDING",
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-03-02T23:12:32.000Z"
}

Keep the returned id. It is how you match this application to webhooks later on.

Status	Meaning
`PENDING`	We are applying, or the application is waiting on manual review.
`SUBMITTED`	The application reached the job site.
`DUPLICATE`	The ATS rejected it because this candidate had already applied.
`FAILED`	We established that the application cannot be submitted.

We emit the application status updated webhook on every status except PENDING, so one arrives per application once it settles. GET Applications is the polling alternative, and carries the same updated_after filter as the posting endpoints. See Webhooks for payloads.

proxy_email is only populated once an application is SUBMITTED. See Candidate account creation to learn when we create an account on the candidate’s behalf.

A failure does not reach you immediately. Every failed submission goes through Kombo’s QA first, and we only report FAILED once we have confirmed we cannot submit the application in any way. See QA Mode for more info.

General

Guides

AI Apply API Reference

Sending applications through posting inquiry

Overview

When to use it

How it works

Syncing job postings

Getting the application form

The token

Sending an application

Return value and webhooks

API reference

​Overview

​When to use it

​How it works

​Syncing job postings

​Getting the application form

​The token

​Sending an application

​Return value and webhooks

​API reference

Overview

When to use it

How it works

Syncing job postings

Getting the application form

The token

Sending an application

Return value and webhooks

API reference