Create a job

post

https://api.join.com/v3/jobs

Creates and publishes a job. Provide its title, description, work location and contract type.

Publishing effects

ONLINE posts the job to job boards.
OFFLINE keeps it internal for direct sourcing and internal hiring, without multiposting.
Both statuses run publish validation and count toward your company’s active-job limit.

Choose IDs from the Locations, Contract types, Pipeline templates and Remote regions endpoints as needed. Employment type follows from the contract type.

See the job workflow for choosing these values and Update a job for later changes.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Creates and publishes a job. ONLINE posts it to job boards; OFFLINE keeps it internal for direct sourcing, without multiposting. Both run the same publish validation and both count toward the active-job limit.

status

string

enum

Defaults to ONLINE

Status a job is created with. ARCHIVED is not valid on create — archive an existing job with PATCH. Both values run the same publish validation and both count toward the active-job limit.

Allowed:

title

string

required

length between 3 and 100

Job title, 3–100 characters

description

string

required

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 the ad is written in. Defaults to your company’s

Allowed:

priority

string

enum

Defaults to NORMAL

How urgently the role needs filling

Allowed:

openings

integer

1 to 99

Defaults to 1

Positions to fill. Omitted, 1

workLocation

required

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

required

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

employmentTerms

object

Contract terms, each optional. An omitted or null term stays empty: JOIN applies no default. Each value is validated against the contract type’s bounds.

compensation

object

What the job pays. Omit the whole object for no salary, which keeps the salary 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.

pipelineTemplateId

integer

The pipeline template the job’s stages are created from; see GET /pipeline-templates. Defaults to your company’s default

hiringTeam

array of objects

Who to invite. Omitted, nobody is invited. System Admins reach the job regardless

hiringTeam

contactPersonEmail

string

Company member shown on the public ad

externalId

string

length ≤ 250

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

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

201The job is created and published

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).

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.