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
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 the Opportunity was archived in Lever.
reason
63dd55b2-a99f-4e7b-985f-22c7bf80ab42Archive reason UIDRequiredReason why the 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.
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.
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.
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.sandbox.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.sandbox.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 the Opportunity was archived in Lever.
reason
63dd55b2-a99f-4e7b-985f-22c7bf80ab42Archive reason UIDRequiredReason why the 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.sandbox.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.

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.