> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workable

> Access Workable recruiting data - jobs, candidates, and pipeline stages - and add comments or move candidates

## At a glance

* **Availability**: Experimental ([how to enable](/cloud/integrations)).
* **Auth**: API key.
* **Connection**: The key from `WORKABLE_API_TOKEN` is sent as the `Bearer` prefixed `Authorization` header.
* **Docs**: [https://workable.readme.io/reference/generate-an-access-token](https://workable.readme.io/reference/generate-an-access-token)

## Credentials

Set these per environment. See [Connect an integration](/cloud/integrations).

| Variable             | Required | Description                                                                                                                                                                |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WORKABLE_API_TOKEN` | Yes      | Workable API access token, generated under Settings → Integrations → Apps → Generate new token [Docs](https://workable.readme.io/reference/generate-an-access-token).      |
| `WORKABLE_SUBDOMAIN` | Yes      | Your Workable account subdomain (\{subdomain}.workable.com), shown in your company profile settings [Docs](https://workable.readme.io/reference/generate-an-access-token). |

## Setup

1. **Get a Workable account**: Sign up at [https://www.workable.com](https://www.workable.com) - a 15-day free trial account is enough for testing the API against your own data.
2. **Generate an access token**: In Workable, open the top-right dropdown menu → Integrations, then click 'Generate new token'. Select the scopes you need (r\_jobs and r\_candidates for reads; w\_candidates for comments and stage moves). The token is shown only once - copy it immediately.
3. **Find your subdomain**: Your account subdomain is the \{subdomain} part of \{subdomain}.workable.com and is shown on your company profile settings page.
4. **Store the credentials**: Add WORKABLE\_API\_TOKEN=\<your token> and WORKABLE\_SUBDOMAIN=\<your subdomain> to your .env file. Requests go to https\://\{subdomain}.workable.com/spi/v3 with an Authorization: Bearer header.

* Tokens are scoped at generation time - writes need w\_candidates (comments also accept w\_comments)
* Revoking a token breaks every script using it; generate a new one and update all consumers
* List endpoints paginate via the paging.next URL and since\_id cursors (max 100 per page)

Provider API reference: [https://workable.readme.io/reference](https://workable.readme.io/reference)

## Tools

| Tool                     | Access | Description                                                                                   |
| ------------------------ | ------ | --------------------------------------------------------------------------------------------- |
| List Jobs                | Read   | List jobs in the Workable account with optional state filtering                               |
| Get Job                  | Read   | Get the full details of a job by its shortcode                                                |
| List Candidates          | Read   | List candidates account-wide or for a specific job (filter by job shortcode, stage, or email) |
| Get Candidate            | Read   | Get the full profile of a candidate by ID, including stage, answers, and attachments          |
| List Members             | Read   | List account members to find the member IDs required by the comment and move-candidate tools  |
| List Stages              | Read   | List the recruitment pipeline stages to find stage slugs for candidate filtering and moves    |
| Create Candidate         | Write  | Add a candidate to a job, either as sourced or as having applied                              |
| Create Candidate Comment | Write  | Post a comment on a candidate's timeline on behalf of a team member                           |
| Move Candidate           | Write  | Move a candidate to another pipeline stage on behalf of a team member                         |

## Example prompts

* List my published jobs in Workable and summarize how many candidates are in each pipeline.
* Show me the candidates currently in the interview stage for a job I specify and summarize their profiles.
* Look up a candidate I specify in Workable and add a comment to their timeline with my feedback.