Wipperoz Orbit public API

Version 1.0.0 · OpenAPI 3.1.0

Base URLs

The Orbit public API lets an account render its own jobs on its own site. Wipperoz is the production tool; the employer is the origin. Every job carries an applyLink to the Wipperoz-hosted apply page, which records the candidate's consent — the employer owns the page, Wipperoz owns the transaction.

Authentication

Every request carries an account API key, minted in Orbit → Settings → API keys. Send it either as Authorization: Bearer <key> or in the x-api-key header. A revoked key stops working within one request. Keys are account-scoped: every response is the calling account's jobs, and there is no cross-account read or write.

Four scopes, chosen when the key is minted and fixed for its life:

- jobs:read — the two read endpoints. What a careers site needs. - jobs:write — create, edit, publish and close. Publishing puts an advertisement in front of the public, so this is deliberately not implied by jobs:read: a key that renders a careers page should not also be able to post ads. - screening — invite a candidate to an AI screening on a managed ad. Issuing a key with this scope is the account's consent to screening overage: past a managed ad's included screenings, each screening is billed at the template's locked price without a per-call confirmation, up to the account's monthly overage cap. - applications:write — receive applications and candidates from your own page (below). Implied by neither jobs scope: these routes send Wipperoz people's details and CVs on the account's word, so a key carrying it can be minted only once an Admin of the account has accepted the API data-processing addendum (https://www.wipperoz.com/en/about/api-addendum).

Writing jobs

Creating and publishing are two calls. POST /v1/jobs makes a draft — nothing public — and POST /v1/jobs/{jobId}/publish takes it live. Publishing is free. An integration that wants the whole loop without a person calls both.

Editing a published ad stages the new words rather than replacing the ones candidates are applying against; the response says pendingRevision: true, and publishEdits: true promotes them in the same call. The closing date and the match cap are exempt and apply immediately — both exist to stop something.

Receiving applications

An employer can take applications on its own page and send them here; Wipperoz builds the candidate's Virtual CV and lets the employer read it for that application. Four calls:

1. GET /v1/consent-text — the sentence the candidate must be shown, in their language. Render it unmodified beside your apply button. The receipt you send back names its id and version; a reworded text is not one we handed out, and is refused. 2. POST /v1/uploads — a five-minute presigned PUT for the PDF. The file goes there, never through this API. 3. POST /v1/jobs/{jobId}/applications — the application: the candidate's details, the consent receipt (which text, when they accepted it, from where) and your attestation that the text was shown unmodified and the acceptance recorded truthfully. Both are stored verbatim with the application. Answered at once; the Virtual CV is built afterwards, and the candidate is emailed one link to claim it. 4. GET /v1/applications/{applicationId} — whether the CV has been built and whether the candidate has claimed it. Never the CV itself, and never the person.

POST /v1/candidates takes the same upload for a person who has not applied — a CV you hold — into My candidates, on your attestation alone; Wipperoz emails them a way to claim or delete it.

The application and candidate routes require an Idempotency-Key: a retried request without one is a second application and a second email to the candidate. Each account may send 500 applications a day through the API, across all its jobs, and import 100 candidates.

Retries

Send an Idempotency-Key header on POST requests. A retry with the same key returns the first answer (with Idempotent-Replay: true) instead of creating a second advertisement or publishing twice. A key is live for 24 hours; the same key sent later starts a new request. The same key with a different body is refused with 409, and so is a retry sent while the first request is still running. A request that died mid-way — a timeout, a dropped connection, no answer at all — may be retried with the same key after a minute: the abandoned attempt is taken over and the work runs once. Without the header, two identical creates make two ads.

Rate limits

120 requests per minute per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds); a request over the limit is answered 429 with Retry-After. A careers page that syncs incrementally needs a handful of calls an hour; the limit exists to stop a misconfigured loop.

Pagination

GET /v1/jobs returns up to limit jobs (default 50, maximum 100) and a nextCursor. Pass it back as cursor to fetch the next page; null means there is no more. Cursors are opaque and issued by this API only.

Incremental sync

updatedSince returns jobs edited, published or closed at or after the given moment. Expiry is time-based and writes nothing, so a page that syncs by updatedSince alone must read each job's expiresAt itself — or ask for status=published and treat anything missing as gone.

Errors

Every error is the same shape: {"error": {"code", "message", "requestId"}}. Quote the requestId to support.

Endpoints