Your first API request

Request up to one job to verify your connection without changing recruiting data. You need a company API token; see Authentication and access.

1. List jobs

curl --fail-with-body "https://api.join.com/v3/jobs?limit=1" \
  -H "Authorization: Bearer $JOIN_API_TOKEN" \
  -H "Join-Version: 2026-11-01"

This request explicitly selects revision 2026-11-01. It lists published jobs, including internal jobs; drafts are excluded. See List jobs.

2. Read the result

A successful request returns 200 OK. The JSON body contains a data array of job records and nextCursor. If your company has no matching jobs, this is a complete successful response:

{
  "data": [],
  "nextCursor": null
}

When a record is present, save its id to retrieve it later. The endpoint reference contains complete populated response examples. A non-null nextCursor means another page is available; follow Pagination, filtering and sorting.

3. Handle a failure

401: check the token and access using Authentication and access.
400 unsupported_api_version: check the Join-Version header and the revision available to your environment.
429: wait for the number of seconds in Retry-After.

Once the request succeeds, your connection is ready. Continue with Create and manage jobs or Create applications and move them through stages.