Deprecated

Candidates

"Candidates" are individuals who have been added to your Lever account as potential fits for your open job positions. "Opportunities" represent each of an individual’s unique candidacies or journeys through your pipeline for a given job position, meaning a single Candidate can be associated with multiple Opportunities. A “Contact” is a unique individual who may or may not have multiple candidacies or Opportunities.

Candidates enter your pipeline for a new Opportunity by:

Applying to a posting on your jobs site,
Being added by an external recruiting agency,
Being referred by an employee,
Being manually added by a Lever user, or
Being sourced from an online profile.

Each opportunity can have their own notes, feedback, interview schedules, and additional forms. An opportunity may be “confidential” only if it is moving through your pipeline for a job posting that has been created as confidential. Opportunities exit your pipeline by being archived for one of two reasons: (1) The candidate was rejected for the opportunity, or (2) The candidate was hired for the opportunity.

A "Contact" is an object that our application uses internally to identify an individual person and their personal or contact information, even though they may have multiple opportunities. From this API, the "Contact" is exposed via the contact field, which returns the unique ID for a Contact across your account. Contact information will be shared and consistent across an individual person's opportunities, and will continue to be aggregated onto individual opportunities in the responses to all GET and POST requests to /opportunities.

Attributes

id

250d8f03-738a-4bba-a671-8a3d73477145 String Candidate & Opportunity UID

name

Shane SmithStringContact full name

headline

Brickly LLC, Vandelay Industries, Inc, Central PerkStringContact headline, typically a list of previous companies where the contact has worked or schools that the contact has attended

contact

7f23e772-f2cb-4ebb-b33f-54b872999992StringContact UID

stage

00922a60-7c15-422b-b086-f62000824fd7Stage UIDThe stage ID of this Opportunity's current stage
Expandable If expanded, contains a stage object.

stageChanges

Array An array of a candidate's historical stage changes for this Opportunity

toStageId: 00922a60-7c15-422b-b086-f62000824fd7 String Stage UID of the stage the candidate entered
toStageIndex: 1 Number The index of the stage in the pipeline at the time the stage change occurred
updatedAt: 1407460071043 Timestamp[?] Time at which stage change occurred
userId: df0adaa6-172c-4cd6-8520-49b203660fe1 String User UID

confidentiality

non-confidential String The confidentiality of the opportunity. An opportunity can only be confidential if it is associated with a confidential job posting. Learn more about confidential data in the API. Can be one of the following values: non-confidential, confidential.

location

OaklandStringContact current location

phones

[{"value":"(123) 456-7891"}]Array of objectsContact phone number(s)

value: (123) 456-7891StringPhone number
type: StringNumber type
One of: "mobile", "home", "work", "skype", "other"

emails

shane@exampleq3.comArray of stringsContact emails

links

indeed.com/r/Shane-Smith/0b7c87f6b246d2bcArray of stringsList of Contact links (e.g. personal website, LinkedIn profile, etc.)

archived

ObjectOpportunity archived status

archivedAt: 1417588008760Timestamp[?]Datetime when Opportunity was archived in Lever.
reason: 63dd55b2-a99f-4e7b-985f-22c7bf80ab42Archive reason UIDReason why Opportunity was archived.

tags

["San Francisco","Full-time","Support","Customer Success","Customer Success Manager"] Array An array containing a list of tags for this Opportunity. Tags are specified as strings, identical to the ones displayed in the Lever interface.

sources

["linkedin"] Array An array of source strings for this Opportunity.

sourcedBy

df0adaa6-172c-4cd6-8520-49b203660fe1 User UID The user that sourced the opportunity. For opportunities that were not sourced, value is null.
Expandable If expanded, contains a user object.

origin

sourcedStringThe way this Opportunity was added to Lever. Can be one of the following values:

agency
applied
internal
referred
sourced
university

owner

df0adaa6-172c-4cd6-8520-49b203660fe1 User UID The user ID of the owner of this Opportunity.
Expandable If expanded, contains a user object.

followers

df0adaa6-172c-4cd6-8520-49b203660fe1,ecdb6670-d9f3-4b87-8267-1cde26d1bc42,022d6639-1333-419b-9635-31f93015335f Array An array of user IDs of the followers of this Opportunity.
Expandable If expanded, contains an array of user objects

applications

cdb4ff13-f7aa-49b0-b6ec-eb4617009cfa Array An array, containing up to one Application ID (can be either an active or archived Application)

WARNING: Each candidateId or opportunity can only have up to one application

resume

WARNING: This field is deprecated. Use the resumes endpoint.

createdAt

1407460071043 Timestamp[?] Datetime when this Opportunity was created in Lever. For candidates who applied to a job posting on your website, the date and time when the Opportunity was created in Lever is the moment when the candidate clicked the "Apply" button on their application.

updatedAt

1407460080914 Timestamp[?] or null Datetime when candidate was updated in Lever. This property is updated when the following fields are modified: applications, archived, confidentiality, contact, dataProtection, emails, followers, headline, isAnonymized, lastAdvancedAt, lastInteractionAt, links, location, name, origin, owner, phones, snoozedUntil, sourcedBy, sources, stage, stageChanges, tags. It is also updated when the following fields on the expanded applications object are modified: archived, candidateId, comments, company, customQuestions, email, links, name, opportunityId, phone, postingId, postingHiringManager, postingOwner, primarySource, requisitionForHire, secondarySources, type, user.

WARNING: The dataProtection status is based on candidate-provided consent and applicable data policy regulations which can change according to many factors. The updatedAt field is only updated when the candidate-provided consent changes.

This value is null when the updatedAt property has not been previously set. This is likely to occur for opportunities that were created prior to the introduction of this property, and have not since been updated.

lastInteractionAt

1417588008760 Timestamp[?] Datetime when the last interaction with this Opportunity profile occurred. [?]

lastAdvancedAt

1417587916150 Timestamp[?] Datetime when the candidate advanced to the pipeline stage where they are currently located in your hiring process for this Opportunity

snoozedUntil

1505971500000 Timestamp[?] If this Opportunity is snoozed, the timestamp will reflect the datetime when the snooze period ends

urls

Object An object containing the list and show urls for this Opportunity.

list: https://hire.lever.co/candidates String URL that points to the account's list of candidates
show: https://hire.lever.co/candidates/250d8f03-738a-4bba-a671-8a3d73477145 Object URL that points to the candidate's profile page for this Opportunity

dataProtection

Object An object containing a candidate's data protection status based on candidate-provided consent and applicable data policy regulations. If there is no policy in place or if no policies apply to the candidate, value is null. (shared by contact)

store, contact

Object An object representing the consent status for a specified processing activity (one of store or contact).

allowed: true Boolean True if the applicable data policy regulation allows for storage of this record.
expiresAt: Timestamp[?] Timestamp of when this permission expires.

isAnonymized

false Boolean Indicates whether an Opportunity has been anonymized. When all of a contact’s Opportunities have been anonymized, the contact is fully anonymized and their personal information is removed. Non-personal metadata may remain for accurate reporting purposes.

deletedBy

8d49b010-cc6a-4f40-ace5-e86061c677ed String User ID of the user who deleted the Opportunity. Note that this attribute only appears for deleted Opportunities.

deletedAt

Timestamp[?] Timestamp for when the Opportunity was deleted. Note that this attribute only appears for deleted Opportunities.

Retrieve a single candidate

WARNING: This endpoint is deprecated but maintained for backward compatibility.

If you want to access a contact's personal or contact information, use the Retrieve a single opportunity endpoint, which will return the same response if using the same value for opportunityId as candidateId.

If you want to access information about a contact's Opportunities or Applications, use the List all opportunities endpoint, specifying the relevant contact UID in the contact_id parameter and optionally specifying the expand parameter to include applications.

GET /candidates/:candidate

Examples

curl -u API_KEY: https://api.lever.co/v1/candidates/250d8f03-738a-4bba-a671-8a3d73477145

{
  "data": {
    "id": "250d8f03-738a-4bba-a671-8a3d73477145",
    "name": "Shane Smith",
    "headline": "Brickly LLC, Vandelay Industries, Inc, Central Perk",
    "contact": "7f23e772-f2cb-4ebb-b33f-54b872999992",
    "emails": [
      "shane@exampleq3.com"
    ],
    "phones": [
      {
        "value": "(123) 456-7891"
      }
    ],
    "confidentiality": "non-confidential",
    "location": "Oakland",
    "links": [
      "indeed.com/r/Shane-Smith/0b7c87f6b246d2bc"
    ],
    "createdAt": 1407460071043,
    "updatedAt": 1407460080914,
    "lastInteractionAt": 1417588008760,
    "lastAdvancedAt": 1417587916150,
    "snoozedUntil": 1505971500000,
    "archivedAt": null,
    "archiveReason": null,
    "stage": "00922a60-7c15-422b-b086-f62000824fd7",
    "stageChanges": [
      {
        "toStageId": "00922a60-7c15-422b-b086-f62000824fd7",
        "toStageIndex": 1,
        "userId": "df0adaa6-172c-4cd6-8520-49b203660fe1",
        "updatedAt": 1407460071043
      }
    ],
    "owner": "df0adaa6-172c-4cd6-8520-49b203660fe1",
    "tags": [
      "San Francisco",
      "Full-time",
      "Support",
      "Customer Success",
      "Customer Success Manager"
    ],
    "sources": [
      "linkedin"
    ],
    "origin": "sourced",
    "sourcedBy": "df0adaa6-172c-4cd6-8520-49b203660fe1",
    "applications": [
      "cdb4ff13-f7aa-49b0-b6ec-eb4617009cfa"
    ],
    "resume": null,
    "followers": [
      "df0adaa6-172c-4cd6-8520-49b203660fe1",
      "ecdb6670-d9f3-4b87-8267-1cde26d1bc42",
      "022d6639-1333-419b-9635-31f93015335f"
    ],
    "urls": {
      "list": "https://hire.lever.co/candidates",
      "show": "https://hire.lever.co/candidates/250d8f03-738a-4bba-a671-8a3d73477145"
    },
    "dataProtection": {
      "store": {
        "allowed": true,
        "expiresAt": 1522540800000
      },
      "contact": {
        "allowed": false,
        "expiresAt": null
      }
    },
    "isAnonymized": false
  }
}

List all candidates

Lists all pipeline Opportunities for Contacts in your Lever account.

WARNING: This endpoint is deprecated but maintained for backward compatibility. Use the List all opportunities endpoint, which will return the same response if using the same parameters.

GET /candidates

Parameters

include: followers Optional Include Opportunity followers in list results
expand: applications, stage, owner, followers, sourcedBy, contact Optional Expand application, stage, contact, or user IDs into full objects in response
tag: San Francisco Optional Filter Opportunities by tag (case sensitive). Results will include Opportunities that contain the specified tag. Multiple tags can be specified and results will include a union of result sets (i.e. Opportunities that have either tag).
email: shane@exampleq3.com Optional Filter Opportunities by an email address. Results will include Opportunities for Contacts that contain the canonicalized email address.
origin: sourced Optional Filter Opportunities by origin. Results will include Opportunities that contain the specified origin. Multiple origins can be specified and results will include a union of result sets (i.e. Opportunities from either origin).
source: Optional Filter Opportunities by source. Results will include Opportunities that contain the specified source tag. Multiple sources can be specified and results will include a union of result sets (i.e. Opportunities from either source).
confidentiality: confidential, non-confidential, all Optional Filter opportunities by confidentiality. If unspecified, defaults to non-confidential. To get both confidential and non-confidential opportunities you must specify all. Learn more about confidential data in the API.
stage_id: fff60592-31dd-4ebe-ba8e-e7a397c30f8e Optional Filter Opportunities by current stage. Results will include Opportunities that are currently in the specified stage. Multiple stages can be specified and results will include a union of result sets (i.e. Opportunities that are in either stage).
posting_id: f2f01e16-27f8-4711-a728-7d49499795a0 Optional Filter Opportunities by posting. Results will include Opportunities that are applied to the specified posting. Multiple postings can be specified and results will include a union of result sets (i.e. Opportunities that are applied to either posting).
archived_posting_id: f2f01e16-27f8-4711-a728-7d49499795a0 Optional Filter Opportunities by postings for which they have been archived. Results will include opportunities for candidates that applied to the specified posting and then the application was archived. Multiple postings can be specified and results will include a union of result sets (i.e. Opportunities that were applied to either posting).
created_at_start, created_at_end: 1407460069499 Optional Filter Opportunities by the timestamp they were created. If only created_at_start is specified, all Opportunities created from that timestamp (inclusive) to the present will be included. If only created_at_end is specified, all Opportunities created before that timestamp (inclusive) are included.
updated_at_start, updated_at_end: 1407460069499 Optional Filter Opportunities by the timestamp they were last updated. If only updated_at_start is specified, all Opportunities updated from that timestamp (inclusive) to the present will be included. If only updated_at_end is specified, all Opportunities updated before that timestamp (inclusive) are included.
advanced_at_start, advanced_at_end: 1407460069499 Optional Filter Opportunities by the timestamp they were advanced to their current stage. If only advanced_at_start is specified, all Opportunities advanced from that timestamp (inclusive) to the present will be included. If only advanced_at_end is specified, all Opportunities advanced before that timestamp (inclusive) are included.
archived_at_start, archived_at_end: 1407460069499 Optional Filter Opportunities by the timestamp they were archived. If only archived_at_start is specified, all Opportunities archived from that timestamp (inclusive) to the present will be included. If only archived_at_end is specified, all Opportunities archived before that timestamp (inclusive) are included.
archived: true Optional Filter Opportunities by archive status. If unspecified, results include both archived and unarchived Opportunities. If true, results only include archived Opportunities. If false, results only include active Opportunities.
archive_reason_id: 63dd55b2-a99f-4e7b-985f-22c7bf80ab42 Optional Filter Opportunities by archive reason. Results will include Opportunities that have been archived with the specified reason. Multiple archive reasons can be specified and results will include a union of result sets (i.e. Opportunities that have been archived for either reason).
snoozed: true Optional Filter Opportunities by snoozed status. If unspecified, results include both snoozed and unsnoozed Opportunities. If true, results only include snoozed Opportunities. If false, results only include unsnoozed Opportunities.
contact_id: 7f23e772-f2cb-4ebb-b33f-54b872999992 Optional Filter Opportunities by contact. Results will include the Opportunities that match the specified contact. Multiple contacts can be specified and results will include a union of result sets (i.e. Opportunities that match each of the contacts).

Examples

curl -u API_KEY: https://api.lever.co/v1/candidates

{
  "data": [
    {
      "id": "250d8f03-738a-4bba-a671-8a3d73477145",
      "name": "Shane Smith",
      "headline": "Brickly LLC, Vandelay Industries, Inc, Central Perk",
      "contact": "7f23e772-f2cb-4ebb-b33f-54b872999992",
      "emails": [
        "shane@exampleq3.com"
      ],
      "phones": [
        {
          "value": "(123) 456-7891"
        }
      ],
      "confidentiality": "non-confidential",
      "location": "Oakland",
      "links": [
        "indeed.com/r/Shane-Smith/0b7c87f6b246d2bc"
      ],
      "createdAt": 1407460071043,
      "updatedAt": 1407460080914,
      "lastInteractionAt": 1417588008760,
      "lastAdvancedAt": 1417587916150,
      "snoozedUntil": 1505971500000,
      "archivedAt": null,
      "archiveReason": null,
      "stage": "00922a60-7c15-422b-b086-f62000824fd7",
      "stageChanges": [
        {
          "toStageId": "00922a60-7c15-422b-b086-f62000824fd7",
          "toStageIndex": 1,
          "userId": "df0adaa6-172c-4cd6-8520-49b203660fe1",
          "updatedAt": 1407460071043
        }
      ],
      "owner": "df0adaa6-172c-4cd6-8520-49b203660fe1",
      "tags": [
        "San Francisco",
        "Full-time",
        "Support",
        "Customer Success",
        "Customer Success Manager"
      ],
      "sources": [
        "linkedin"
      ],
      "origin": "sourced",
      "sourcedBy": "df0adaa6-172c-4cd6-8520-49b203660fe1",
      "applications": [
        "cdb4ff13-f7aa-49b0-b6ec-eb4617009cfa"
      ],
      "resume": null,
      "followers": [
        "df0adaa6-172c-4cd6-8520-49b203660fe1",
        "ecdb6670-d9f3-4b87-8267-1cde26d1bc42",
        "022d6639-1333-419b-9635-31f93015335f"
      ],
      "urls": {
        "list": "https://hire.lever.co/candidates",
        "show": "https://hire.lever.co/candidates/250d8f03-738a-4bba-a671-8a3d73477145"
      },
      "dataProtection": {
        "store": {
          "allowed": true,
          "expiresAt": 1522540800000
        },
        "contact": {
          "allowed": false,
          "expiresAt": null
        }
      },
      "isAnonymized": false
    },
    {
      "id": "5c86dcd8-6cf1-40da-9ae3-5e7ea91079f5",
      "name": "Chaofan West",
      "headline": "Grunnings, Inc., Coffee Bean, Ltd, Betelgeuse Commercial Service Co., Ltd, Double C Private Co., Ltd",
      "contact": "bd4d81c8-7858-4624-be98-552dfb9ca850",
      "emails": [
        "chaofan@example.com"
      ],
      "phones": [
        {
          "value": "(123) 456-7891"
        }
      ],
      "location": "San Francisco",
      "links": [
        "indeed.com/r/Chaofan-West/4f2c7523b0edefbb"
      ],
      "createdAt": 1407778275799,
      "lastInteractionAt": 1417587990376,
      "lastAdvancedAt": 1417587903121,
      "snoozedUntil": 1499577840000,
      "archivedAt": null,
      "archiveReason": null,
      "stage": "00922a60-7c15-422b-b086-f62000824fd7",
      "owner": "ecdb6670-d9f3-4b87-8267-1cde26d1bc42",
      "tags": [
        "San Francisco",
        "Marketing",
        "Customer Success",
        "Customer Success Manager",
        "Full-time"
      ],
      "sources": [
        "Job site"
      ],
      "origin": "applied",
      "sourcedBy": null,
      "applications": [
        "e326d6e6-e3f6-46eb-9c14-6f90b88aacac"
      ],
      "resume": null,
      "followers": [
        "df0adaa6-172c-4cd6-8520-49b203660fe1",
        "ecdb6670-d9f3-4b87-8267-1cde26d1bc42",
        "022d6639-1333-419b-9635-31f93015335f"
      ],
      "dataProtection": null
    },
    {
      "id": "37caee03-bd3f-487d-b32e-a296ce05aa6b",
      "name": "Roberta Easton",
      "headline": "Useful Information Access",
      "contact": "853af6b1-71a2-46d7-a430-c067e28b08f9",
      "emails": [
        "roberta@exampleq3.com"
      ],
      "phones": [
        {
          "value": "(123) 456-7891"
        }
      ],
      "location": "San Jose",
      "links": [
        "https://linkedin.com/in/roberta-e"
      ],
      "createdAt": 1407778277088,
      "lastInteractionAt": 1417587981210,
      "lastAdvancedAt": 1417587891220,
      "snoozedUntil": 1420266291216,
      "archivedAt": null,
      "archiveReason": null,
      "stage": "00922a60-7c15-422b-b086-f62000824fd7",
      "owner": "ecdb6670-d9f3-4b87-8267-1cde26d1bc42",
      "tags": [
        "San Francisco",
        "Marketing",
        "Customer Success",
        "Customer Success Manager",
        "Full-time"
      ],
      "sources": [
        "Job site"
      ],
      "origin": "applied",
      "sourcedBy": null,
      "applications": [
        "eb91c63f-3511-4e9d-a805-aaa92f0c80c9"
      ],
      "resume": null,
      "followers": [
        "df0adaa6-172c-4cd6-8520-49b203660fe1",
        "ecdb6670-d9f3-4b87-8267-1cde26d1bc42",
        "022d6639-1333-419b-9635-31f93015335f"
      ],
      "dataProtection": null
    }
  ]
}

Create a candidate

WARNING: This endpoint is deprecated but maintained for backward compatibility. To create candidates and/or opportunities, use the Create an opportunity endpoint.

POST /candidates

This endpoint enables integrations to create candidates in your Lever account.

If you want to apply a candidate to a job posting or create a custom job site, you should use the Lever Postings API instead of the Lever Data API.

We accept requests of type application/json and multipart/form-data. If you are including a resume or other files, you must use the multipart/form-data type.

There are many ways to create a candidate. Here are some examples:

Provide a JSON representation of a candidate with basic information like candidate name, email, and phone number
Upload just a resume file and specify you'd like the resume parsed. Information parsed from the resume will be used to create the candidate—their name, email, and phone number, for example.

Note: If you are creating a confidential candidate, you must provide a UID for a confidential job posting. Learn more about confidential data in the API.

Note: If candidate is provided in the POST request and resume parsing is requested, the manually provided information will always take precedence over the parsed information from the candidate resume.

All fields are optional, but an empty candidate is not particularly interesting. All query parameters except the perform_as parameter are optional.

If an email address is provided, we will always attempt to dedupe the candidate. If a match is found, we will create a new Opportunity (candidateId) that is linked to the existing matching candidate’s contact (i.e. we never create a new contact, or person, if a match has been found). The existing candidate’s contact data will take precedence over new manually provided information.

Parameters

Specify query parameters in the url (e.g. POST /candidates?perform_as=8d49b010-cc6a-4f40-ace5-e86061c677ed).

perform_as: 8d49b010-cc6a-4f40-ace5-e86061c677ed Required Perform this create on behalf of a specified user. The creator and the owner of this Opportunity will default to the perform_as user. The owner can be explicitly specified in the request body if you want the owner to be a different person.
parse: true Optional If unspecified, assumed to be false. If set to true and a resume file is provided, the resume will be parsed and extracted data will be used to autofill information about the contact such as email and phone number. Any fields manually passed to the endpoint take precedence over any parsed data.
dedupe: true Optional
WARNING: Specifying the dedupe parameter as false is deprecated, and has been sunset effective June 5, 2019. All POST requests to /candidates will treat dedupe as true, regardless of whether this parameter is specified in the request.

Using this 'Create a candidate' endpoint to update existing candidates' links, files, tags, or sources is deprecated and would likely result in the unintended creation of a new Opportunity, or candidateId, linked to the contact with the specified email address.

If you want to update an existing contact's links, use the Update contact links endpoint.
If you want to update an existing Opportunity's files, use the Files endpoints. These endpoints will allow you to add and delete non-resume and non-offer files.
If you want to update an existing Opportunity's tags, use the Update opportunity tags endpoint.
If you want to update an existing candidate's sources, use the Update opportunity sources endpoint.
If you want to find the Opportunities associated with a specific email address, use the email parameter in the List all opportunities endpoint.
perform_as_posting_owner: true Optional If unspecified, assumed to be false and the Opportunity owner will default to the perform_as user. If set to true, an array containing a single posting UID must be passed in via the postings field. The Opportunity owner will be set to that of the posting owner for the single posting. If the posting does not have an owner, the Opportunity owner will default to the perform_as user.

Fields

If a resume file is provided and parsing is enabled, the following fields can be populated with extracted data (although no information is guaranteed to be extracted): name, headline, emails, phones, location, company, and links. The candidate headline is typically composed of prior companies where they worked or schools that they attended.

When using the multipart/form-data encoding, specify each array field individually. For example, for emails specify an emails[] field for each email address. For any fields with nested values, you can specify the values of nest fields using the syntax archive[archivedAt]=1407460071043.

name

Shane SmithStringContact full name

headline

Brickly LLC, Vandelay Industries, Inc, Central PerkStringContact headline, typically a list of previous companies where the contact has worked or schools that the contact has attended This field can also be populated by parsing a provided resume file.

stage

00922a60-7c15-422b-b086-f62000824fd7Stage UIDThe stage ID of this Opportunity's current stage If omitted, the Opportunity will be placed into the "New Lead" stage.

location

OaklandStringContact current location

phones

[{"value":"(123) 456-7891"}]Array of objectsOptionalContact phone number(s)

value: (123) 456-7891StringPhone number
type: StringOptionalNumber type
One of: "mobile", "home", "work", "skype", "other"

emails

shane@exampleq3.comArray of stringsContact emails

links

indeed.com/r/Shane-Smith/0b7c87f6b246d2bcArray of stringsList of Contact links (e.g. personal website, LinkedIn profile, etc.) Should be specified as a JSON array for text/json and as an array field links[] for multipart/form-data encoding.

tags

["San Francisco","Full-time","Support","Customer Success","Customer Success Manager"] Array of strings An array containing a list of tags to apply to this Opportunity. Tags are specified as strings, identical to the ones displayed in the Lever interface. If you specify a tag that does not exist yet, it will be created.

sources

["linkedin"] Array of strings An array containing a list of sources to apply to this Opportunity. Sources are specified as strings, identical to the ones displayed in the Lever interface. If you specify a source that does not exist yet, it will be created.

origin

sourcedStringThe way this Opportunity was added to Lever. Can be one of the following values:

agency
applied
internal
referred
sourced
university

owner

df0adaa6-172c-4cd6-8520-49b203660fe1 User UID The user ID of the owner of this Opportunity. If not specified, Opportunity owner defaults to the perform_as user.

followers

df0adaa6-172c-4cd6-8520-49b203660fe1,ecdb6670-d9f3-4b87-8267-1cde26d1bc42,022d6639-1333-419b-9635-31f93015335f Array of user UIDs An array of user IDs that should be added as followers to this Opportunity. The Opportunity creator will always be added as a follower.

resumeFile

[binary file] Resume file for this Opportunity. Additional files can be uploaded using the file field, but only one resume file may be specified. Only supported in multipart/form-data requests.

files

[binary file] File(s) relating to this opportunity. If uploading multiple files, specify the field as an array instead (use files[] as the field name). Only supported in multipart/form-data requests.

postings

["f2f01e16-27f8-4711-a728-7d49499795a0"] Array of Posting UIDs

WARNING: Specifying multiple posting UIDs in this request will result in a rejected request. To specify multiple postings for a single candidate, send multiple POST requests to this endpoint—each with one posting UID in the array for this postings field, with the same email address of the desired contact.

createdAt

Timestamp[?] To create a historical Opportunity, set the create time for an Opportunity in the past. Default is current datetime. Note that time travel in the other direction is not permitted; you cannot create a candidate in the future.

archived

ObjectOptionalOpportunity archived status You must specify this field if you would like the candidate to be archived for the created Opportunity. This is useful if you'd like to import historical data into Lever and the Opportunities you are creating are not active. The archive reason must be specified for an archived Opportunity (if you just set the archivedAt we will ignore it). If you only specify an archive reason, archivedAt defaults to the current datetime. If you specify an archivedAt datetime, you must specify a createdAt datetime that occurs before archivedAt.

archivedAt: 1417588008760Timestamp[?]Datetime when Opportunity was archived in Lever.
reason: 63dd55b2-a99f-4e7b-985f-22c7bf80ab42Archive reason UIDReason why Opportunity was archived.

Examples

curl -H "Content-Type: application/json" -X POST -u API_KEY: -d '{
  "name": "Shane Smith",
  "headline": "Brickly LLC, Vandelay Industries, Inc, Central Perk",
  "stage": "00922a60-7c15-422b-b086-f62000824fd7",
  "location": "Oakland",
  "phones": [{
    "value": "(123) 456-7891"
  }],
  "emails": [
    "shane@exampleq3.com"
  ],
  "links": [
    "indeed.com/r/Shane-Smith/0b7c87f6b246d2bc"
  ],
  "tags": [
    "San Francisco",
    "Full-time",
    "Support"
  ],
  "sources": [
    "linkedin"
  ],
  "origin": "sourced",
  "owner": "df0adaa6-172c-4cd6-8520-49b203660fe1",
  "followers": [
    "df0adaa6-172c-4cd6-8520-49b203660fe1",
    "ecdb6670-d9f3-4b87-8267-1cde26d1bc42",
    "022d6639-1333-419b-9635-31f93015335f"
  ]
}' https://api.lever.co/v1/candidates?perform_as=8d49b010-cc6a-4f40-ace5-e86061c677ed

{
  "data": {
    "deduped": false,
    "data": {
      "id": "d8da28bd-b3ed-4bd0-a998-5af1a1c0a695",
      "name": "Shane Smith",
      "contact": "8e6763cb-c30a-4ea6-9518-67844c568817",
      "headline": "Brickly LLC, Vandelay Industries, Inc, Central Perk",
      "stage": "2cd82884-ea52-4b41-84be-20b7e8393637",
      "location": "Oakland",
      "phones": [
        {
          "type": "other",
          "value": "(123) 456-7891"
        }
      ],
      "emails": [
        "shane@exampleq3.com"
      ],
      "links": [
        "http://indeed.com/r/Shane-Smith/0b7c87f6b246d2bc"
      ],
      "archived": null,
      "tags": [
        "San Francisco",
        "Full-time",
        "Support"
      ],
      "sources": [
        "Job site"
      ],
      "stageChanges": [
        {
          "toStageId": "2cd82884-ea52-4b41-84be-20b7e8393637",
          "toStageIndex": 0,
          "updatedAt": 1574201580513,
          "userId": "5dc3d8e7-db49-44e5-99e9-fec13a305533"
        }
      ],
      "origin": "applied",
      "owner": "df0adaa6-172c-4cd6-8520-49b203660fe1",
      "followers": [
        "df0adaa6-172c-4cd6-8520-49b203660fe1",
        "ecdb6670-d9f3-4b87-8267-1cde26d1bc42",
        "022d6639-1333-419b-9635-31f93015335f"
      ],
      "applications": [],
      "createdAt": 1574201580513,
      "lastInteractionAt": 1574201580513,
      "lastAdvancedAt": 1574201580513,
      "snoozedUntil": null,
      "urls": {
        "list": "https://hire.lever.dev/candidates",
        "show": "https://hire.lever.dev/candidates/d8da28bd-b3ed-4bd0-a998-5af1a1c0a695"
      },
      "isAnonymized": false,
      "dataProtection": null
    }
  }
}

Update candidate stage

Change an Opportunity's current stage

WARNING: This endpoint is deprecated but maintained for backward compatibility. Use the Update opportunity stage endpoint, which will update the same candidate / opportunity if using the same value for opportunityId as candidateId.

PUT /candidates/:candidate/stage

Parameters

perform_as: 8d49b010-cc6a-4f40-ace5-e86061c677ed Optional Perform this update on behalf of a specified user.

Fields

stage: 00922a60-7c15-422b-b086-f62000824fd7Stage UIDThe stage ID of this Opportunity's current stage

Update candidate archived state

Update an Opportunity's archived state. If an Opportunity is already archived, its archive reason can be changed or if null is specified as the reason, it will be unarchived. If an Opportunity is active, it will be archived with the reason provided.

The requisitionId is optional. If the provided reason maps to ‘Hired’ and a requisition is provided, the Opportunity will be marked as Hired, the active offer is removed from the requisition, and the hired count for the requisition will be incremented.

If a requisition is specified and there are multiple active applications on the profile, you will receive an error. If the specific requisition is closed, you will receive an error. If there is an offer extended, it must be signed, and the offer must be associated with an application for a posting linked to the provided requisition. You can hire a candidate against a requisition without an offer.

WARNING: This endpoint is deprecated but maintained for backward compatibility. Use the Update opportunity archived state endpoint, which will update the same candidate / opportunity if using the same value for opportunityId as candidateId.

PUT /candidates/:candidate/archived

Parameters

perform_as: 8d49b010-cc6a-4f40-ace5-e86061c677ed Optional Perform this update on behalf of a specified user.

Fields

reason: 63dd55b2-a99f-4e7b-985f-22c7bf80ab42 Archive reason UID Reason why this candidate is archived for this Opportunity
cleanInterviews: true Boolean Remove pending interviews from Opportunity when it is archived. If unspecified, defaults to false.
requisitionId: 64e9c86b-03e9-42a5-871c-591d77f45609 Requisition UID Optional Hire a candidate for the Opportunity against the specific requisition. The active offer on the profile must be associated with an application for a posting linked to this requisition.

Update candidate links

WARNING: These endpoints are deprecated but maintained for backward compatibility. Use the Update contact links endpoints, which will update the same contact if using the same value for opportunityId as candidateId.

Add links to a Contact

POST /candidates/:candidate/addLinks

Remove links from a Contact

POST /candidates/:candidate/removeLinks

Parameters

perform_as: 8d49b010-cc6a-4f40-ace5-e86061c677ed Optional Perform this update on behalf of a specified user.

Fields

links: ["indeed.com/r/Shane-Smith/0b7c87f6b246d2bc"] Array of strings Array of links to add or remove from the Contact.

Update candidate tags

Add tags to an Opportunity

WARNING: These endpoints are deprecated but maintained for backward compatibility. Use the Update opportunity tags endpoints, which will update the same candidate / opportunity if using the same value for opportunityId as candidateId.

POST /candidates/:candidate/addTags

Remove tags from an Opportunity

POST /candidates/:candidate/removeTags

Parameters

perform_as: 8d49b010-cc6a-4f40-ace5-e86061c677ed Optional Perform this update on behalf of a specified user.

Fields

tags: ["Infrastructure Engineer"] Array of strings Array of tags to add or remove from this Opportunity.

Update candidate sources

Add sources to an Opportunity

WARNING: These endpoints are deprecated but maintained for backward compatibility. Use the Update opportunity sources endpoints, which will update the same candidate / opportunity if using the same value for opportunityId as candidateId.

POST /candidates/:candidate/addSources

Remove sources from an Opportunity

POST /candidates/:candidate/removeSources

Parameters

perform_as: 8d49b010-cc6a-4f40-ace5-e86061c677ed Optional Perform this update on behalf of a specified user.

Fields

sources: ["Gild"] Array of strings Array of sources to add or remove from this Opportunity.

Add candidate postings

Add postings to an Opportunity

WARNING: This endpoint is deprecated. To add an opportunity for a posting to an existing candidate, use the Create an opportunity endpoint, specifying the email address of the desired candidate. Alternatively, to submit an application on behalf of a candidate, use the Apply to a posting endpoint along with the email address of the desired candidate.

POST /candidates/:candidate/addPostings

Parameters

perform_as: 8d49b010-cc6a-4f40-ace5-e86061c677ed Required Perform this update on behalf of a specified user.

Fields

postings: ["f2f01e16-27f8-4711-a728-7d49499795a0"] Array of Posting UIDs Array of posting UIDs to be applied to this Opportunity.