Update a job

patch

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

Updates a published job’s details, status, or both.

Updating fields

Omitted fields stay unchanged. Send null only for fields documented as nullable.
Provided work locations, compensation, application forms and hiring-team arrays replace their previous values in full. Read each field’s rules before sending a partial object.
Employment terms have their own field-level rules; see employmentTerms.

Saving changes and handling failures

Job fields, hiring-team assignments and status are saved together. If a status transition is refused, those changes stay unapplied. Custom screening questions are updated separately before that save and can remain changed if a later step fails. Read the job, including its application form, before deciding what to retry. If updates overlap, the last write determines the stored values.

See Responses, errors and retries for handling an uncertain write outcome.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

integer

required

ID of the job

Body Params

Updates a job’s details, status, or both. Job fields, hiring-team assignments and status are saved together. Custom screening questions are updated separately and can remain changed if a later step fails. Omitted fields stay unchanged. Read the individual field rules for replacement, merging and clearing. If updates overlap, the last write determines the stored values.

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; HTML markup does not count toward the limit. 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 of the job ad. Omit to keep the current language.

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

Contract type ID from List contract types. This determines the job’s employment type.

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

Documents and custom questions for the application form. Omit the object to keep the current form. Supplying it replaces the form in full: omitted documents resets to a required CV, and omitted screeningQuestions removes the custom questions.

hiringTeam

array of objects | null

Company users to assign to this job. Omit to keep the current assignments. A supplied array replaces the assignments; null clears them. System Admins retain access through their company role.

hiringTeam

contactPersonEmail

string | null

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

externalId

string | null

Your own reference for the job. Multiple jobs can share this value; the externalId filter returns all matches. Shown in the product as Internal Job ID. Sending null clears it.

Headers

Accept-Language

string

Preferred language for translated display names. Supported languages are en, de, fr, es, it and nl. Regional variants use their main language (de-CH → de); a list uses the first supported language. If the header is omitted or no language matches, the response uses English. Content-Language identifies the language used. Identifiers, slugs and enum values stay stable. Use languageCode to filter jobs by the language of the ad.

Join-Version

string

Selects a dated API revision in YYYY-MM-DD format, such as 2026-11-01. Pin this header to choose the revision explicitly; omitting it uses the server’s default. An unsupported value returns 400 unsupported_api_version. See Versions and compatibility.

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. For a write, the outcome may be uncertain: read the affected record before retrying. See Responses, errors and retries.