Documentation

Connect Workable

Workable takes two things — your subdomain and an access token — and sets up its own webhooks once you're connected. The one thing to decide carefully is the token's expiry, because when it lapses the connection stops with it.

Before you start

You need to be an Admin in Workable. There's no narrower permission for generating tokens.

Generate the token in Workable

  1. In Workable, select your profile icon at the top right, then Settings.
  2. Go to Integrations > Apps and find API Access Tokens.
  3. Select + Generate API token and name it, such as Voyse.
  4. Choose an expiry. Workable offers 30 days, 90 days, 6 months, 1 year and 2 years. Pick the longest your organisation's rules allow — when the token expires, roles stop importing and applications stop reaching Workable until you generate a new one and enter it here again. Put the date in a calendar.
  5. Select the scopes:
    • r_jobs — your published roles.
    • w_candidates — candidates apply through Voyse.
    • r_candidates — personalised links for named people.
    • w_comments — writing a summary of what a candidate asked back to their profile.
  6. Copy the token. Workable shows it once.

Your subdomain is the first part of your Workable address, so acme in acme.workable.com. It's also shown in Settings, in the company profile section.

Connect it in Voyse

  1. Select Integrations in the sidebar.
  2. Under Connect an ATS, choose Workable.
  3. Fill in Subdomain and Access token, then select Connect.
  4. The pill by the provider's name reads Connected, and Sync status fills in once the first import finishes.

Webhooks

There's nothing to set up. As you connect, Voyse registers two subscriptions in Workable — a candidate created, and a candidate moved — and the Webhooks section reads Configured automatically. Candidate events are received in real time.

If that registration didn't complete, the section offers Complete setup instead; select it once the token is in place.

Workable sends candidate activity, not job activity, so a role you publish in Workable appears in Voyse at the next import or when you select Sync now.

What comes across

Jobs whose state in Workable is published, with their departments and their application questions.

Capabilities lists Job Sync, Application Submit and Webhook Events as essential, plus:

  • CRM Prospects — granted when the token has r_candidates.
  • Candidate Notes — listed, but it stays Not granted. Workable offers no way for Voyse to confirm that a token may write comments without writing one, so Voyse doesn't claim it. Nothing else is affected.

Check capabilities re-tests the first of those after you change the token's scopes.

If it didn't work

  • Invalid Workable credentials — either the subdomain is the whole address rather than the name alone, or the token has expired. Check its expiry in Workable first; a lapsed token looks exactly like a wrong one.
  • Roles stopped arriving after months of working — almost always the token expiry. Generate a new token and connect again with it.
  • CRM Prospects shows Not granted — the token lacks r_candidates. Generate a new token with that scope and connect again with it.

The rest of the page — sync status, the activity log, disconnecting — is covered in Connect your ATS.