A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Workable API is how an app or AI agent works with a Workable account: listing open jobs, reading and creating candidates, moving a candidate to the next pipeline stage, or posting a comment or rating on an application. Access is granted through an access token that carries a set of scopes, like reading candidates or writing them, and a call can only reach what the token's scopes and the account behind it permit. A subscription lets Workable push an event to a registered endpoint when a candidate is created or moved, so an integration is told about activity rather than polling for it.
How an app or AI agent connects to Workable determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Workable tools to agents, and each is governed by the token behind it and the scopes that token carries.
The REST API returns JSON and is reached under each account's own subdomain at https://
A first-party hosted Model Context Protocol server at https://mcp.workable.com/mcp exposes Workable tools to AI assistants across the hiring and HR platform, covering jobs and candidates, offers, requisitions, employees, time off, time tracking, and performance reviews. It authenticates with OAuth 2.0 and supports dynamic client registration and discovery. An agent first calls get_accounts to list accessible accounts, then uses the returned subdomain for later calls. Transport is stateless streamable HTTP in JSON mode.
A subscription registers a target URL for one event type by POSTing to /subscriptions. Workable then pushes a notification to that URL when the event fires, and the subscription can be filtered to a single job or stage. Supported recruiting events include candidate_created and candidate_moved. A target URL must be unique, and re-registering one returns a 409 conflict.
An access token tied to a single Workable account, created in the account's Integrations settings with a chosen set of scopes and shown only once. It is the simplest way to call the API for one account, and it carries the lowest rate limit, 10 requests per 10 seconds. Revoking it invalidates every integration using it.
An OAuth 2.0 access token obtained on a user's behalf, used by the first-party MCP server and by apps connecting an account through an authorization flow. It allows 50 requests per 10 seconds, a higher ceiling than an account token, and is sent as a Bearer token like any other.
A partner token is for integrations that operate across many customer accounts, such as a third-party tool building on top of Workable. It allows 50 requests per 10 seconds, and the account it acts on is selected per call by the subdomain in the request URL.
The Workable API is split into areas an agent can act on, like jobs, candidates, pipeline stages, and the people on the hiring team. Each area has its own methods, and writes here move candidates through the pipeline, post comments and ratings, or disqualify an application.
Methods for listing and reading jobs and their pipeline stages.
Methods for reading, creating, and updating candidates.
Methods that move a candidate through the pipeline or act on an application.
Methods for reading the hiring team and external recruiters.
Methods for reading activity streams and scheduled events.
Methods for registering and removing event subscriptions.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
JobsMethods for listing and reading jobs and their pipeline stages.4 | ||||||
| GET | /spi/v3/jobs | List the account's jobs, paged with a limit parameter. | read | r_jobs | Current | |
Read-only. Accessible with all token types. Acts onjob Permission (capability) r_jobsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /spi/v3/jobs/:shortcode | Retrieve the details of a single job by its shortcode. | read | r_jobs | Current | |
Read-only. Accessible with all token types. Acts onjob Permission (capability) r_jobsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /spi/v3/jobs/:shortcode/stages | List the pipeline stages configured for a job. | read | r_jobs | Current | |
Read-only; the stages of one job. Accessible with all token types. Acts onstage Permission (capability) r_jobsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /spi/v3/stages | List the account's recruitment pipeline stages. | read | r_jobs | Current | |
Read-only; the account-wide stage list. Accessible with all token types. Acts onstage Permission (capability) r_jobsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CandidatesMethods for reading, creating, and updating candidates.5 | ||||||
| GET | /spi/v3/candidates | List candidates, paged with a limit parameter (default 50, max 100). | read | r_candidates | Current | |
Read-only; returns a reduced payload per candidate. Accessible with all token types. Acts oncandidate Permission (capability) r_candidatesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /spi/v3/candidates/:id | Retrieve the full details of a single candidate. | read | r_candidates | Current | |
Read-only; the fuller fields not returned by the list. Accessible with all token types. Acts oncandidate Permission (capability) r_candidatesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /spi/v3/jobs/:shortcode/candidates | Create a candidate on a job; set sourced to false to treat it as an applicant. | write | w_candidates | Current | |
A core write; uploaded by default, set sourced to false for an applied candidate. Accessible with all token types. Acts oncandidate Permission (capability) w_candidatesVersionAvailable since the API’s base version Webhook event candidate_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /spi/v3/candidates/:id | Partially update a candidate's fields. | write | w_candidates | Current | |
A core write; only the supplied fields change. Accessible with all token types. Acts oncandidate Permission (capability) w_candidatesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /spi/v3/talent_pool/candidates | Create a candidate in the account's talent pool rather than on a job. | write | w_candidates | Current | |
A write; adds a candidate to the talent pool. Acts oncandidate Permission (capability) w_candidatesVersionAvailable since the API’s base version Webhook event candidate_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Candidate actionsMethods that move a candidate through the pipeline or act on an application.4 | ||||||
| POST | /spi/v3/candidates/:id/move | Move a candidate to another pipeline stage. | write | w_candidates | Current | |
Advances or sends back a candidate in the pipeline. Accessible with all token types. Acts oncandidate Permission (capability) w_candidatesVersionAvailable since the API’s base version Webhook event candidate_movedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /spi/v3/candidates/:id/disqualify | Disqualify a candidate, optionally with a reason and notes. | write | w_candidates | Current | |
Requires member_id; can be reverted with the revert method. Accessible with all token types. Acts oncandidate Permission (capability) w_candidatesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /spi/v3/candidates/:id/comments | Add a comment to a candidate's timeline. | write | w_candidates | Current | |
Requires a member_id and a comment body. The w_comments scope also grants this. Acts oncomment Permission (capability) w_candidatesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /spi/v3/candidates/:id/ratings | Create a rating or evaluation on a candidate. | write | w_candidates | Current | |
Records a score or evaluation on the application. Accessible with all token types. Acts onrating Permission (capability) w_candidatesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
People & teamMethods for reading the hiring team and external recruiters.2 | ||||||
| GET | /spi/v3/members | List the account's members (the hiring team). | read | r_jobs | Current | |
Read-only. Accessible with account tokens and user tokens. Acts onmember Permission (capability) r_jobsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /spi/v3/recruiters | List the account's external recruiters. | read | r_jobs | Current | |
Read-only; the external recruiting agencies on the account. Acts onrecruiter Permission (capability) r_jobsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Activity & eventsMethods for reading activity streams and scheduled events.4 | ||||||
| GET | /spi/v3/events | List scheduled events such as calls, interviews, and meetings. | read | r_jobs | Current | |
Read-only; includes timing, members, and RSVP status. Acts onevent Permission (capability) r_jobsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /spi/v3/events/:id | Retrieve a single scheduled event by its id. | read | r_jobs | Current | |
Read-only. Acts onevent Permission (capability) r_jobsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /spi/v3/jobs/:shortcode/activities | Read the activity stream for a job. | read | r_jobs | Current | |
Read-only; the actions recorded against a job. Acts onactivity Permission (capability) r_jobsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /spi/v3/candidates/:id/activities | Read the activity stream for a candidate, like applications, comments, and stage moves. | read | r_candidates | Current | |
Read-only; the timeline of a single candidate. Acts onactivity Permission (capability) r_candidatesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Subscriptions (webhooks)Methods for registering and removing event subscriptions.3 | ||||||
| POST | /spi/v3/subscriptions | Subscribe to an event by registering a target URL for one event type. | write | r_candidates | Current | |
Needs r_candidates (or r_employees for HR events); a duplicate target URL returns 409. Accessible with all token types. Acts onsubscription Permission (capability) r_candidatesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /spi/v3/subscriptions | List the account's active event subscriptions. | read | r_candidates | Current | |
Read-only; the registered webhook subscriptions. Acts onsubscription Permission (capability) r_candidatesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /spi/v3/subscriptions/:id | Unsubscribe from an event by deleting its subscription. | write | r_candidates | Current | |
Removes where the event was being pushed. Acts onsubscription Permission (capability) r_candidatesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Workable can notify an app when something happens in an account, like a candidate being created or moved to another stage. A subscription registers a target URL for one event type, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
candidate_created | A new candidate was created in the account, whether uploaded through the API or applied through a form. A subscription can be narrowed to a single job or stage. | /spi/v3/jobs/:shortcode/candidates/spi/v3/talent_pool/candidates |
candidate_moved | A candidate was moved to another pipeline stage. A subscription can be filtered to a target stage, like 'hired', to be told only about moves into that stage. | /spi/v3/candidates/:id/move |
Workable limits how fast an app can call, measured as a number of requests within a rolling ten-second window, and the ceiling depends on the kind of token making the call.
Workable meters requests by a rolling ten-second window, and the ceiling depends on the token. An account token allows 10 requests per 10 seconds, while an OAuth 2.0 token and a partner token each allow 50 requests per 10 seconds. Every response carries X-Rate-Limit-Limit, X-Rate-Limit-Remaining, and X-Rate-Limit-Reset headers so an integration can pace itself. Going over the limit returns HTTP 429.
A list endpoint pages with a limit parameter, which defaults to 50 results and cannot exceed 100 per page. The response carries a paging object whose next field holds the URL of the following page, and an integration follows that link until it is absent. Results are not offset-based; the next link is the supported way to walk a collection.
A page returns at most 100 records, the maximum value of limit. The newest fields for a candidate are returned only by the single-candidate endpoint; the candidates list returns a reduced payload to keep pages small.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | unauthorized | No valid access token was provided, or the token has been revoked. | Send a valid Bearer access token in the Authorization header, and generate a new token if the old one was revoked. |
| 403 | forbidden | The token is valid but lacks the scope the method needs, or the account role does not permit the action. | Recreate the token with the required scope, like r_candidates or w_candidates, and confirm the account role allows it. |
| 404 | not_found | The requested job, candidate, or other record does not exist or is not visible to this token's account. | Verify the shortcode or id and confirm the record belongs to the account the token is tied to. |
| 409 | conflict | A conflicting request, such as registering a subscription with a target URL that is already in use. | Use a unique target URL per subscription, or unsubscribe the existing one before re-registering. |
| 429 | too_many_requests | The token exceeded its allowed number of requests within the rolling ten-second window. | Read the X-Rate-Limit-Remaining and X-Rate-Limit-Reset headers, then back off and retry after the window resets. |
Workable versions its recruiting API by a single path segment, currently v3, and ships dated changes through its developer documentation rather than minting a new version for each one.
The current version of Workable's recruiting API, reached under each account's subdomain at the /spi/v3 path. It changed several response shapes from v2 and is the version to build against; v1 and v2 are deprecated but continue to function.
The first two versions of the recruiting API. Both are deprecated but continue to function for existing integrations; new work should target v3.
Build against v3; the older v1 and v2 APIs are deprecated but still function.
Workable v3 changes ↗Bollard AI sits between a team's AI agents and Workable. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.