Sending applications through posting inquiry

Fetch the live application form for a job posting and submit a candidate application against it.

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:

1. 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.
2. You show the candidate the form and collect their answers.
3. 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.

Submitting the application

Once the candidate has answered the form, submit it with the token from the inquiry. See Submitting applications for preparing the answers, the request, and tracking the result.

API reference

• POST Inquiries
• GET Job Postings Forms