A candidate is an application, not a person. Someone who applied to two jobs is two candidate records with the same name and email. See Candidates are applications.
The Read step covers two objects: Candidate with 22 fields and Job Posting with 21. After a change to the Lever fields, for example a new field, run Reconnect under Manage Connections to make sure the step has the latest catalog.
A candidate is one application, not a person. Someone who applied to two jobs is two candidate records: same Name and Email Addresses, different Record ID, Stage and Job Posting Title.
| Fields | Scope |
|---|---|
| Name, Headline, Location, Email Addresses, Phone Numbers, Mobile / Work / Home Phone, Links | Changes on every application this person holds. |
| Stage, Tags | Only changes on the current application. |
| Field | Behavior on update |
|---|---|
| Email Addresses | Adds to the existing list. Case-insensitive, so an address already on the record is not duplicated. |
| Phone Numbers | Adds a number to the existing list if it is not already there. The number lands with no type, which Lever shows as Other. |
| Mobile / Work / Home Phone | Replaces the first number of that type. A candidate with three mobile numbers shows and updates only the first. |
| Links, Tags | Adds to the existing list. |
| Name, Headline, Location, Stage | Replaces the current value. |
An update never removes a value. You cannot drop an email address, phone number, tag, or link from a workflow.
| Field | What to know |
|---|---|
| Name | Required on every write. To change a name the candidate already has, tick Overwrite if field value exists. |
| Location | Stored as Lever's own version of the string: Houston, TX, USA reads back as Houston, Texas, USA. |
An empty Record ID under Update or Create creates a candidate. An email address that already belongs to a contact attaches the new application to that person and keeps their existing name. With Create as the write setting, Job Posting Title is also available: map it to attach the new application to a job, otherwise the candidate is created with no job selected.
The Note object is create-only and has two fields, Candidate Record ID and Note Content. Both are required.
⚠️ Address the candidate by Record ID, for example from the Read step.
Record ID is the only key that guarantees one match. Without it, narrow the rule to a single application: Email Addresses plus Job Posting Title, Stage, or Tags.
Their labels carry a (searchable) suffix in the picker.
Candidate: Record ID, Email Addresses, Tags, Sources, Origin, Stage, Job Posting Title.
Job Posting: Record ID, Job Title, State, Team, Location, Work type, Tags.
Any other field in the rule stops the step.
;, and the record has to carry all of them. Tags = "Java; Kubernetes" finds candidates tagged with both. Two conditions on Tags mean the same thing. One value that matches nothing empties the result.; in it, or a second condition on the same field, stops the step.Team = Customer Success matches, customer success returns nothing. Use values as the Read step returns them.| Field | What to know |
|---|---|
| Record ID | Returns a single record. An empty value returns nothing. |
| Email Addresses | Returns every application this person holds. |
| Tags | Case sensitive. Matches the posting's automatic tags as well as the ones a recruiter set. |
| Sources | Matches whole values, not parts of them. |
| Origin | One of agency, applied, internal, referred, sourced, university, in any letter case. |
| State | One of published, internal, closed, draft, pending, rejected, in any letter case. |
| Stage | The stage name as shown in Lever. |
| Job Posting Title, Job Title | The job title as shown in Lever. Two postings with the same title stop the step. |
| Location | The value the Read step returns, Remote - US, not the longer string in the posting form. |
⚠️ An email search returns every application the person holds. Add Job Posting Title, Stage, or a Tag to the rule to land on one.
Tags include the posting's title, team, and location, which Lever adds to every application and hides on the candidate profile. A candidate tagged qa-keep on a Customer Success Manager posting returns:
Customer Success Manager; Customer Success; Remote - US; qa-keep
| Type | Reads as |
|---|---|
| Date | ISO instant: 2026-08-15T19:28:44.551Z |
| List | Email Addresses, Phone Numbers, Links, Tags, Sources: one string with ; between values, Product Manager, Growth; Remote - US |
Department stays empty unless your Lever account uses departments. Team is populated either way.
Posting URL and Apply URL are two different links: the public job page and the application page.
Values must match your Lever account exactly.
| Field | Accepted values |
|---|---|
| Origin | agency, applied, internal, referred, sourced, university. Any letter case. |
| Location type | remote, onsite, hybrid. Read only. |
| State | published, internal, closed, draft, pending, rejected. Any letter case. Read only. |
| Salary Interval | A machine value such as per-year-salary, not the / year shown in Lever. Read only. |
| Stage, Work type, Team, Location | Configured in your Lever account, so the values are your own. Use them as the Read step returns them. |
Open the Docusign App Center and search for Lever in the search bar.
Click the Lever app card to open its detail page, then click Install App.
Review the access the app requests and click Install and Authorize.
The app now appears with an Installed status.
On the installed app page, click Connect Account.
Connection Visibility: choose how the connection is shared:
Name Connection: enter a name. It appears in workflow steps, so make it easy to identify. Click Log In.
Sign in to Lever if you are not signed in already. Lever names the app Docusign IAM for Lever.
On the Lever consent screen, click Accept.
The connection is added and ready to use in workflow steps.
The Lever consent screen appears every time you create a connection.
On the Lever app page, open the Manage dropdown.
Select Manage Connections to see every connection.
Use the three-dot (⋮) menu next to a connection:
Use Manage → New Connection on the app page, or + New Connection on the Connections page. Each connection appears separately in workflow steps.
In Lever, open Settings → Integrations and API → Authorized Apps and revoke Docusign IAM for Lever. That stops every Docusign connection created by that Lever user.
Log in to Docusign and go to Agreements → Workflows.
Click Create Workflow.
Build your workflow using the available steps, including the Lever actions.
Publish the workflow when it is ready.
Click + Add Step and search for Lever:
A typical hiring flow:
Job postings are read-only. There is no writeback to a posting.
The Read from Lever step retrieves a record and exposes its fields as workflow variables.
In this example the workflow starts From an API Call and receives the ID of the record to read.
On the workflow canvas, click Add workflow start.
Select a method: choose From an API Call.
Set up variables: add a Text variable named object_id.
Process type: choose Automated process.
Once published, the workflow has a URL your external system calls, passing object_id.
On the workflow canvas, click + Add a step below Start Workflow.
Search for Lever and select Read from Lever.
Connection: select the connection you created during installation.
Lever object: choose Candidate or Job Posting. This example uses Candidate.
Click Next.
Click Add or Remove Fields and tick the fields your workflow needs. The selected fields become workflow variables for later steps.
Available fields:
Candidate: Record ID, Name, Headline, Email Addresses, First Email, Second Email, Phone Numbers, Mobile Phone, Work Phone, Home Phone, Location, Links, Tags, Sources, Origin, Stage, Owner Email, Owner Name, Job Posting Title, Lever Profile URL, Created At, Last Interaction At.
Job Posting: Record ID, Job Title, State, Team, Department, Location, Work type, Location type, Tags, Posting Owner Name, Posting Owner Email, Hiring Manager Name, Hiring Manager Email, Salary Range Minimum, Salary Range Maximum, Salary Currency, Salary Interval, Salary Description, Posting URL, Apply URL, Created At.
Fields with a fixed set of values are listed under Field Values Reference.
Click Next.
Create a rule that tells the step which record to read. In this example, match the Lever Record ID to the object_id variable from the workflow start:
object_idUnder How many records should this step return?, pick one:
Use preview this step to check the rule against live data. Click Apply.
Searchable fields are Record ID, Email Addresses, Tags, Sources, Origin, Stage, and Job Posting Title for a candidate, and Record ID, Job Title, State, Team, Location, Work type, and Tags for a job posting. Every other field stops the step. How each field matches is under Searching for a Record.
The Writeback to Lever step updates a candidate, creates one, or posts a note.
Check what an update does to each field first: some fields replace their value and some add to a list.
On the workflow canvas, click + Add a step where the writeback belongs, for example below a Collect Data with Web Forms step.
Search for Lever and select Writeback to Lever.
Connection: select your Lever connection.
Lever object: choose Candidate or Note. This walkthrough uses Candidate.
Write settings:
Click Next.
Click Add or Remove Fields and tick the fields you want to write.
Each selected field then gets its own row. Map it to the workflow variable that supplies the value.
Writable Candidate fields: Name*, Headline, Email Addresses, Phone Numbers, Mobile Phone, Work Phone, Home Phone, Location, Links, Tags, Stage.
* Name is a required field. To change a name the candidate already has, tick Overwrite if field value exists on it.
With Create as the write setting, Job Posting Title is also available: map it to attach the new candidate to a job.
⚠️ Map from the right source. The variable picker also lists the output of your Read from Lever step. Mapping from there writes the original values back unchanged. Map from the step that collected the new data, such as Collect Data with Web Forms.
Click Next.
Address the candidate by Record ID, for example from the Read step.
Click Apply.
Leaving the Record ID empty under Update or Create creates a candidate.
Select Note as the Lever object.
Create is the only write setting.
Map both required fields, Candidate Record ID and Note Content.
The File Upload to Lever step attaches a document produced earlier in the workflow to a candidate's Files tab. Maximum size is 30 MB.
Add a step after signing completes, search for Lever, and select File Upload to Lever.
Choose the file or envelope from an earlier step. In this example it is the Combined Envelope File from Send Documents for Signature.
An empty list means no earlier step in the workflow produced a file.
Select connection: your Lever connection.
Select drive: Candidates is the only drive.
Click Add Folder.
The folder holds the candidate's Record ID. Lever creates no folder.
Open the Select folder dropdown and pick New Subfolder.
In the New folder dialog, click Add Variable.
Choose the step that returns the candidate, then select Record ID and click Add.
The variable appears in the Folder name field.
Select folder now shows the Record ID variable. Click Next.
The app reads the last segment of the path, so a subfolder overrides the folder above it. Plain text in the folder and the Record ID in a subfolder still reaches the right candidate.
We do not recommend it. Put the Record ID in the folder and leave the subfolder out.
Build the file name from Add Text and Add Variable. A timestamp variable keeps repeat runs from producing identical names.
The app replaces anything outside letters, digits, dots, and hyphens with _, so 2026-08-21T08:20:32.706Z is stored as 2026-08-21T08_20_32.706Z.
Click Apply. The file lands on the candidate's Files tab, marked Related to their job.
The Lever consent screen appears every time I create a connection.
That is how the app connects. Earlier connections stay Active under Manage Connections.
A field or a search option I expect is missing from the step.
Open Manage Connections, click Reconnect on the connection, then reopen the step.
The Read step fails with Request failed with status code 400.
Check the rule: a field outside the searchable list, a
;in a field other than Tags or Sources, two conditions on one field other than Tags or Sources, a Stage or Job Posting Title that does not exist in Lever, or an Origin or State outside its list.
My rule has a Record ID and another condition, and the record comes back even though it does not match the other condition.
A Record ID identifies one record, so the other conditions are not applied. Drop the Record ID when the other conditions should decide.
Why can't I search by name, First Email, or Mobile Phone?
Name and phone number are not searchable. First Email, Second Email and Mobile / Work / Home Phone are assembled from the full lists on the record, so they are not searchable either. Search on Email Addresses.
A tag search returns nothing, but the candidate has the tag.
Tag values are case sensitive. Copy the tag as the Read step returns it.
The Tags variable holds more tags than the candidate profile shows.
The posting's title, team, and location are added to every application as tags. See Reading Record Data.
I created a candidate and Lever saved a different name.
One of the email addresses already belonged to a contact, so the new application was attached to that person and kept their existing name.
I wrote a phone number and the old one is still there.
Phone Numbers adds to the list. To replace a number, write to Mobile Phone, Work Phone, or Home Phone.
How do I remove a tag, a link, or an email address?
Not from a workflow. Those fields only add. Remove the value in Lever.
The location I wrote back does not match what the Read step returns.
Lever stores its own version of the location, so
Houston, TX, USAcomes back asHouston, Texas, USA. Compare against the value the Read step returns.
I created a candidate and the profile says "No job selected yet".
Map Job Posting Title in the Writeback step with Create as the write setting. It takes the job title as shown in Lever.
The file picker says no files are available.
No earlier step produced a file. Add the upload after Send Documents for Signature.
The file did not appear on the candidate.
The folder has to hold the candidate's Record ID variable, from a step that runs before the upload.