Versions and compatibility

The URL selects the major API version: https://api.join.com/v3. The Join-Version header selects a dated revision within v3.

Join-Version: 2026-11-17

Use the YYYY-MM-DD format. These guides and the reference describe 2026-11-17. Requests without the header use your company's default revision: 2026-11-01 for companies that existed before 2026-11-17 was released, and 2026-11-17 for companies created since. Send the header on every request so your integration keeps a fixed revision.

Revisions

RevisionWhat it adds or changes
2026-11-17Interviews, interview templates, scorecard templates and users. Four more application document types. Scorecards link to their interview. Hiring-team members and the contact person are returned as users and can be assigned by user ID. Breaking: the hiring-team role field is renamed jobRole, and hiring-team users and the contact person have a new shape. See the changelog.
2026-11-01First v3 revision: jobs, job-authoring lookups, applications, candidates, candidate notes, scorecards and locations. The default for companies that existed before 2026-11-17.

Updating an integration

Before changing a pinned revision, compare its request fields, response fields and behavior with the version you use. Exercise your integration against the supported target revision.

Ignore response fields your integration does not use and handle unfamiliar error codes through their HTTP status.

Deprecation signals

Deprecated revisions can return these headers:

HeaderMeaning
DeprecationDeprecation timestamp, expressed as Unix seconds prefixed with @
SunsetHTTP date communicating the retirement date
Link with rel="sunset"Information about migration or retirement

Monitor these headers and follow the linked notice. For a v2 integration, use the migration guide.