Manual management of job postings

Overview

Use manual management when you cannot send a complete job feed, for example because your ingestion pipeline processes one posting at a time. Manual management allows you to create career sites and postings individually through the API. The application flow works the same way as described in your implementation guide.

We recommend job feeds when possible. Managing postings individually takes more work.

Why we advise against it

You own the bookkeeping. Career site labels are not unique, so sending the same label twice creates a second career site rather than returning the first. Job feeds handle this out of the box.
You handle duplicates. A job posting is identified by its career site, URL, and job code. Submitting a posting you already created returns an AI_APPLY.JOB_POSTING_ALREADY_EXISTS error. So you need to keep track of what you already sent to AI Apply and what still needs parsing.

How it works

The posting comes back before parsing has finished, with availability set to PENDING. It becomes APPLYABLE once parsing succeeds, and UNAVAILABLE if it fails. We send an AI Apply data-changed webhook when a job posting’s status changes. See Data fetching for the lifecycle and payloads, or poll GET Job Postings if you would rather not receive webhooks.

Creating a career site

A career site groups job postings under one entity. Create one per employer whose jobs you send us. POST Career Sites takes a label and returns the career site:

{
  "id": "mK7pQw9xNvEr2LdY5sGh8TcZ",
  "label": "Acme Inc. California"
}

Store the returned id. You need it for every posting you create, and there is no way to look a career site up by label: GET Career Sites lists them, but nothing stops two of them sharing a label.

Use a label you can trace back to the source, and keep your own mapping from that source to the returned id. Recreating a career site because the mapping was lost splits one employer’s postings across two entities.

Creating a job posting

POST Job Postings queues a posting for parsing:

{
  "career_site_id": "mK7pQw9xNvEr2LdY5sGh8TcZ",
  "url": "https://careers.acme.com/jobs/fullstack-engineer-14102",
  "job_code": "ACME_13",
  "location": {
    "country": "US",
    "postal_code": "94116"
  }
}

Field	Required	Behavior
`career_site_id`	Yes	The career site to group this posting under.
`url`	Yes	The job posting we parse and later submit applications to.
`job_code`	No	Your own identifier for the job. Also part of what makes a posting unique.
`location`	No	Where we apply from. We route the browser session through that country, and through that state for US postal codes. Without it, we run from our own infrastructure.

Query parameters in the posting URL can affect the parsed form. See Query parameters.

The response is the job posting, with availability set to PENDING until parsing finishes:

{
  "id": "9QGNv3B98kL3hyELE1qsZ86s",
  "career_site": {
    "id": "mK7pQw9xNvEr2LdY5sGh8TcZ",
    "label": "Acme Inc. California"
  },
  "url": "https://careers.acme.com/jobs/fullstack-engineer-14102",
  "job_code": "ACME_13",
  "availability": "PENDING",
  "archived_at": null,
  "archived_reason": null
}

Submitting the same career site, URL, and job code again returns an error rather than a second posting:

{
  "status": "error",
  "error": {
    "code": "AI_APPLY.JOB_POSTING_ALREADY_EXISTS",
    "title": "A job posting with this URL already exists for this career site.",
    "message": "A job posting with the same URL has already been submitted for this career site. You can retrieve the existing job posting via GET /v1/ai-apply/postings and filtering by URL.",
    "log_url": "https://app.kombo.dev/my-prod/logs?interactionId=123456"
  }
}

Keeping state in sync

Postings you create this way are archived in two cases: when we detect that the job has been taken offline, and when someone archives it in the Kombo Dashboard. Neither transition is dispatched from your system, so you learn about it rather than cause it. Keep your copy current by syncing GET Job Postings with updated_after, triggered by the data-changed webhook or on a schedule. The pattern is described in Data fetching. Before you show a job to a candidate, check availability and archived_at on your copy. Anything you no longer offer that is still APPLYABLE on our side is yours to hide. Job feeds remove this reconciliation entirely: one request replaces the whole list and archives whatever you left out.

General

Implementation

Features

AI Apply API Reference

Manual management of job postings

Overview

Why we advise against it

How it works

Creating a career site

Creating a job posting

Keeping state in sync

API reference

​Overview

​Why we advise against it

​How it works

​Creating a career site

​Creating a job posting

​Keeping state in sync

​API reference

Overview

Why we advise against it

How it works

Creating a career site

Creating a job posting

Keeping state in sync

API reference