Fintech Careers

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.

  1. Generate an API key. An OWNER creates a scoped key from Company Settings in the app. See Getting an API key.
  2. Make your first authenticated REST call. Send the raw key as a bearer token, e.g. GET /v1/partner/vacancies. See Authenticating REST calls.
  3. Subscribe a webhook URL to an event. Register an endpoint and pick which events from the event catalog it should receive.
  4. 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.
  5. 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…

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; its id is ours. READ scope.
  • POST /v1/partner/vacancies/external/:externalId/publish, /unpublish, /close, /restore — exactly the actions above, with the same rules, answers and errors. WRITE scope.
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 ARCHIVED vacancy each take one credit and start a new period. With no credit left (and no unlimited plan) they answer 402 NO_JOB_POST_CREDITS and 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, unless workFormats includes REMOTE;
  • an employmentType;
  • a level;
  • a salary: from, to or both, with its currency. Set isSalaryPublic: false to 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, with metadata.missingFields listing what to fill in first (see Required content: description, countryId, employmentType, level, salary), or VACANCY_CONTAINS_BANNED_TERMS when the title or description contains a term the platform does not allow. A PATCH of a live vacancy answers the same two: one that would clear its salary, employmentType or level, or put a banned term in.
  • 403 — API_KEY_MISSING_SCOPE (the key has no WRITE), INSUFFICIENT_VACANCY_PERMISSION (the key's creator is no longer a company member allowed to manage vacancies), or COMPANY_BLOCKED on 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. WRITE scope.
  • GET /v1/partner/roles/:roleId — read it back, with its vacancy. READ scope.
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 answers 409 ROLE_BUSY with a Retry-After header.
  • 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 answers 409 ROLE_SYNC_IN_PROGRESS with a Retry-After header — but unlike ROLE_BUSY it was accepted: GET shows the new state with pending: true, and the sync applies it. Resending the same request (same occurredAt) is safe and applies it right away; sending an older state after it is stale.
  • 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: GET shows pending: 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_ENABLED or API_KEY_MISSING_SCOPE, 409 ROLE_BUSY and ROLE_APPLY_JOB_TAKEN, and 429. PARTNER_ROLES_NOT_ENABLED is 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 PUT per active role. After that, a role's vacancy is addressed by its roleId.
  • A per-posting vacancy imported before the switch is either adopted by a role (above) or, if its posting is listed by a role (applyJobId or jobIds), 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/:externalId keeps 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.
  • PROPOSED and 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}") )
Use the exact raw request body bytes — the ones actually received on the wire, before any JSON parsing/re-serialization. Re-serializing and re-stringifying the parsed JSON before hashing will very often produce a byte-for-byte different string (key order, whitespace) and the signature won't match even though the payload is "the same" logically.
Never compare signatures with === / 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);

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.

Delivery order is not guaranteed. A retried delivery can arrive interleaved with newer events for the same entity, and nothing here promises deliveries land in the order their source events occurred. Sort by the envelope's own 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.

The settings UI's "test" button sends a synthetic delivery through this exact same path, so you can verify your endpoint end to end — but test deliveries never count toward the 20-failure auto-disable counter, so testing a currently-broken endpoint can't accidentally disable it for real traffic.

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.