Getting started with Workable
January 11, 2024
To add Workable to your product with Unified.to, activate the Workable integration in your workspace and choose how customers authorize it: a Workable API token plus the account subdomain, or OAuth 2 with credentials that Workable issues to partners. Then embed the Authorization component and store the connection ID each customer creates. Workable is one of 2297 integrations on Unified.to. This guide is for developers and product teams adding Workable ATS and HR data to their product. It covers Unified.to's Workable integration from credentials to your first API call.
At the end of this guide, you will have everything you need to activate a Workable integration and begin creating customer connections in production.
What do you need before you start?
You need a Unified.to account. Start a 30-day free trial and follow the onboarding steps. Workable and all pre-built integrations are available on every Unified.to plan.
You also need to choose which Workable credential your customers will use. The API-token method needs nothing from Workable except a customer who is a Workable Admin. OAuth 2 needs partner credentials from Workable.
This guide assumes you know Workable and basic integration concepts. You don't need to be an expert in integration development or in Unified.to.
Should your customers use a Workable API token or OAuth 2?
Use the API token if you want to start now: each customer creates the token in their own Workable account. Use OAuth 2 once Workable has accepted you as a partner. Your customers then approve access on Workable's sign-in page, and Workable's API docs give OAuth tokens a higher rate limit. Unified.to's Workable integration supports both methods.
| API token and subdomain | OAuth 2 | |
|---|---|---|
| Who issues the credential | Your customer, in their own Workable account (Admin users only) | Workable issues your client ID and client secret after it approves you as a partner; each customer then approves access |
| What your customer provides | The token and their account subdomain | Their account subdomain, then their Workable sign-in and approval of the requested scopes |
| What you enter in Unified.to | Nothing beyond activation | Your Workable client ID and client secret |
| Workable rate limit | 10 requests per 10 seconds on account tokens. Calls that carry your Workable client ID get partner limits, and Unified.to sends it when you've entered one | 50 requests per 10 seconds on OAuth tokens |
| Expiry | The customer picks 30 days, 90 days, 6 months, 1 year or 2 years. When it expires, the customer selects Renew in Workable, which keeps the same token | Access tokens last 7,200 seconds (2 hours); Unified.to uses the refresh token to renew them without asking the customer again |
| Workable facts in this table come from Workable's documentation, as of 21 October 2026. Workable counts requests per account or per OAuth application in 10-second windows, and returns HTTP 429 when a limit is exceeded. |
How does a customer generate a Workable API token?
A Workable Admin generates the token from their profile icon under Settings > Integrations > Apps, in the API Access Tokens section (Workable Help Center, as of 21 October 2026). Workable has no separate API permission, so a user who isn't an Admin can't create one.
- Select the button to generate a new token, name it and choose an expiry.
- Select the scopes for the data your product uses.
- Copy the token. Workable shows it only once; if it's lost, the customer generates a new one.
- Find the account subdomain in Workable's company profile settings. It is the
<subdomain>inhttps://<subdomain>.workable.com.
The customer enters both values when they connect Workable from your app. A token reaches only the Workable account it was created in, so a customer with two Workable accounts creates two tokens and two connections.
Ask customers to select the scopes that match the Unified.to objects you use. The Workable scope descriptions are from Workable's Help Center, as of 21 October 2026:
| Workable scope | What Workable says it covers | Unified.to objects that use it |
|---|---|---|
r_candidates | Candidates, activities, offers | Candidate, application, document, activity, scorecard |
r_jobs | Jobs, stages, members, events, accounts | Job, application status, interview, company |
w_candidates | Creating and changing candidates, comments, copying candidates onto jobs | Writes to candidates, applications, documents and activities |
r_account | Departments | HR & Directory group |
r_employees | Employee records (Workable flags this scope as sensitive) | HR & Directory employee |
Native webhooks also need r_candidates (candidates) or r_employees (employees). If a customer can't find a scope you asked for, it isn't on Workable's token form: some scopes are only available to partner OAuth apps. When the token expires, the customer selects Renew in Workable. The token stays the same, so the connection keeps working. If a token is revoked instead, ask the customer to re-authorize the same connection with a new token. The connection keeps its ID. |
How do you get Workable OAuth 2 credentials?
Workable issues OAuth 2 credentials only to official partners. Once Workable approves you, it gives you a client_id and client_secret (Workable OAuth documentation, as of 21 October 2026). There is no self-serve app registration.
- Apply to Workable's partnership program. As of 21 October 2026, Workable's 3rd Party Integration Partner tier has no mutual-customer minimum and accepts integrations built on a unified API; its Native Integration Partner tier requires at least 15 mutual customers.
- When Workable provisions your credentials, give it the Unified.to redirect URI for your workspace's region. Every authorization must use exactly the redirect URI you gave Workable at provisioning, so register each region you use:
- US (every plan):
https://api.unified.to/oauth/code - EU (Pro and Scale):
https://api-eu.unified.to/oauth/code - AU (Pro and Scale):
https://api-au.unified.to/oauth/code
- US (every plan):
- Ask Workable for the scopes your product needs. The OAuth 2 tab on Unified.to's Workable activation page lists the redirect URI and the Workable scopes for each Unified.to object. Request
w_candidatesonly if you create or update candidates, applications or documents. - In Unified.to, paste the client ID and client secret on the Workable activation page and select Activate.
With OAuth 2, the customer still enters their account subdomain. Workable access tokens last 7,200 seconds, and Unified.to renews them with the refresh token, which Workable replaces on every refresh. If a customer revokes access in Workable, ask them to re-authorize the same connection.
For help with a Workable partnership, email hello@unified.to or ask on Discord.
How do you activate Workable in Unified.to?
Sign in to app.unified.to, open Integrations, and search for Workable. You can also find it under the ATS or HR & Directory category.

Select Workable. On the authorization page, choose the categories (ATS, HR & Directory) and the authorization methods your customers can use: API token, OAuth 2 or both. For OAuth 2, enter your Workable client ID and client secret. Then select Activate.


Activation applies to the environment selected in app.unified.to. Activate Workable in each environment you use, such as Sandbox and Production, with that environment's credentials. As of 19 October 2026, activated integrations can't be copied between environments.
The Feature Support tab shows the objects and fields Unified.to's Workable integration supports. The same objects, methods and fields are listed publicly on the Workable integration page.

What can you read and write with a Workable connection?
As of 19 October 2026, Unified.to's Workable integration reads candidates, applications, jobs, documents, activities, interviews, scorecards, stages and companies in ATS, and employees and departments in HR & Directory. It writes candidates, applications, documents and activities.
| Unified.to object | Read | Write | Change events |
|---|---|---|---|
| Candidate | List, Get | Create (needs a job), Update | Native and virtual webhooks (created, updated) |
| Application | List, Get | Create, Update | Virtual webhooks |
| Job | List, Get | None (read-only) | Virtual webhooks |
| Document | List (by application), Get | Create, Update, Remove | None |
| Activity | List (by candidate) | Create | None |
| Interview | List, Get | None | None |
| Scorecard | List (by candidate) | None | Virtual webhooks |
| Application status (stages) | List | None | None |
| Company | List | None | None |
| HR & Directory employee | List, Get | None | Native webhooks |
| HR & Directory group (departments) | List, Get | None | None |
| For Workable endpoints outside these objects, use the Passthrough API (GET, POST, PUT, DELETE). |
In Workable, a candidate is created on a job, and putting the same person on another job means creating the candidate again on that job, under a new Workable ID. See Workable: creating candidates and attaching them to jobs before you write candidates.
Assessment vendors use a separate integration, Workable Assessment (launched 6 February 2026). It is authorized with a Workable partner API key and handles assessment packages and orders.
How do Workable change events reach your app?
Candidate and employee changes can arrive as native webhooks, which Unified.to forwards as Workable sends them. Applications, jobs and scorecards use virtual webhooks, which check for changes at an interval you set, as often as every minute on paid plans; a check that finds nothing isn't billed. Candidates support both types. As of 20 October 2026, Unified.to lists created and updated events for Workable objects, not deleted events.
Workable's candidate_created event feeds Unified.to's native candidate created event, and only candidate_moved (a stage change) feeds native candidate updated; other candidate changes reach you through virtual webhooks.
Create webhooks in app.unified.to or with the webhooks API. See virtual webhooks for how checks and retries work. Native Workable webhooks need no setup in the customer's Workable account: Unified.to subscribes when you create the webhook. The connection must include r_candidates for candidate events or r_employees for employee events. Without them, webhook creation fails with "Failed to subscribe".
How do you add Workable to your app?
Add the Authorization component to your app, or build your own list of integrations with the API.
Workspace and environments. When you create a Unified.to account, Unified.to creates a workspace for you. A workspace holds environments, such as Sandbox, staging and production, and each environment has its own active integrations and credentials. You can add environments under Workspace Settings on any plan (set environments).
Workspace ID. The Authorization component needs your workspace ID. Find it under Settings > API Keys.
Authorization component. Open app.unified.to/embed, configure the Authorization component and copy its snippet into your app with your workspace ID. Components are available for React, Angular, Vue, Svelte and plain JavaScript. Select the permission scopes your product needs; if you leave them blank, Unified.to requests every scope the integration supports. The preview shows the Workable authorization page your customers see.
Your own front end. To build your own list, call GET /unified/integration/workspace/{workspace_id}, which returns all activated integrations in a workspace. Then send customers to the authorization URL from GET /unified/integration/auth/{workspace_id}/{integration_type}.
What happens after a customer connects Workable?
After a customer authorizes Workable, Unified.to redirects them to your success URL. The URL carries id (the connection ID), state, nonce, type and sig. Before you store anything, check sig against your workspace secret (embedded components).
Important: pass your own user or account ID in state. It comes back on the success URL with the connection ID, so you can store the two together.
From then on, call the API with that connection ID, for example GET /ats/{connection_id}/candidate. A connection is one customer's authorization of one integration.
How do you test without a Workable account?
Use the Sandbox (synthetic data) environment. Switch the environment in app.unified.to to Sandbox (synthetic data), activate Workable with any credentials, and create a test connection under Connections > Create test connection. Calls on that connection return synthetic data and don't reach Workable (sandbox environment).
To get mock data on a single request, send the header X-Mock: 1 with an empty Authorization header (mock server).
Which SDKs can you use?
SDKs are available for TypeScript, Python, PHP, Java, Go, C# and Ruby. Learn more.
Where to go next
- Workable: creating candidates and attaching them to jobs
- Build a candidate sourcing or job board app
- Build a candidate assessment product
- Workable integration page
Have a question? Complete this form or chat with us on Discord.