Overview
Workable is a recruiting software platform that helps teams post jobs, track candidates, and manage the hiring process. Persona’s Workable integration connects your Workable account to Persona Workflows so you can incorporate recruiting context—like job details, candidate profiles, and candidate activity—into automated identity and hiring processes.
This integration is especially useful for Recruiting Operations and People Operations teams that want to reduce manual data entry and keep hiring systems aligned as candidates move through the pipeline.
Benefits
- Reduced manual work: Automatically create or update candidate records from Persona instead of copy-pasting candidate details between systems.
- More consistent candidate records: Keep key candidate fields (like contact information and profile details) up to date as your workflow progresses.
- Better pipeline visibility in workflows: Pull a candidate’s activity stream (including stage transitions and comments) to inform downstream workflow decisions.
- Faster recruiting handoffs: Give teams the context they need (job and candidate details) where they’re already working in Persona.
Integration Features
The Workable integration enables teams to incorporate recruiting context into Persona workflows. Key capabilities include:
- List Jobs: Retrieve a list of jobs (including job shortcodes) with optional filtering by job state and timestamps.
- Create Candidate: Create a new candidate for a specific job using core candidate details (for example, name and email) and optional profile fields.
- Update Candidate: Partially update an existing candidate by sending only the fields you want to change.
- Get Candidate Activities: Retrieve a candidate’s activity stream, including stage transitions, comments, and other hiring-related events.
- Update Candidate Tags: Replace a candidate’s tags with the list that you send.
- Update Candidate Custom Attribute Value: Write a value to one candidate custom attribute.
- List Recruitment Pipeline Stages: Get the stages of your recruitment pipeline.
- Webhook Subscriptions: List, create, and delete Workable webhook subscriptions from a Workflow.
- Workflow Triggers: Start a Workflow when a candidate is created or moved, when an employee is created, updated, or published, or when onboarding is completed.
- Employees (Workable HR): List, create, and update employees.
Setting up the Workable Integration
Prerequisites
To set up the Workable integration, ensure you have:
- Admin access to your Workable account
- A Workable API token with the scopes that your Workflows use:
r_jobs: jobs, recruitment pipeline stages, and candidate custom attributesr_candidates: candidate activities and webhook subscriptionsw_candidates: create, update, and tag candidatesr_employeesandw_employees: employee actions and employee events. These require Workable HR.
Setting up the Workable Credentials
- In the Persona Dashboard, go to Integrations > Marketplace and select Workable.
- Click Add Credential.
- Enter a credential nickname and your Workable account details (including your Workable subdomain and API token).
- Click Continue to save the credential.
- After the credential is created, click Test to confirm it’s working. You can remove the credential at any time.
Using the Workable Integration in a Workflow
- Create a new workflow (or open an existing one).
- Add an Action step and choose Integrations.
- Select Workable and pick your saved credentials.
- Choose the operation you want to run (for example, Create Candidate or Update Candidate) and map Persona data into the Workable fields.
- Save and publish the workflow.
Start a Workflow from Workable events
The Workable integration can start a Workflow when one of these Workable events occurs:
- Candidate created: A candidate is added in Workable.
- Candidate moved: A candidate moves between recruitment pipeline stages. The stage in the event is the new stage.
- Employee created, Employee updated, and Employee published: An employee record changes in Workable HR. An Employee updated event contains only the fields that changed.
- Onboarding completed: Workable sends this event when an employee completes onboarding. An API action cannot cause this event.
Employee events require Workable HR and a token with the r_employees scope.
Workable signs each delivery with your Workable API access token. Persona uses that token to verify the delivery.
- In the Persona Dashboard, open the Workable integration page and add a webhook.
- Enter a nickname, select the environments that the webhook is active in, and enter your Workable API token in Access Token.
- Copy the webhook URL that Persona generates.
- Create a Workable webhook subscription for each event that you want. Use the Persona webhook URL as the target. You can use the Subscribe to a webhook event action or the Workable API.
A Workflow that a Candidate moved event triggers starts even when Workable sends limited candidate profile details. In that case, optional profile fields can be empty. Make sure that your Workflow steps do not depend on these fields. For example, use conditions, or use the Candidate ID with Get candidate activities to get more context.
Workable Operations Overview
Persona can list jobs and recruitment pipeline stages, create and update candidates, update candidate tags and custom attributes, and get candidate activity streams with Workable’s API. Persona can also manage webhook subscriptions and, with Workable HR, list, create, and update employees.
See below for a comprehensive list of available Workflow Action steps and possible configurations for the Workable integration:
Listing Endpoints
These endpoints help Persona fetch lists that can be used in workflows (for example, when selecting the right job to associate with a candidate).
-
List jobs: Returns a paginated list of jobs in your Workable account and includes each job’s shortcode, which can be used when creating candidates for a specific role. This is helpful for keeping workflows aligned to the current set of open roles without requiring someone to manually look up job identifiers.
Configuration Steps:
- Provide values for required fields:
- None
- Optionally add:
- State (Draft, Published, Archived, Closed)
- Limit
- Since ID
- Created After (timestamp)
- Updated After (timestamp)
- Provide values for required fields:
-
List recruitment pipeline stages: Returns the stages of your recruitment pipeline. Each stage has a slug, a name, a kind, and a position. Use a stage slug to limit a candidate event subscription to one stage, for example
hired.
Create a candidate for a job
Create a new candidate under a specific job so recruiting teams can start tracking an applicant in Workable as part of a Persona-driven workflow. This action requires basic candidate identity fields and supports adding additional profile details—such as a cover letter, education history, work experience, and social profiles—when available.
Configuration Steps:
- Provide values for required fields:
- Job shortcode
- Candidate first name
- Candidate last name
- Candidate email
- Optionally add:
- Headline
- Summary
- Address
- Phone
- Cover letter
- Education entries (for example, degree, school, field of study, start date, end date)
- Experience entries (for example, title, summary, company, industry, start date, end date, current)
- Social profiles (for example, type, name, username, URL)
Update a candidate
Update an existing candidate by sending only the fields you want to change, which helps keep Workable aligned as new information becomes available during your workflow. This is useful when your workflow learns additional candidate context over time and you want Workable to reflect the latest details without overwriting fields unnecessarily.
Configuration Steps:
- Provide values for required fields:
- Candidate ID
- Candidate fields to update
- Optionally add:
- First name
- Last name
- Headline
- Summary
- Address
- Phone
- Cover letter
- Education entries
- Experience entries
- Social profiles
Get candidate activities
Retrieve a candidate’s activity stream to understand what has happened in the hiring process, including stage transitions, comments, and other hiring-related events. This can be used to enrich workflow context or to drive conditional logic (for example, taking different actions depending on the most recent stage-related activity).
Configuration Steps:
- Provide values for required fields:
- Candidate ID
Update candidate tags
Replace a candidate’s tags with the list that you send. This action replaces the candidate’s entire tag list. Include every tag that you want to keep. An empty list removes all tags. The token must have the w_candidates scope.
Configuration Steps:
- Provide values for required fields:
- Candidate ID
- Tags
Update candidate custom attribute value
Write a value to one candidate custom attribute. Workable documents this action as requiring the r_jobs scope.
Configuration Steps:
- Provide values for required fields:
- Candidate ID
- Custom Attribute Key
- Provide the field that matches the type of the attribute:
- Checked (yes or no)
- Value (short text, free text, or numeric)
- File (File Name and File Data), or File URL
- Date
- Choices
Manage webhook subscriptions
Use these actions to control which Workable events reach Persona:
- List webhook subscriptions: Returns your webhook subscriptions.
- Subscribe to a webhook event: Creates a subscription. Requires a target URL and an event. Optionally, add a job shortcode and a stage slug. These two filters apply to candidate events only.
- Unsubscribe: Deletes a subscription. Requires the subscription ID.
You can register each target URL one time only. A duplicate target URL returns a conflict error, so delete the old subscription first. Each subscription has an expiry (valid_until) and can need renewal.
Employees (Workable HR)
List, create, and update employees with List employees, Create employee, and Update employee. These actions require Workable HR. The token must have the r_employees scope to read employees and the w_employees scope to create or update employees.
FAQs
What Workable subdomain should I use when configuring credentials?
Use the subdomain of your Workable account (for example, if your Workable account is hosted at a URL that includes acme, your subdomain would be acme).
What information is required to create a candidate?
Creating a candidate requires the candidate’s first name, last name, and email, along with the job’s shortcode (so Workable knows which job the candidate should be associated with).
Can I filter the job list returned by Workable?
Yes. When listing jobs, you can optionally filter by job state (Draft, Published, Archived, or Closed) and by created/updated timestamps, and you can page through results using limit and an ID-based cursor.
Will Update candidate tags keep existing tags?
No. Update candidate tags replaces the candidate’s entire tag list with the list that you send. Include every tag that you want to keep. An empty list removes all tags.
Why are Workable events not starting my Workflow?
Check these items:
- The webhook subscription exists in Workable and is not expired.
- The target URL of the subscription is the Persona webhook URL.
- The token has the scopes that the event needs.
- The stage and job filters on the subscription match the candidates that you expect.
If a delivery does not get a success response, Workable tries the delivery again.
Why are some candidate fields empty in a Candidate moved event?
Workable can send limited candidate profile details in a Candidate moved event, so optional profile fields can be empty. Design your Workflow so that it does not depend on these fields.
Plans Explained
Workable Integration by plan
| Startup Program | Essential Plan | Growth Plan | Enterprise Plan | |
|---|---|---|---|---|
| Workable Integration | Not Available | Not Available | Limited | Available |