Send JSON request bodies with Content-Type: application/json. Field names use camelCase. JOIN resource IDs are integers; your externalId references are strings. Timestamps use ISO 8601, country codes use ISO 3166-1 alpha-2 and currencies use ISO 4217.
Successful responses
Single-resource JSON responses wrap the record in data. Lists wrap an array in data; only paginated lists add nextCursor. A successful deletion returns 204 No Content with no JSON body. Do not try to parse a 204 as JSON.
| Operation | Success status |
|---|---|
| Read or list | 200 |
| Create | 201 |
| Update a resource or move an application | 200 |
| Delete | 204 |
An omitted update field stays unchanged. Send null only where the field accepts it. Nested values often replace the stored value in full, but field-specific rules take precedence; see Update a job and Update a location.
Application document and screening-file download URLs expire after one hour. Read the record again for a fresh URL. Download URLs are credentials for the file; do not forward your JOIN API token to their storage host.
Error details
Branch on error.code, not the human-readable message. Field-level errors include details; business-rule errors may omit it.
{
"error": {
"code": "validation_error",
"message": "The query parameters contain invalid values.",
"details": [
{ "field": "limit", "in": "query", "message": "must be <= 50" }
]
}
}| Status | Typical codes | What to do |
|---|---|---|
400 | malformed_json, cursor_invalid, filter_invalid, unsupported_api_version | Correct the request; restart pagination for an invalid cursor |
401 | authentication_required, token_invalid | Check your credential and company access |
404 | job_not_found, candidate_not_found, application_not_found, location_not_found, note_not_found | Check the resource ID and company scope |
422 | validation_error or an endpoint-specific business-rule code | Correct the fields or satisfy the stated business rule |
429 | rate_limit_exceeded | Wait for Retry-After before trying again |
500 | unknown | Treat the outcome as uncertain; follow the retry guidance below |
Each endpoint lists its own business errors. Examples include application_already_exists, stage_not_in_pipeline, note_limit_reached and location_is_default. A 404 does not disclose whether a resource belongs to another company. Draft jobs are also unreadable until published.
Retry without duplicating changes
For reads, retry transient failures with bounded exponential backoff; respect Retry-After when provided. Stop and investigate persistent failures.
For writes, a timeout or server error can occur after a change has been saved. Read the affected records and reconcile before retrying. Use external references to associate records with your system; they do not make retries safe. Multiple jobs can share the same externalId.
Job updates save job fields, hiring-team assignments and status together. Custom screening questions are updated separately and can remain changed if a later step fails; read the job and its application form before retrying. Application stage moves can trigger email automation. Choose a retry strategy for each operation based on its effects.