Create an application

post

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

Creates an application on a job. Provide jobId and exactly one of candidateId or candidate.

Choosing a candidate

Use candidateId for a candidate already in your company.
Use candidate to provide inline details. If the email matches an existing candidate, JOIN reuses that candidate, applies new tags and ignores the other supplied profile fields.

Initial state and documents

New applications start as ACTIVE in the job’s first review stage. JOIN sets their source. When documents is omitted for an existing candidate, their profile CV and cover letter are carried forward automatically.

Follow the application workflow, then move the application to a stage.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Supply exactly one of candidateId and candidate. Supplying both, or neither, is rejected with validation_error.

jobId

integer

required

ID of the job to apply to. The job must not be archived

externalId

string

length between 1 and 50

\S

Your own reference for this application. Limited to 50 characters; a longer value is refused with validation_error. Must contain at least one non-whitespace character.

candidateId

integer

ID of an existing candidate in your company. Either supply this field or candidate, not both

candidate

object

A candidate described inline. When the email is already known to your company, that candidate is reused rather than the request being refused. Either supply this field or candidateId, not both

documents

array of objects

Documents for this application. When omitted, an existing candidate’s profile CV and cover letter are carried forward; no other document type is

documents

Headers

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 application is created

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

422The request body failed validation, or the application could not be created: the job is archived (job_archived), the candidate already applied to it (application_already_exists), or the candidate is blocked (candidate_blocked).

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.