Job feeds and bulk imports

Overview

Job feeds allow you to easily synchronize the job postings you have in your database with AI Apply. For each of your job inventory sources, set up a job feed, and periodically send an up-to-date list of all job postings using our bulk import endpoint. Kombo takes care of job posting creation, archival, updates, and more. A single job feed holds the jobs from one source, like a recruitment marketing partner or a specific employer with which you have a relationship.

How an import works

The bulk import response confirms that your records are stored, not that parsing has finished. New postings start with availability: PENDING. They become APPLYABLE after a successful parse, or UNAVAILABLE if parsing fails. The AI Apply data-changed webhook notifies you when a posting finishes parsing or an import archives one. The webhook identifies the changed model, not individual postings. After receiving it, fetch GET Job Postings with updated_after to find the postings and their current availability.

Creating a job feed

You must create the job feed before being able to bulk import. This can be done either in the Kombo Dashboard or through the API. Via API, the POST Job Feeds endpoint returns the new feed:

{
  "id": "mK7pQw9xNvEr2LdY5sGh8TcZ",
  "label": "Standard Acquisition Services LLC"
}

The returned id identifies the feed in every import you send afterwards. You can look it up again at any time with GET Job Feeds.

Choose clear, descriptive names for job feeds. Whenever possible, use the data source name so you can easily track the origin of imported job postings later.

Sending an import

Each import sends a newline-separated list of JSON records (NDJSON) as the request body, with one record per job posting.

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

{ "url": "https://careers.acme.com/job/1", "career_site_label": "ACME Corp" }
{ "url": "https://careers.acme.com/job/2", "career_site_label": "ACME Corp", "job_code": "ENG-123" }
{ "url": "https://careers.acme.com/job/3", "career_site_label": "ACME Corp", "location": { "country": "US", "postal_code": "94115" } }

Field	Required	Behavior
`url`	Yes	The job posting we parse and later submit applications to.
`career_site_label`	Yes	Groups the posting under a career site. We create a career site for each unique label automatically.
`job_code`	No	Your own identifier for the job.
`location`	No	Where we apply from. We route the browser session through that country, and through that state for US postal codes. Omitting it on a later import keeps the location we already have, and `null` clears it.

How postings are matched

Inside a feed, a posting is identified by its career site label, its URL, and its job code:

A record whose combination we have seen before updates that posting.
A new combination creates a posting and queues it for parsing.
A posting from an earlier import that is missing from the current one is archived. Its parsed data is kept, so a later import containing it again can revive it.

If the same combination appears twice within one import, the last record wins and no error is raised.

If you have frequent churn in job URLs between imports (e.g. a timestamp in the job URL) but your job codes are stable, please let us know. We can also match your feed on the job code alone, in which case every record needs a job_code and the url is upserted.

Note: Job postings imported through different job feeds are always treated as distinct!

Limits and failures

Send the body as application/x-ndjson.
A request may be at most 35 MB and take at most 5 minutes.
Only one import can run per job feed at a time.

If a record is invalid or ill-formatted, we abort the import at that line. Records before it may already have been created or updated, and nothing is archived. Fix the faulty record and submit the request again: because postings are matched instead of blindly inserted, resubmitting the same import is safe.

Example responses

A successful import responds with what happened to your postings:

{
  "status": "success",
  "data": {
    "created": 150,
    "processed": 197,
    "archived": 10
  }
}

processed: records we read from your request.
created: postings that did not exist yet and are now queued for parsing.
archived: postings from earlier imports that were missing from this one.

Errors use our standard error format, with code as the field to branch on:

{
  "status": "error",
  "error": {
    "code": "PLATFORM.INPUT_INVALID",
    "title": "Your request contains invalid data and failed validation.",
    "message": "Error parsing line number 42: url: URL must start with http:// or https://",
    "log_url": "https://app.kombo.dev/my-prod/logs?interactionId=123456"
  }
}

API reference

POST Bulk Import, including every error this endpoint can return
POST Job Feeds
GET Job Feeds

General

Implementation

Features

AI Apply API Reference

Job feeds and bulk imports

Overview

How an import works

Creating a job feed

Sending an import

How postings are matched

Limits and failures

Example responses

API reference

​Overview

​How an import works

​Creating a job feed

​Sending an import

​How postings are matched

​Limits and failures

​Example responses

​API reference

Overview

How an import works

Creating a job feed

Sending an import

How postings are matched

Limits and failures

Example responses

API reference