Screening

201 — The screening was sent. Body: ScreeningTriggered.

{
  "screening": {
    "screeningId": "8d3f6a2e-4b1c-4f0a-9e7d-2c5b8a1f0e3d",
    "jobId": "job_01J8Z3K9Q0EXAMPLE",
    "candidateId": "app_01J9B2C3D4EXAMPLE",
    "templateId": "tpl_01J9C3D4E5EXAMPLE",
    "status": "invited",
    "deliveryPath": "token",
    "completeBy": "2026-10-02T00:00:00.000Z",
    "requestedAt": "2026-09-25T01:10:00.000Z"
  },
  "billing": "overage",
  "priceCents": 300,
  "currency": "AUD"
}

400 — A query parameter is malformed. The message says which. Body: Error.

{
  "error": {
    "code": "bad_request",
    "message": "`limit` must be an integer between 1 and 100",
    "requestId": "5f7a9c1e-2b3d-4e5f-8a9b-0c1d2e3f4a5b"
  }
}

401 — No API key, or one that is not valid. Body: Error.

{
  "error": {
    "code": "unauthorized",
    "message": "This endpoint requires an API key. Send it as `Authorization: Bearer <key>` or in `x-api-key`.",
    "requestId": "5f7a9c1e-2b3d-4e5f-8a9b-0c1d2e3f4a5b"
  }
}

402 — No screening was sent, for one of two reasons (error.code): - overage_cap_reached — this screening is past the ad's included ones and would take the account past its monthly overage cap. A billing admin can raise the cap in Orbit. The error carries the screening's priceCents and currency, and the account's capCents and spendCents. - subscription_paused — the account's subscription is paused. The error carries resumesAt (ISO 8601), when it resumes; a billing admin can resume it early in Orbit. For example: {"error": {"code": "subscription_paused", "message": "Your subscription is paused until 14 Jan 2027 — resume to use this.", "requestId": "…", "resumesAt": "2027-01-14T00:00:00.000Z"}} Body: Error.

{
  "error": {
    "code": "overage_cap_reached",
    "message": "This screening would pass the account's monthly overage cap.",
    "requestId": "5f7a9c1e-2b3d-4e5f-8a9b-0c1d2e3f4a5b",
    "priceCents": 300,
    "currency": "AUD",
    "capCents": 20000,
    "spendCents": 19800
  }
}

403 — The key is valid but does not carry the scope this route needs. Body: Error.

{
  "error": {
    "code": "forbidden",
    "message": "This key does not carry the `jobs:read` scope. Mint a key with it in Orbit → Settings → API keys.",
    "requestId": "5f7a9c1e-2b3d-4e5f-8a9b-0c1d2e3f4a5b"
  }
}

404 — No such job on this account. Body: Error.

{
  "error": {
    "code": "not_found",
    "message": "No such job on this account",
    "requestId": "5f7a9c1e-2b3d-4e5f-8a9b-0c1d2e3f4a5b"
  }
}

409 — The role is not a managed ad, so it cannot screen (ad_not_managed). The same status answers a screening already open for this candidate on this role (conflict) and a template whose price cannot be read (price_unavailable). Body: Error.

{
  "error": {
    "code": "ad_not_managed",
    "message": "Only a managed ad can screen candidates. Manage this ad in Orbit first.",
    "requestId": "5f7a9c1e-2b3d-4e5f-8a9b-0c1d2e3f4a5b"
  }
}

429 — The candidate did not apply and has had as much unsolicited contact as they allow this week. Body: Error.

Error

ScreeningRequest

ScreeningTriggered

JobList

Skill

Salary

Location

Where the role is. address is the place in the recruiter's words — a picked suggestion's full address, or text typed by hand — and it is what the Wipperoz job page shows first. city, state and country are set only when the place was picked from a suggestion (or sent by you), so a location typed by hand is address alone: show address when it is there, and build structured data (jobLocation) from the parts. A job needs a country to be published for the first time.

Company

Job

Enough to build a JobPosting JSON-LD block: title, description, postedAt → datePosted, expiresAt → validThrough, company → hiringOrganization, location → jobLocation, salary → baseSalary, employmentType.

JobWrite

What you may set on a job. Every field is optional on PATCH; title is required on POST. The vocabulary is the one the reads return, so an enum you already map for rendering is the enum you send. What you may **not** set: status, id, slug, url, applyLink, company, postedAt, updatedAt and closedAt are ours — derived, permanent, or a lifecycle transition with its own endpoint. Sending one is a 400, deliberately, rather than being ignored: a field you thought you set and we silently dropped is worse than an error.

AuthoredJob

The job as its own account sees it. Identical to Job, except that status may also be draft — the state a job is created in, which the read endpoints never return. A draft already carries an applyLink. It does not resolve until the role is published; it is there so a careers page can be built against the record before it goes live.

ConsentText

UploadSlot

ConsentReceipt

Your record of showing the candidate the consent text and recording their acceptance. Stored verbatim with the application, beside our own copy of the text in locale — what the candidate read.

ApplicationWrite

ApplicationCreated

ApplicationStatus

CandidateWrite

CandidateCreated