Update a job

patch

https://api.join.com/v3/jobs/{id}

Updates a job’s attributes, its status, or both. A provided nested object or array replaces its value in full; an omitted field is unchanged; an explicit null clears an optional field. When one request changes both, attributes apply first and the transition second. Concurrent updates are last-write-wins — there is no ETag, no If-Match and no 412.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

integer

required

Id of the job

Query Params

language

string

enum

Defaults to en

Translates the display names in the response to this ISO 639-1 language. JOIN supports nl, en, fr, de, it and es and no others, so any other value is rejected with 400 unsupported_language rather than answered in English. Identifiers, slugs, enum values and error codes are never translated. Not to be confused with the languageCode job filter, which selects the language an ad is written in.

Allowed:

Body Params

Partial update of a job’s attributes, its status, or both — attributes apply first and the transition second, so a refused transition does not discard the attribute changes. A provided nested object or array replaces its value in full, so send the complete value; an omitted field is unchanged. Concurrent updates are last-write-wins.

status

string

enum

Target status. Any direction among the three is allowed; a refusal is always validation_error or job_limit_reached

Allowed:

title

string

length between 3 and 100

Job title, 3–100 characters

description

string

Job description as HTML. The visible text must be 200–10,000 characters; markup does not count toward that, so the bound is enforced on write rather than by this schema. Allowed tags: <p>, <br>, <strong>, <em>, <ul>, <ol>, <li>, <h2> and <h3>, without attributes. Any other tag, links included, is removed and its text kept; scripts and embedded content are removed entirely.

languageCode

string

enum

The language the ad is written in. Defaults to your company’s

Allowed:

priority

string

enum

How urgently the role needs filling. It stays unchanged if this field is omitted

Allowed:

openings

integer

1 to 99

Positions to fill

workLocation

Where the job is performed. Each workplace model carries exactly the fields it needs and refuses the others: locationId for ONSITE and HYBRID, hybridSchedule optionally for HYBRID, and then countryCode for REMOTE + COUNTRY or remoteRegionId for REMOTE + REGION. REMOTE + ANYWHERE carries none of them. Replaced in full on update, so changing the model clears what the previous one carried.

contractTypeId

integer

The contract type; see GET /contract-types. employmentType follows from it and cannot be set

employmentTerms

object | null

Contract terms. An omitted term stays as it is and a null term is cleared; null for the whole object clears every term. Each value is validated against the contract type’s bounds, and changing contractTypeId drops the stored terms the new contract type does not allow.

compensation

object | null

What the job pays. Replaced in full when sent; omitted, it stays as it is. null removes the salary and keeps it HIDDEN.

applicationForm

object

What the candidate is asked to provide. Replaced in full on write. Omitted on create, the form keeps CV required and carries no custom questions.

hiringTeam

array of objects | null

Who to invite. Omitted, nobody is invited. System Admins reach the job regardless. Sending null clears it.

hiringTeam

contactPersonEmail

string | null

Company member shown on the public ad. Sending null clears it.

externalId

string | null

Your own reference for the job. Not unique — the externalId filter returns every match. Shown in the product as Internal Job ID. Sending null clears it.

Headers

Join-Version

string

Selects the dated API version the request runs against, named after its release day as YYYY-MM-DD, e.g. 2026-11-01. Omit to use the current default version (2026-11-01). A value that is not a supported version is rejected with 400 unsupported_api_version.

Responses

200The updated job

400The request could not be processed: an unsupported API version, or an unparseable JSON body.

401Authentication failed. Either the Authorization: Bearer header is missing (authentication_required), or the presented token is malformed, unknown, revoked, or belongs to a company that no longer has API access (token_invalid).

404No job with this id exists within the caller’s company. A job belonging to another company is reported the same way.

429The token exceeded its sustained (600/60s) or burst (100/10s) request quota. Retry after the number of seconds in Retry-After.

500An unexpected error occurred on JOIN’s side. The request may be retried.