Partner API — Integration Guide
Everything you need to pull vacancies/applications and receive webhook events for a company on Fintech Careers. For the full REST request/response schemas, see the API reference — this page is the narrative walkthrough, especially for webhooks.
What this API is for
The Fintech Careers Partner API lets a company pull and manage its own vacancies and applications over REST, and subscribe to webhooks to receive real-time events about its own company's activity on Fintech Careers — a vacancy getting published, a new application coming in, an application's status changing, and more. It is scoped strictly to one company's own data: there is no cross-company access of any kind.
Quickstart
The whole integration in five steps. Each one links down to the fuller section below it for the details.
- Generate an API key. An OWNER creates a scoped key from Company Settings in the app. See Getting an API key.
-
Make your first authenticated REST call. Send
the raw key as a bearer token, e.g.
GET /v1/partner/vacancies. See Authenticating REST calls. - Subscribe a webhook URL to an event. Register an endpoint and pick which events from the event catalog it should receive.
- Verify an incoming signature. Every delivery is HMAC-signed — verify it before trusting the payload. See Signature verification for working Node.js and Python code.
- You're done. Failed deliveries retry automatically for up to 24 hours; see Retries & auto-disable for what happens if your endpoint stays down.
Getting an API key
An OWNER of the company generates an API key from
Company Settings in the app (this guide doesn't
cover logging into the app itself). The raw key —
pk_live_<64 hex chars> — is shown
exactly once, at creation. It is never stored in
recoverable form on our side (we keep a SHA-256 hash), so if it's
lost, revoke it and create a new one.
Each key carries one or more scopes — READ,
WRITE — and a per-minute rate limit set by the OWNER.
A key scoped to READ only can never call a
WRITE endpoint, regardless of what it's asked to do.
Authenticating REST calls
Every partner REST request carries the raw key as a bearer token:
Authorization: Bearer pk_live_6f2c9a1e...
An unknown or revoked key always returns the same 401
— the response deliberately never reveals which of those it was,
so an attacker probing keys can't distinguish "wrong" from "used
to be right." (A completely missing key is distinguishable — see
Common error responses for the exact split.)
When a company is deleted, every API key it has is revoked: from
that moment each call with one of them gets this same
401.
Every path in this guide and in the
API reference is relative to the
API base URL: <API base URL>.
curl <API base URL>/v1/partner/vacancies \
-H "Authorization: Bearer pk_live_6f2c9a1e..."
Every list endpoint (GET /v1/partner/vacancies,
GET /v1/partner/applications) returns the same
paginated envelope — items is the allow-listed
shape described under Webhook payload
shapes (the REST and webhook shapes are identical, see
below), the rest is standard offset pagination:
{
"items": [ /* ...PartnerVacancyPayload or PartnerApplicationPayload objects... */ ],
"page": 1,
"pageSize": 20,
"totalItems": 42,
"totalPages": 3
}
page is 1-based, both page and
pageSize come from the identically-named query
params (defaults 1 / 20), and
pageSize is clamped server-side to
1–100 — asking for more than 100 per
page just gets you 100, not an error.
Each of those also has a single-item form —
GET /v1/partner/vacancies/:id and
GET /v1/partner/applications/:id — returning one
items-shaped object directly (no envelope). Both
404 identically whether the id doesn't exist or belongs to
another company; see
404 — cross-company isolation. There's also
GET /v1/partner/company, which takes no
:id at all — an API key belongs to exactly one
company, so it always returns that key's own profile, in the
same allow-listed shape as the company.* webhook
payload below.
Rate limits
Each key is limited to its own configured
rateLimitPerMinute, enforced as a fixed 60-second
window per key (not a sliding window / token bucket). Exceeding it
returns 429:
{
"statusCode": 429,
"message": "Rate limit exceeded",
"code": "RATE_LIMIT_EXCEEDED",
"metadata": {
"apiKeyId": "ak_3f9c...",
"retryAfterSeconds": 42
},
"timestamp": "2026-09-17T10:30:00.000Z",
"path": "/v1/partner/vacancies"
}
Wait at least metadata.retryAfterSeconds before
retrying. The limiter fails closed: if our rate
limiter backend is unreachable, requests are refused rather than
let through unlimited — you may see a burst of 429s
during an incident on our side even if you're well under your
normal limit.
Event catalog
The full, current event catalog — generated from the same source
of truth the webhook dispatcher itself reads
(PARTNER_EVENT_CATALOG /
KAFKA_EVENT_CLASS_TO_CATALOG_KEY), via
event-catalog.json next to this page (produced by
npm run export:partner-openapi). A subscription's
eventNames must be a subset of the event
column below; an unknown name is rejected at subscription-create
time, not silently ignored.
Loading the current catalog…
| Event | Entity | Source domain event | Fires when… |
|---|
Webhook payload shapes
Every webhook delivery has the same envelope, whatever the event:
{
"event": "vacancy.published",
"id": "<the entity's own id>",
"timestamp": "<ISO-8601, when the source event occurred>",
"data": { /* one of the four allow-listed shapes below */ }
}
data is an explicit, hand-picked allow-list per
entity kind — never a raw internal DTO passed through. The exact
same shape is what GET /v1/partner/vacancies and
GET /v1/partner/applications return, so there is no
back door to read a field the push side keeps out.
The example JSON below shows one populated row of real-looking
data, not every field's actual optionality — several fields
(description, website,
logoUrl, and similar) can genuinely be
null even though the example happens to show a
value. Treat any field typed string | null (or
similarly) in the API reference's
schema as something your integration must handle being absent,
regardless of what the example here shows.
company company.*
{
"id": "6f1a2b3c-45d6-4e7a-8b9c-1234567890ab",
"name": "Acme Robotics",
"description": "We build warehouse robots.",
"website": "https://acme-robotics.example.com",
"logoUrl": "https://cdn.jobs.example.com/logos/acme.png",
"industryId": "ind_software",
"size": "51-200",
"hqCity": "Berlin",
"hqCountryId": "country_de",
"status": "ACTIVE",
"createdAt": "2026-01-14T09:12:00.000Z",
"updatedAt": "2026-06-02T11:45:00.000Z"
}
status is ACTIVE or BLOCKED
— included specifically because company.blocked /
company.unblocked exist to tell you exactly this.
company.deleted carries the company as it was just
before the delete. When a company is deleted, its API keys are
revoked (see Authenticating REST
calls) and its webhook subscriptions are switched off:
nothing that happens after the delete is sent to them.
Deliveries already queued, this company.deleted
among them, still go out, with the usual
retries. A blocked company keeps its keys
and subscriptions.
company.deleted is not always the last webhook you
get for the company: the retries of a delivery queued before it,
and an event from the moments before the delete, can arrive
after it, for as long as the retry schedule runs (about 24
hours). Don't treat it as the end of the company's stream: a
later webhook's timestamp tells you when that event
happened.
Pull the same shape any time with
GET /v1/partner/company — useful if you were only
subscribed to webhooks starting after the company's last change,
or just want a plain pull-based way to refresh it.
vacancy vacancy.*
{
"id": "8a2e5f10-9c3b-4d1e-a7f2-0987654321cd",
"companyId": "6f1a2b3c-45d6-4e7a-8b9c-1234567890ab",
"title": "Senior Backend Engineer",
"description": "Own our vacancies service end to end.",
"salary": { "from": 4000, "to": 6000, "currency": "EUR" },
"isSalaryPublic": true,
"experienceMonths": 36,
"level": "SENIOR",
"workFormats": ["REMOTE", "HYBRID"],
"employmentType": "FULL_TIME",
"skills": ["Node.js", "PostgreSQL"],
"techStack": ["TypeScript", "NestJS", "Kafka"],
"responsibilities": ["Design APIs", "Mentor engineers"],
"department": "Engineering",
"city": "Berlin",
"countryId": "country_de",
"categoryTagId": "cat_backend",
"questions": [
{
"id": "q1",
"text": "Years of production Node.js experience?",
"type": "TEXT",
"options": [],
"required": true
}
],
"status": "PUBLISHED",
"viewCount": 214,
"scheduledPublishAt": null,
"createdAt": "2026-05-30T08:00:00.000Z",
"updatedAt": "2026-06-02T11:45:03.000Z"
}
status is one of DRAFT,
PUBLISHED, SCHEDULED,
CLOSED, ARCHIVED — the vacancy's public
lifecycle only (see
Publishing & closing
vacancies). Internal moderation state is a separate axis this
payload never exposes.
skills and techStack are free text.
In techStack, a technology the platform knows is
stored under its common name: send golang and read
back Go in GET responses and in
vacancy.updated payloads (PATCH
answers only a message); duplicates of one technology are
stored once. techStack takes at most 100 items of
200 characters each (a vacancy that already holds more items,
or a longer one, keeps them, but cannot add more or another
longer one); anything other than an array of strings
is a 400 Validation failed
(field: "VacancyTechStack", see
Common error responses), and on a create
the draft with its title has already been made, as with any
other refused field. skills is stored as sent.
The known names: GET /v1/dictionaries/skills?q=….
level is one of INTERN,
JUNIOR, MIDDLE, SENIOR,
LEAD, HEAD, DIRECTOR,
C_LEVEL, or null when the vacancy does
not name one — the same values the create and update endpoints
accept. null is for a draft: a vacancy needs a
level, an employmentType and a
salary to be published (see
Required content), so a live
vacancy has them unless it went live before they were required
or a job feed imported it.
title is 1–80 characters. A longer one is a
400 Validation failed
(field: "VacancyTitle", see
Common error responses); a title saved
before this limit may be sent back unchanged on a
PATCH.
application application.*
{
"id": "c3d4e5f6-1122-4a5b-9c8d-abcdefabcdef",
"vacancyId": "8a2e5f10-9c3b-4d1e-a7f2-0987654321cd",
"companyId": "6f1a2b3c-45d6-4e7a-8b9c-1234567890ab",
"applicantUserId": "usr_7788",
"resumeId": "res_3344",
"answers": [{ "questionId": "q1", "answer": ["4 years"] }],
"coverLetter": "I'd love to help build the vacancies service.",
"status": "NEW",
"source": "SELF_APPLIED",
"proposalMessage": null,
"proposedAt": null,
"respondedAt": null,
"expiresAt": null,
"createdAt": "2026-06-02T12:00:00.000Z",
"updatedAt": "2026-06-02T12:00:00.000Z"
}
status is the ATS pipeline stage (NEW,
REVIEWED, INTERVIEW,
HIRED, ARCHIVED — rejected
— or WITHDRAWN) for a SELF_APPLIED row,
or a proposal state (PROPOSED,
PROPOSAL_DECLINED, PROPOSAL_REVOKED,
PROPOSAL_EXPIRED) for a SOURCED one that
hasn't turned into role_proposal.accepted yet.
The former PHONE_SCREEN, ON_SITE and
OFFER stages were merged into
INTERVIEW and are never sent any more.
roleProposal role_proposal.*
{
"id": "c3d4e5f6-1122-4a5b-9c8d-abcdefabcdef",
"vacancyId": "8a2e5f10-9c3b-4d1e-a7f2-0987654321cd",
"companyId": "6f1a2b3c-45d6-4e7a-8b9c-1234567890ab",
"candidateUserId": "usr_9911",
"status": "PROPOSED",
"proposalMessage": "We think you'd be a great fit for this role.",
"proposedAt": "2026-06-01T10:00:00.000Z",
"respondedAt": null,
"expiresAt": "2026-06-08T10:00:00.000Z",
"createdAt": "2026-06-01T10:00:00.000Z",
"updatedAt": "2026-06-01T10:00:00.000Z"
}
Once a proposal is accepted, the same underlying row is delivered
through application.* events instead (with
source: "SOURCED") — resume/answers/cover-letter
fields don't apply to a not-yet-accepted proposal, so they're not
on this shape at all.
Resolving ids to readable data
Several fields above are opaque foreign-key ids rather than
human-readable values — industryId,
hqCountryId, countryId,
categoryTagId, applicantUserId,
candidateUserId. Each has a lookup endpoint. All of
the reference-data ones below are unauthenticated (no API key
needed) and safe to cache aggressively — this data changes
rarely.
| Field | Resolve with |
|---|---|
countryId / hqCountryId |
GET /v1/countries (list, optional
?search=) or
GET /v1/countries/:id
|
industryId |
GET /v1/industries or
GET /v1/industries/:id
|
categoryTagId |
GET /v1/category-tags or
GET /v1/category-tags/:id
|
applicantUserId / candidateUserId
|
GET /v1/identity/users/:userId → public
profile (id, firstName,
lastName, photo) only —
deliberately no email/phone/resume access; see below.
|
GET /v1/reference-data bundles countries, industries
and category tags into a single response, if pulling all three
up front and caching them locally is more convenient than three
separate calls:
{
"countries": [ { "id": "country_de", "name": "Germany" }, ... ],
"industries": [ { "id": "ind_software", "name": "Software" }, ... ],
"categoryTags": [ { "id": "cat_backend", "name": "Backend" }, ... ]
}
Resumes are deliberately not exposed to partners.
resumeId on the application payload has
no partner-accessible lookup — even a company's own
session-authenticated recruiter can only see a candidate's resume
once it's PUBLISHED by that candidate; there's no
broader grant for a company to read a non-published resume tied
to its own application, and the partner API doesn't invent one.
Treat resumeId as an opaque reference you can echo
back into your own system, not something you resolve.
Publishing & closing vacancies
POST /v1/partner/vacancies creates a
DRAFT. These WRITE-scope endpoints
move it through the rest of its life. Like every write here,
they run the same commands as the buttons in the app, acting as
the API key's original creator, so credits,
moderation and content checks behave exactly as they do for a
recruiter. None takes a body. Each answers
200 with the vacancy re-read after the change (same
shape as GET /v1/partner/vacancies/:id), except
delete, which answers 204.
| Endpoint | Accepted from | Result | Webhook |
|---|---|---|---|
| POST /v1/partner/vacancies/:id/publish | any status but PUBLISHED |
PUBLISHED: in the public search, open to applications |
vacancy.published |
| POST /v1/partner/vacancies/:id/unpublish | PUBLISHED |
DRAFT: offline, data and applications kept |
vacancy.unpublished |
| POST /v1/partner/vacancies/:id/close | any status but CLOSED |
CLOSED: no new applications, the existing ones stay with you |
vacancy.closed |
| POST /v1/partner/vacancies/:id/restore | ARCHIVED only |
PUBLISHED again |
vacancy.published |
| DELETE /v1/partner/vacancies/:id | any status | gone: every endpoint answers 404 for the id afterwards |
vacancy.deleted |
A vacancy becomes ARCHIVED on its own when its paid
period runs out (vacancy.archived). Bring it back
with publish or restore; they do the
same, but restore refuses any other status, for when
you mean "only if it was archived". To reopen a
CLOSED or unpublished vacancy, call
publish.
The vacancy.deleted webhook carries the vacancy as
it was just before the delete.
Vacancies imported from your ATS. If a job feed
is connected to your company, the vacancies it imports follow the
source: one removed there is archived here within minutes. Such
a vacancy cannot be deleted through this API
(409 VACANCY_MANAGED_BY_FEED); remove it at the
source, or close or unpublish it to
hide it meanwhile.
Addressing a vacancy by its ATS id
A vacancy a job feed imported keeps the id your ATS gave it (a Teamtailor job id, for example). You can use that id instead of ours, so acting on one job needs no lookup first:
-
GET /v1/partner/vacancies/external/:externalId
— the vacancy, same shape as
GET .../:id; itsidis ours.READscope. -
POST /v1/partner/vacancies/external/:externalId/publish,
/unpublish,/close,/restore— exactly the actions above, with the same rules, answers and errors.WRITEscope.
curl -X POST <API base URL>/v1/partner/vacancies/external/8331292/close \
-H "Authorization: Bearer pk_live_6f2c9a1e..."
An id that none of your company's vacancies carries answers
404, like an unknown :id. Only
vacancies a feed imported have an ATS id; there is no
PATCH or DELETE by ATS id, since the
feed keeps their content in step with your ATS and they cannot
be deleted.
With roles switched on, a vacancy stands for
a role rather than one posting: address it through
GET /v1/partner/roles/:roleId, whose
vacancy.id works with every
/v1/partner/vacancies/:id route.
external/:externalId keeps addressing the per-posting
vacancies imported before the switch by their posting id.
Job-post credits
One credit keeps one vacancy live for a 60-day paid period.
-
A first publish, a publish after the period ran out, and a
publish or restore of an
ARCHIVEDvacancy each take one credit and start a new period. With no credit left (and no unlimited plan) they answer402 NO_JOB_POST_CREDITSand nothing changes. - Unpublish and close never give a spent credit back, and the period keeps running while the vacancy is offline. Publishing it again before the period ends is free and does not extend it.
- A credit that is only reserved (the vacancy is waiting for moderation, or for a scheduled publish) goes back to the balance on close or delete. Deleting a vacancy that already spent its credit is not a refund.
Required content
A vacancy can be created and edited as a draft with only its
title. To go live — publish, or
restore of an archived one — it needs:
- a
description; - a
countryId, unlessworkFormatsincludesREMOTE; - an
employmentType; - a
level; - a
salary:from,toor both, with itscurrency. SetisSalaryPublic: falseto keep it off the job page.
Without them the call answers
422 VACANCY_MISSING_REQUIRED_CONTENT, and
metadata.missingFields names what is short, as the
field names above. Once a vacancy is PUBLISHED (or
scheduled from the app), a PATCH that would clear its
salary, employmentType or
level answers the same 422 and changes
nothing. A vacancy that went live before these three were required
can still be edited without them, but needs them to be published
again once it is offline. A vacancy a job feed imported from your
ATS does not need the three: its source does not always send
them.
Moderation
If your company's postings are reviewed before going live,
publish and restore still answer
200 with status: "PUBLISHED", but the
vacancy stays out of the public search until a moderator
approves it. The credit is reserved, not spent, and the paid
period starts at approval. Watch for the
vacancy.published webhook: it is sent only when the
vacancy actually goes live.
Errors
-
400— the vacancy is not in a state the action accepts:VACANCY_ALREADY_PUBLISHED,VACANCY_NOT_PUBLISHED,VACANCY_ALREADY_CLOSED,VACANCY_NOT_ARCHIVED. -
402 NO_JOB_POST_CREDITS— publish or restore with no credit available. -
422— publish and restore:VACANCY_MISSING_REQUIRED_CONTENT, withmetadata.missingFieldslisting what to fill in first (see Required content:description,countryId,employmentType,level,salary), orVACANCY_CONTAINS_BANNED_TERMSwhen the title or description contains a term the platform does not allow. APATCHof a live vacancy answers the same two: one that would clear itssalary,employmentTypeorlevel, or put a banned term in. -
403—API_KEY_MISSING_SCOPE(the key has noWRITE),INSUFFICIENT_VACANCY_PERMISSION(the key's creator is no longer a company member allowed to manage vacancies), orCOMPANY_BLOCKEDon publish and restore (the company has been suspended). -
404— no vacancy with this id belongs to your company, checked before anything is attempted. -
409 VACANCY_MANAGED_BY_FEED— delete of a vacancy imported from your ATS (see above).
Roles: one vacancy per hire
For a company whose ATS feed is connected, the platform imports
one vacancy per ATS posting. When you advertise one hire through
several postings (one per location, for example), group them
into a role and get one vacancy per role
instead. Roles are switched on per company on request (ask your
account manager); until then these endpoints answer
403 PARTNER_ROLES_NOT_ENABLED. Once they are on,
the feed no longer creates vacancies by itself: every new
vacancy comes from a role.
-
PUT /v1/partner/roles/:roleId
— set the role's state.
WRITEscope. -
GET /v1/partner/roles/:roleId
— read it back, with its vacancy.
READscope.
curl -X PUT <API base URL>/v1/partner/roles/role-4711 \
-H "Authorization: Bearer pk_live_6f2c9a1e..." \
-H "Content-Type: application/json" \
-d '{
"status": "published",
"applyJobId": "8331292",
"jobIds": ["8331292", "8331300"],
"occurredAt": "2026-11-02T13:00:00Z"
}'
| Field | Meaning |
|---|---|
roleId (path) |
Your own id for the role: 1–255 characters, no whitespace,
control characters or /.
|
status |
"published" or "closed". |
applyJobId |
Required for published. The ATS posting whose
content the vacancy shows and whose application page its
Apply button opens. The vacancy shows
only this posting; nothing is merged from
the role's other postings. It must be open (published or
unlisted) and not internal; an unlisted posting works as
long as the ATS access you gave us can read it. A string of
digits without leading zeros (a JSON number is accepted
too). Ignored for closed: the role keeps the
last one.
|
jobIds |
Every open posting of the role. Optional, at most 50
distinct ids; applyJobId is added when
missing. The platform uses it to retire the per-posting
vacancies of these postings (see
Switching to roles).
|
occurredAt |
When the role reached this state in your system: ISO-8601 with a time zone, at most 5 minutes ahead of our clock. Requests are ordered by it (see below). |
Always send the role's whole current state; the call is
idempotent. Every accepted request answers 200:
{
"roleId": "role-4711",
"status": "published",
"applyJobId": "8331292",
"jobIds": ["8331292", "8331300"],
"occurredAt": "2026-11-02T13:00:00.000Z",
"pending": false,
"applyUrl": "https://careers.example.com/jobs/8331292-backend-engineer",
"vacancy": { "id": "8a2e5f10-...", "status": "PUBLISHED", "title": "Backend Engineer", ... },
"result": "created"
}
vacancy is the same shape as
GET /v1/partner/vacancies/:id (null while the role
has none), applyUrl is where its Apply button
sends candidates, and result (PUT only) says what
the request did:
| Request | What happens | result |
Webhooks |
|---|---|---|---|
published, no vacancy for this role yet |
A vacancy is created from the applyJobId posting and published. |
created |
vacancy.created, vacancy.updated, vacancy.published |
published, no role vacancy yet, but one of the role's postings already has its own vacancy |
That vacancy becomes the role's (its URL, views and
bookmarks are kept) and shows the
applyJobId posting from now on.
|
adopted |
vacancy.updated, plus vacancy.published if it was not live |
Another applyJobId |
The same vacancy; its content and Apply link are re-read from the new posting. | updated |
vacancy.updated |
closed |
The vacancy stops taking applications. It is not removed:
its page stays reachable and says the vacancy is no longer
accepting applications (status: "ARCHIVED").
|
closed |
vacancy.archived |
published again after closed |
The same vacancy is published again. | reopened |
vacancy.published |
| The same state again | Nothing. | unchanged |
none |
occurredAt older than the last accepted request |
Nothing; the answer is the current state. | stale |
none |
published, but a moderator took the vacancy down |
Accepted, but the vacancy is not published over the moderator's decision. | held |
none |
Ordering, retries and pending
-
Requests for a role are ordered by
occurredAt: an older one than the last accepted changes nothing (stale), an equal one is accepted (the last one to arrive wins). Send a role's requests one after another; different roles can go in parallel. A request that arrives while another one for the same role is still running waits up to a few seconds for it, then answers409 ROLE_BUSYwith aRetry-Afterheader. -
Taking over an existing per-posting vacancy
(
adopted) cannot happen while a feed sync is running. A request that has to wait for one longer than a few seconds answers409 ROLE_SYNC_IN_PROGRESSwith aRetry-Afterheader — but unlikeROLE_BUSYit was accepted:GETshows the new state withpending: true, and the sync applies it. Resending the same request (sameoccurredAt) is safe and applies it right away; sending an older state after it isstale. -
A request that is accepted but cannot be applied completely
(the posting is refused, your ATS is unreachable, no credit…)
answers the error, but the role keeps the state you asked for:
GETshowspending: true, and the platform retries it on every feed sync until it succeeds, for example once the posting is published again. Resending is allowed, never required. Requests refused before they are accepted change nothing:400,401,403 PARTNER_ROLES_NOT_ENABLEDorAPI_KEY_MISSING_SCOPE,409 ROLE_BUSYandROLE_APPLY_JOB_TAKEN, and429.PARTNER_ROLES_NOT_ENABLEDis answered before the request is validated.
Content stays in step with the posting
The vacancy's content is refreshed from the
applyJobId posting on every feed sync (every few
minutes), so an edit in your ATS needs no new
PUT. If that posting is closed or removed in your
ATS while the role is published, the vacancy keeps its last
content and stays live until you close the role or send another
applyJobId; the platform never switches to another
posting of jobIds by itself.
Use PUT to open and close a role's vacancy. The
lifecycle routes still accept
it, but the role does not follow them: the next
PUT brings the vacancy back to the role's state.
Switching to roles
-
Send one
PUTper active role. After that, a role's vacancy is addressed by itsroleId. -
A per-posting vacancy imported before the switch is either
adopted by a role (above) or, if its posting is listed by a
role (
applyJobIdorjobIds), archived on the next feed sync. A posting no role lists keeps its vacancy up to date until a role lists it or it leaves your ATS. -
GET /v1/partner/vacancies/external/:externalIdkeeps addressing per-posting vacancies by their posting id.
Errors
All in the usual error shape.
Retry means: resend the same request after the
Retry-After header's seconds (also in
metadata.retryAfterSeconds). Every other code is
final for that request: resending it gives the same answer
until you or your ATS change something.
| Status | Code | Retry | Meaning |
|---|---|---|---|
| 400 | ROLE_INVALID_INPUT |
no | metadata.field names the field (roleId, body, status, applyJobId, jobIds, occurredAt). |
| 403 | PARTNER_ROLES_NOT_ENABLED |
no | Roles are not switched on for your company. |
| 404 | ROLE_NOT_FOUND |
no | GET of a role your company never sent. |
| 409 | ROLE_BUSY |
yes | Another request for this role is still running. Nothing changed. |
| 409 | ROLE_SYNC_IN_PROGRESS |
yes* | Accepted, but taking over an existing vacancy had to wait for a running feed sync. The sync applies it; resending applies it at once. |
| 409 | ROLE_APPLY_JOB_TAKEN |
no | Another published role already uses this applyJobId (metadata.takenByRoleId). Nothing changed. |
| 422 | ROLE_APPLY_JOB_NOT_FOUND |
no* | Your ATS has no such posting, or the access you gave us cannot read it. |
| 422 | ROLE_APPLY_JOB_INTERNAL |
no* | An internal (employee-only) posting is never shown on the board. |
| 422 | ROLE_APPLY_JOB_NOT_OPEN |
no* | The posting does not take applications (metadata.humanStatus: draft, archived…). |
| 422 | ROLE_APPLY_JOB_UNMAPPABLE |
no* | The posting's data cannot make a vacancy (metadata.message says why, e.g. no title). |
| 422 | ROLE_APPLY_JOB_NO_APPLY_URL |
no* | The posting has no application page to send candidates to. |
| 422 | VACANCY_CONTAINS_BANNED_TERMS, VACANCY_MISSING_REQUIRED_CONTENT |
no* | The vacancy's own content checks (see Required content). |
| 402 | NO_JOB_POST_CREDITS |
no* | Publishing the vacancy needs a credit the company does not have. |
| 403 | COMPANY_BLOCKED |
no* | The company has been suspended and cannot publish. |
| 503 | ROLE_SOURCE_UNAVAILABLE |
yes* | Your ATS could not be read (metadata.reason), not a problem with the posting. |
* The state was accepted and stays pending: the
platform applies it on a later sync once the cause is gone, so
fixing the posting in your ATS (or sending another
applyJobId) is enough.
{
"statusCode": 422,
"message": "Job 8331292 is not open (archived)",
"code": "ROLE_APPLY_JOB_NOT_OPEN",
"metadata": { "applyJobId": "8331292", "humanStatus": "archived" },
"timestamp": "2026-11-02T13:00:01.000Z",
"path": "/v1/partner/roles/role-4711"
}
Controlling the hiring flow
Beyond reading vacancies and applications, the API can drive the hiring flow itself: change an application's ATS status, reject a candidate (with a reason), cancel a role proposal your company sent, and message a candidate directly. All three are WRITE-scope, thin gateways onto the same real commands the session-authenticated app itself uses — no business rule is reimplemented in the partner layer, so behavior here always matches what a recruiter sees in the normal UI.
Change status PATCH /v1/partner/applications/:id/status
Body: { "status": "INTERVIEW" }. Moves the
application to any ATS pipeline stage, in either direction:
NEW, REVIEWED, INTERVIEW,
HIRED. HIRED does not close the vacancy
or change its other applications. Returns the application,
re-fetched after the change, in the same shape as
GET .../applications/:id.
Deprecated: PHONE_SCREEN,
ON_SITE and OFFER were merged into
INTERVIEW. For one more release they are still
accepted here and stored as INTERVIEW; responses and
webhooks only ever carry INTERVIEW. Switch to
INTERVIEW now.
There is no "REJECTED" status — a rejected
candidate's application is ARCHIVED, and only
POST /v1/partner/applications/:id/reject gets it
there: rejecting always needs a reasonCode from
GET /v1/reject-reasons.
These statuses can never be set through this route, and the real
aggregate refuses each with a 400
INVALID_APPLICATION_STATUS_TRANSITION:
-
ARCHIVED— use the reject endpoint above. -
WITHDRAWN— candidate-only. Only the candidate can withdraw their own application; this route can't do it for them, and can't move an application back out of it either. -
PROPOSEDand the rest of the role-proposal family (PROPOSAL_DECLINED,PROPOSAL_REVOKED,PROPOSAL_EXPIRED) — managed exclusively by the role-proposal endpoints below, in either direction: neither settable as a new value, nor movable out of if the application is currently in one of them.
Permission model: gated on company membership
(APPLICATION_MANAGE), not on who authored the
vacancy — any active OWNER/RECRUITER can move any application
through the pipeline. If the API key's original
creator is no longer an active company member (left, or
was removed) since the key was created, this 403s with
code: INSUFFICIENT_VACANCY_PERMISSION — a key
outlives its creator's membership, but the action it performs
does not.
Cancel a role proposal POST /v1/partner/applications/:id/revoke-proposal
No body. Only valid while the application is a
pending role proposal — status:
"PROPOSED", source: "SOURCED", not yet
answered by the candidate. On success, the application moves to
PROPOSAL_REVOKED, a terminal state, and the response
is the re-fetched application. Calling it again, or on a plain
self-applied application, or on a proposal the candidate already
answered, returns 409 PROPOSAL_NOT_PENDING.
Permission model here is deliberately stricter
than status changes above: revoking is
author-only — the API key's original creator
must literally be the vacancy's author, not just any company
member with APPLICATION_MANAGE. An OWNER or
RECRUITER who can otherwise manage the vacancy fine still gets
403 NOT_APPLICATION_OWNER if they didn't author it
themselves. This mirrors the real aggregate's own rule for
role-proposal actions, not a restriction the partner API adds on
top.
Send & read messages POST /v1/partner/applications/:id/messages GET /v1/partner/applications/:id/messages
POST body: { "content": "..." }. Sends
a real chat message to the candidate — the exact same direct
chat a recruiter would see and reply in from the normal app UI,
not a side-channel. GET lists that same thread,
paginated newest-first, same page/pageSize
query params as every other list endpoint.
// GET .../messages response item shape
{
"id": "message-uuid",
"authorId": "user-uuid",
"isFromCompany": true,
"content": "Thanks for applying! Are you available this week?",
"sentAt": "2026-09-17T10:30:00.000Z",
"editedAt": null,
"deletedAt": null
}
Read this carefully before using it in production: every message is sent as the API key's original creator — the same actor-identity rule every write on this API already follows for vacancies and applications (see Authenticating REST calls). This is a real, permanent consequence, not an implementation detail: the candidate sees that person as the sender in their normal chat UI, indefinitely — even if that person later leaves the company, or the key outlives them. There is no abstract "message from the company" identity in this system.
An application with no messages yet returns an empty,
zero-total page from GET — not an error. That's the
expected, common case, not a sign anything is wrong.
There is currently no message.* webhook
for messages the candidate sends back to you — only the pull
GET above. Correlating an arbitrary incoming chat
message to "which partner company, which application" isn't a
simple mapping: chat messages carry only the two participants'
user ids, no vacancy/application link at all, and a candidate
can have more than one application at the same company, which
would need an explicit (and currently undefined) disambiguation
rule. If you need near-real-time incoming messages today, poll
GET .../messages.
Signature verification
Every webhook request carries four headers:
| Header | Value |
|---|---|
X-Webhook-Id |
The delivery's own id (idempotency key on your side). |
X-Webhook-Event |
The event name, e.g. vacancy.published —
matches the body's event field.
|
X-Webhook-Timestamp |
Unix seconds, as a plain decimal string. |
X-Webhook-Signature |
Hex-encoded HMAC-SHA256, described below. |
The signature is computed exactly as:
signature = hex( HMAC_SHA256(secret, "{X-Webhook-Timestamp}.{raw request body}") )
=== / a plain
string comparison. A naive comparison exits as soon as it
finds the first mismatched byte, which leaks — through response
timing — how many leading bytes of your guess were correct. Use a
constant-time comparison (crypto.timingSafeEqual in
Node, hmac.compare_digest in Python) every time,
exactly like this codebase's own delivery-side implementation
does.
const crypto = require('crypto');
const express = require('express');
const WEBHOOK_SECRET = process.env.JOBS_WEBHOOK_SECRET;
function verifyWebhookSignature(secret, timestampSeconds, rawBody, signature) {
const expected = crypto
.createHmac('sha256', secret)
.update(`${timestampSeconds}.${rawBody}`)
.digest('hex');
let expectedBuf, signatureBuf;
try {
expectedBuf = Buffer.from(expected, 'hex');
signatureBuf = Buffer.from(signature, 'hex');
} catch {
return false;
}
// Different lengths would make timingSafeEqual throw — treat that as "no match".
if (expectedBuf.length !== signatureBuf.length) return false;
return crypto.timingSafeEqual(expectedBuf, signatureBuf);
}
const app = express();
// express.raw() keeps req.body as a Buffer of the EXACT bytes received —
// do not use express.json() here, it would already have re-parsed the body
// by the time you see it, and rawBody would be lost.
app.post(
'/webhooks/jobs',
express.raw({ type: 'application/json' }),
(req, res) => {
const timestamp = req.header('X-Webhook-Timestamp');
const signature = req.header('X-Webhook-Signature');
const rawBody = req.body.toString('utf8');
if (!verifyWebhookSignature(WEBHOOK_SECRET, timestamp, rawBody, signature)) {
return res.status(401).send('invalid signature');
}
// Optional but recommended: reject a timestamp too far in the past to
// limit a stolen signature's replay window.
const skewSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
if (skewSeconds > 5 * 60) {
return res.status(401).send('stale timestamp');
}
const event = JSON.parse(rawBody);
console.log('received', event.event, event.id);
// ... handle event.event / event.data ...
res.status(200).end();
},
);
app.listen(3000);
import hashlib
import hmac
import os
import time
from flask import Flask, abort, request
WEBHOOK_SECRET = os.environ["JOBS_WEBHOOK_SECRET"]
app = Flask(__name__)
def verify_webhook_signature(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
message = f"{timestamp}.".encode("utf-8") + raw_body
expected = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
# hmac.compare_digest is constant-time — never use `==` here.
return hmac.compare_digest(expected, signature)
@app.route("/webhooks/jobs", methods=["POST"])
def webhook():
timestamp = request.headers.get("X-Webhook-Timestamp", "")
signature = request.headers.get("X-Webhook-Signature", "")
raw_body = request.get_data() # exact raw bytes, before any JSON parsing
if not verify_webhook_signature(WEBHOOK_SECRET, timestamp, raw_body, signature):
abort(401, "invalid signature")
# Optional but recommended: reject a timestamp too far in the past.
if abs(time.time() - float(timestamp)) > 5 * 60:
abort(401, "stale timestamp")
event = request.get_json()
print("received", event["event"], event["id"])
# ... handle event["event"] / event["data"] ...
return "", 200
Retries & auto-disable
A delivery that doesn't get a 2xx response (or times
out after 10s) is retried up to 5 attempts,
spanning roughly 24 hours:
| After attempt | Wait before next attempt |
|---|---|
| 1 | 1 minute |
| 2 | 15 minutes |
| 3 | 2 hours |
| 4 | 8 hours |
| 5 (final) | — marked EXHAUSTED, no further retries |
Respond 2xx as soon as you've durably queued the
event for your own processing — don't do slow work in the
handler itself, or you risk a timeout being treated as a failure
even though you did receive the event.
timestamp field (see
Webhook payload shapes) if your
integration cares about the order events actually happened in —
don't rely on arrival order.
A webhook subscription is automatically disabled after 20 distinct events in a row each exhaust all 5 attempts (a single event retried 5 times only ever counts once here). Any one delivery that succeeds resets this counter to zero. When a subscription auto-disables, the company OWNER is notified; re-enable it from Company Settings once your endpoint is healthy again.
Common error responses
Every error raised by this API surface (both REST and the
webhook-subscription management endpoints) shares this shape,
except the 400 Validation failed below, which names
the refused field instead of a code,
and the plain 404 below, which is Nest's own
default exception format:
401 — invalid or revoked API key
{
"statusCode": 401,
"message": "Invalid API key",
"code": "API_KEY_INVALID",
"metadata": {},
"timestamp": "2026-09-17T10:30:00.000Z",
"path": "/v1/partner/vacancies"
}
The status code, message, and shape are identical whether a key
was actually tried and rejected — unknown or revoked, every key of
a deleted company included
(code: "API_KEY_INVALID", shown above) — on purpose,
so a response never confirms a specific key string used to be
valid. A request with no
Authorization header at all (or one that isn't
Bearer <token>-shaped) gets the same
401 status but
code: "API_KEY_MISSING" instead — that distinction
is safe to expose, since it only tells you "you didn't send a
key," never anything about whether a specific key value you sent
was ever valid.
403 — key missing the required scope
{
"statusCode": 403,
"message": "This API key does not have the required scope",
"code": "API_KEY_MISSING_SCOPE",
"metadata": {
"apiKeyId": "ak_3f9c...",
"requiredScope": "WRITE"
},
"timestamp": "2026-09-17T10:30:00.000Z",
"path": "/v1/partner/vacancies"
}
400 — a field the platform refuses
A field whose value has the wrong shape, such as a
techStack that is not an array of strings, more
than 100 tags or a tag over 200 characters, or a
title over 80 characters
(field: "VacancyTitle"), is refused with the
name of the rule that failed in field and the
details in errors:
{
"statusCode": 400,
"message": "Validation failed",
"errors": [
{
"expected": "array",
"code": "invalid_type",
"path": [],
"message": "Invalid input: expected array, received string"
}
],
"field": "VacancyTechStack",
"timestamp": "2026-10-18T10:30:00.000Z",
"path": "/v1/partner/vacancies/8a2e5f10-9c3b-4d1e-a7f2-0987654321cd"
}
404 — cross-company isolation
Every :id-taking partner route —
GET/PATCH /v1/partner/vacancies/:id,
GET /v1/partner/applications/:id — returns a plain
404 — never a 403 — both when the id
doesn't exist at all AND when it belongs to a different company.
A 403 would confirm the id exists for someone else;
this never does.
{
"statusCode": 404,
"message": "Vacancy not found",
"error": "Not Found"
}
429 — rate limit exceeded
See Rate limits above for the full shape.
409 / 503 with Retry-After — try again shortly
ROLE_BUSY and ROLE_SYNC_IN_PROGRESS
(409) and ROLE_SOURCE_UNAVAILABLE (503) on
/v1/partner/roles are temporary: resend the same
request after the Retry-After header's seconds. See
Roles → Errors for every role code.
FAQ & troubleshooting
My signature verification fails intermittently — why?
The most common cause is clock skew, not a broken signature. The
signature itself (Signature
verification) doesn't expire — it's a hash of the timestamp
and body, valid however old the delivery is. The optional
"reject a stale timestamp" check shown in the sample code
(skewSeconds > 5 * 60) is your own
replay-window guard, and it compares
X-Webhook-Timestamp against your server's clock. If
your server's clock has drifted, that check can reject a
genuinely valid, on-time delivery. Make sure the machine
verifying signatures is NTP-synced, and double-check you're
comparing against the exact raw request body bytes (see the
callout in Signature verification) —
a re-serialized body is the other common cause of a mismatch
that looks like a signature problem but isn't.
How do I test webhooks against my local machine?
Your webhook URL has to be reachable from the public internet,
so a plain localhost URL won't receive anything.
During development, point the subscription at a public tunnel
into your local machine (a generic reverse-tunnel tool such as
ngrok, or your own equivalent) instead. Once a subscription
exists, use the "test" button in Company Settings to send a
synthetic delivery through the exact same path real events use
— see the callout under
Retries & auto-disable — so you can
confirm your handler and signature verification work before any
real event has to reach it.
What does "auto-disabled" actually mean, and how do I recover?
Covered fully under Retries &
auto-disable: a subscription disables itself after 20
distinct events in a row each exhaust all 5 retry attempts. In
practice this means your endpoint was down or erroring for a
sustained period and stopped receiving new deliveries entirely
rather than continuing to fail silently. To recover: fix
whatever was wrong with your endpoint, then re-enable the
subscription from Company Settings — it does not re-enable
itself once your endpoint recovers, and no events are
backfilled for the time it was disabled. There is currently no
way to list or replay exactly which events you missed while
disabled, so reconcile by re-pulling current state via
GET /v1/partner/vacancies/applications
(see Quickstart) rather than trying to
reconstruct the gap from webhook history.
A role answers pending: true. Do I need to resend it?
No. pending means the role's last accepted state
is not fully applied yet, typically because the
applyJobId posting was refused (a
422) or your ATS was unreachable (a
503). The platform retries it on every feed sync,
so fixing the posting in your ATS is enough; or send the role
again with another applyJobId. See
Roles.
I rotated infrastructure and my webhook URL changed. What do I update?
Update the subscription's URL from Company Settings, the same place you created it. Use the "test" button afterward to confirm the new URL is reachable and your signature verification still passes before relying on it for real traffic — test deliveries never affect the auto-disable counter, so this is safe to do even on a subscription that was previously disabled.
Generated content on this page (event catalog table) is produced by
npm run export:partner-openapi straight from
src/contexts/partner-integrations — see
docs/plans/partner-api-webhooks.md in the backend repo
for the full design history.