# SmartRecruiters integration overview

> Connect Persona Workflows to SmartRecruiters to look up and tag candidates, create and publish jobs, and start Workflows from SmartRecruiters events.

Source: https://help.withpersona.com/articles/uIeeE3KHgAqTEnltQfZPtt/
Section: Marketplace and 3rd-Party Integrations > ATS > SmartRecruiters

## Overview

[SmartRecruiters](https://www.smartrecruiters.com/) is a talent acquisition suite with recruitment marketing, applicant tracking, and hiring tools. Persona's SmartRecruiters integration connects your Workflows to SmartRecruiters candidates and jobs, so recruiting, operations, and compliance teams can pull candidate context into Persona and write verification outcomes back without copying them by hand.

Common uses include verifying the identity of candidates who reach a particular stage, tagging candidates in SmartRecruiters with the result, and starting a Workflow when something changes in SmartRecruiters.

## Integration features

- **Candidates:** List and search candidates, retrieve a candidate's details, status history, attachments, and application status, create a candidate on a job, and set candidate property values.
- **Candidate tags:** Retrieve, add, replace, or delete a candidate's tags, for example to mark a candidate as `persona-verified`.
- **Jobs:** Create a job, publish it, and list its publications.
- **Configuration lookups:** List the industries, job functions, experience levels, types of employment, departments, candidate and job properties, and predefined locations your SmartRecruiters company uses.
- **Webhooks:** Start a Workflow from a SmartRecruiters event notification, and manage SmartRecruiters webhook subscriptions from a Workflow.

## Prerequisites

Before configuring the integration, you need:

- A SmartRecruiters account.
- A SmartRecruiters API key created with the **Admin** system role. Managing webhook subscriptions requires the Admin role; other roles get a `NO_PERMISSION_TO_MANAGE_WEBHOOKS` error.

## Set up SmartRecruiters credentials

1. In SmartRecruiters, go to **Settings > Administration > App management > Custom applications**.
2. Click **New Credential** and choose **API Key**.
3. Enter a credential name and description, set the system role to **Admin**, and click **Generate**. Copy the API key.
4. In the Persona Dashboard, go to **Integrations > Marketplace** and select **SmartRecruiters**.
5. Click **Add Credential**, enter a nickname for the credential, choose the **Production** or **Sandbox** SmartRecruiters server, and paste the API key.
6. Save the credential.

## Use SmartRecruiters in a Workflow

1. Create a Workflow, or open the Workflow you want to update.
2. Add an **Action** step and select **Integrations**.
3. Select **SmartRecruiters**, choose the saved credential, and select an action.
4. Map Persona data to the action's input fields.
5. Save and publish the Workflow.

## Start a Workflow from SmartRecruiters events

The integration includes an **Event notification** webhook that can trigger a Workflow whenever a SmartRecruiters event it is subscribed to fires, such as `candidate.created`, `candidate.updated`, or `application.status.updated`.

1. In the Persona Dashboard, open the **SmartRecruiters** integration page and add a webhook. Enter a nickname, select the environments it should be active in, and fill in the **Header name** and **Header value** Persona uses to authenticate incoming deliveries.
2. Copy the webhook URL Persona generates.
3. Create a SmartRecruiters webhook subscription with that URL as the **Callback URL** and the events you want, using the **Create webhook subscription** action or the SmartRecruiters API.
4. Activate the subscription with the **Activate webhook subscription** action. SmartRecruiters delivers no events until a subscription is activated.

ℹ️

Each environment you select for the webhook runs the Workflow in that environment when an event arrives.

An event notification carries the event name, version, and ID, a link to the changed resource, and only the identifiers of what changed, such as the candidate ID, job ID, or application ID. Use those identifiers with actions like **Retrieve candidate details** to fetch the full record.

## SmartRecruiters actions

### Candidates

- **List candidates:** Returns candidates who have at least one job application. Optional filters: Query, Job IDs, Locations, Statuses, Sub-status, Tags, Updated After, Limit, Page ID.
- **Retrieve candidate details:** Returns a candidate. Requires Candidate ID.
- **Create candidate:** Creates a candidate and assigns them to a job. Requires Job ID, First Name, Last Name, and Email. Optional fields include Phone Number, Location, Web Profiles, Tags, Education, Experience, Source Details, and Internal. If no source is set, SmartRecruiters records the API as the source.
- **Retrieve candidate status history for job:** Requires Candidate ID and Job ID.
- **List candidate attachments for job:** Requires Candidate ID and Job ID.
- **Update candidate property values:** Sets candidate property values for the candidate's job. Requires Candidate ID and Job ID. Use **List candidate properties** to see the properties your company has configured.
- **Retrieve application status:** Returns a candidate's application status for a job posting. Requires Posting UUID and Candidate ID. Find the Posting UUID with **List job publications**.
- **Retrieve job application:** Requires Job Application ID.

### Candidate tags

- **Retrieve candidate tags:** Requires Candidate ID.
- **Add tags to candidate:** Adds tags and keeps the existing ones. Requires Candidate ID and Tags.
- **Replace candidate tags:** Replaces every existing tag with the list you provide. Requires Candidate ID and Tags.
- **Delete candidate tags:** Deletes all of a candidate's tags. Requires Candidate ID.

### Jobs

- **Create job:** Requires Title, Location, Industry, Function, and Experience Level. Optional fields include Reference Number, Target Hiring Date, Department, Type of Employment, EEO Category, Template, Compensation, Job Ad, and Properties. Include any job properties your company marks as required; **List job properties** shows them.
- **Publish job:** Publishes the job's default ad to internal sources and free job aggregators, the same as **Publish** in SmartRecruiters. Requires Job ID. Optional fields: Aggregators, Visibility, Include Internal, Delay Public In Days.
- **List job publications:** Requires Job ID. Optional fields: Active Only, Accept-Language.

### Configuration lookups

Use these to find valid values for Create job and other actions: **List industries**, **List functions**, **List experience levels**, **List types of employment**, **List departments** (requires Company Identifier, the subdomain of your company's career site), **List candidate properties**, **List job properties**, and **List predefined locations**.

### Webhook subscriptions

**Create webhook subscription** (requires Callback URL and Events), **List webhook subscriptions**, **Retrieve webhook subscription**, **Delete webhook subscription**, **Activate webhook subscription**, **Generate webhook secret key**, **Retrieve webhook secret key**, and **Search callback log**. Each SmartRecruiters user can register up to 20 subscriptions.

## FAQs

### Will Add tags to candidate overwrite existing tags?

No. Add tags to candidate keeps the existing tags. Replace candidate tags is the action that overwrites them, so include any tag you want to keep in its list.

### Why are SmartRecruiters events not starting my Workflow?

Check that the subscription is activated, since SmartRecruiters sends nothing to an inactive subscription. SmartRecruiters can also suspend a subscription automatically after repeated delivery failures. Use **Search callback log** to see recent delivery attempts and their results.

## Plans Explained

### SmartRecruiters Integration by plan

|                             | Startup Program | Essential Plan | Growth Plan | Enterprise Plan |
| --------------------------- | --------------- | -------------- | ----------- | --------------- |
| SmartRecruiters Integration | Not Available   | Not Available  | Limited     | Available       |

[Learn more about pricing and plans](https://withpersona.com/pricing?utm_source=product&utm_medium=referral&utm_audience=a&utm_campaign=cm_gen_ds_hc-plan-table).