Workable provides an API that gives you complete control over your data. You can access, manage, and extract recruiting data from your Workable account by generating API access tokens.
To generate or revoke access tokens for your account, you must be an Admin user in Workable; there is no dedicated access only for this use. As an Admin user, you can:
- create tokens with expiration
- choose the scopes for the tokens you wish to create
- have multiple account-level tokens with different scopes, different expirations, etc.
Once one or more access tokens are created, you should share them with the relevant parties (developers, IT team).
Generate a new token
As an Admin user:
- Click your profile icon in the upper right and navigate to Settings > Integrations > Apps
- Locate the API Access Tokens section near the top of the page
- Click the button + Generate API token
- Add a name for your token, e.g., if it is used to access candidate data, you can name it "Candidates"
- Select the token's expiration from the dropdown; available options will be: 30 days, 90 days, 6 months, 1 year, 2 years
- Select which scope(s) will be enabled for this token; you must select at least one scope
- Click Generate token to complete the process
- Once your access token is generated, you will see a modal with the full token (a long string of random letters and numbers). Click to copy it to your clipboard.
- Your access token will not be visible after closing the modal. If you need it again, you should generate a new one.
- Be extra cautious while sharing access tokens since they're confidential. Assist your IT team in the most secure way to share it with others involved.
Supported API scopes
API tokens can be configured to enable different scopes while making calls. The set of scopes of a token makes it usable in specific (or all) the SPI endpoints.
The supported scopes are:
|SPI endpoints access
Access configuration information about your account via:
Access your candidates via:
❗This scope gives access to sensitive employee information via:
Access your jobs via:
/jobs, /jobs/:shortcode, /jobs/:shortcode/application_form, /jobs/:shortcode/questions, /jobs/:shortcode/stages, /jobs/:shortcode/custom_attributes, /jobs/:shortcode/members, /jobs/:shortcode/recruiters, /custom_attributes, /events, /events/:id
Via this scope, you will also have access to the below endpoints:
Change your candidates via:
/candidates, /talent_pool/candidates, /candidates/:id/comments, /candidates/:id/tags, /candidates/:id/disqualify, /candidates/:id/revert, /candidates/:id/copy, /candidates/:id/relocate, /candidates/:id/move, /candidates/:id/ratings
Add comments to your candidates via:
/candidates/:id/comments (also included in the w_candidates scope)
Change your employees via:
On the same page, Admin users have the ability to revoke individual tokens. Revoking a token means that every script or application that accesses the Workable SPI through this token will stop functioning. You must generate a new access token and update it in every script or application previously bound to the old one.
- Click the three dots menu next to the token you need to revoke and then Revoke token
- Click Revoke to confirm the action
Renew an expired token
When a token expires, you can quickly renew it by clicking the Renew button under it. Renewing a token means it won't change, so all scripts or applications using this token will continue functioning normally.