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-17Use 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
| Revision | What it adds or changes |
|---|---|
2026-11-17 | Interviews, 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-01 | First 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:
| Header | Meaning |
|---|---|
Deprecation | Deprecation timestamp, expressed as Unix seconds prefixed with @ |
Sunset | HTTP 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.