Candidates

This is an object representing your candidate and prospect in SmartRecruiters. The Candidates API enables you to create candidate profiles, retrieve candidate information and assign candidates to a job to create applications to keep track of each candidate's progress in the hiring process.

{
  "id": "string",
  "internal": true,
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phoneNumber": "string",
  "location": {
    "country": "string",
    "countryCode": "string",
    "regionCode": "string",
    "region": "string",
    "city": "string",
    "lat": 0,
    "lng": 0
  },
  "web": {
    "skype": "string",
    "linkedin": "string",
    "facebook": "string",
    "twitter": "string",
    "website": "string"
  },
  "createdOn": "2021-07-23T10:13:15.871Z",
  "updatedOn": "2021-07-23T10:13:15.871Z",
  "tags": [
    "string"
  ],
  "averageRating": 0,
  "education": [
    {
      "institution": "string",
      "degree": "string",
      "major": "string",
      "current": true,
      "location": "string",
      "startDate": "string",
      "endDate": "string",
      "description": "string"
    }
  ],
  "experience": [
    {
      "title": "string",
      "company": "string",
      "current": true,
      "startDate": "string",
      "endDate": "string",
      "location": "string",
      "description": "string"
    }
  ],
  "primaryAssignment": {
    "job": {
      "id": "string",
      "title": "string",
      "actions": {
        "details": {
          "url": "string",
          "method": "GET"
        },
        "positionDetails": {
          "url": "string",
          "method": "GET"
        }
      }
    },
    "status": "LEAD",
    "subStatus": "string",
    "startsOn": "2021-07-23T10:13:15.871Z",
    "source": "string",
    "reasonOfRejection": {
      "id": "string",
      "label": "string"
    },
    "reasonOfWithdrawal": {
      "id": "string",
      "label": "string"
    },
    "actions": {
      "sourceDetails": {
        "url": "string",
        "method": "GET"
      }
    }
  },
  "secondaryAssignments": [
    {
      "job": {
        "id": "string",
        "title": "string",
        "actions": {
          "details": {
            "url": "string",
            "method": "GET"
          },
          "positionDetails": {
            "url": "string",
            "method": "GET"
          }
        }
      },
      "status": "LEAD",
      "subStatus": "string",
      "startsOn": "2021-07-23T10:13:15.871Z",
      "source": "string",
      "reasonOfRejection": {
        "id": "string",
        "label": "string"
      },
      "reasonOfWithdrawal": {
        "id": "string",
        "label": "string"
      },
      "actions": {
        "sourceDetails": {
          "url": "string",
          "method": "GET"
        }
      }
    }
  ],
  "actions": {
    "properties": {
      "url": "string",
      "method": "GET"
    },
    "attachments": {
      "url": "string",
      "method": "GET"
    },
    "consent": {
      "url": "string",
      "method": "GET"
    },
    "consents": {
      "url": "string",
      "method": "GET"
    }
  }
}

The candidate object

id string
Unique candidate identifier

Internal boolean
Whether the candidate is an internal candidate. Set internal=true if the candidate is an internal employee

firstName string
The candidate's first name

lastName string
The candidate's last name

email string
The candidate's email address. Email communication with the candidate such interview invitation and direct conversations will be send to this email address.

location object
The candidate's location information

  • location.country string
    Name of the candidate's country of residence
  • location.countryCode string
    Two-letter, ISO 3166-1 alpha-2 formatted country code of the candidate's country of residence
  • location.regionCode string
    Four-letter ISO 3166-2:US formatted region code for regions in the United State. The regionCode field is not required and not recommend to be used for regions outside of the United States.
  • location.region string
    The candidate's area of residence description, such as state, province or voivodeship.
  • location.city string
    The candidate's city of residence
  • location.lat float
    ISO 6709 formatted latitude of the candidate's residence address
  • location.lng string
    ISO 6709 formatted longitude of the candidate's residence address

web object
The candidate's profiles from different social media sites or platforms

  • web.skype string
    The candidate's Skype profile URI
  • web.linkedin string
    The candidate's LinkedIn profile URI
  • web.facebook string
    The candidate's Facebook profile URI
  • web.twitter string
    The candidate's Twitter profile URI
  • web.website string
    Additional URI or site of the candidate

createdOn date-time
The time that the candidate object was created. The value should be ISO8601-formatted date with the following format: yyyy-MM-ddTHH:mm:ss.SSSZZ.

updatedOn date-time
The latest time that a property or field of the candidate object is modified. The value should be ISO8601-formatted date with the following format: yyyy-MM-ddTHH:mm:ss.SSSZZ.

tag array of strings
Category labels that can be used to identify group of candidates

averageRating number
The average review score of the candidate rated by interviewers across all of the candidate's applications. The value should be a number between 1 and 5.

education array of objects
The candidate's education history

  • education.institution string
    The name of the institution
  • education.degree string
    The degree, diploma or certificate the candidate obtained from the institution
  • education.major string
    The specialized area of study of the candidate's degree, diploma or certificate
  • education.current boolean
    Whether the candidate is currently pursuing the degree. Set education.current=true if the candidate is currently pursuing the degree
  • education.location string
    The address of the institution
  • education.startDate string
    The start date of the candidate pursue of the degree. The value should be ISO8601-formatted date with the following format: yyyy-MM-dd
  • education.endDate string
    The last date of the candidate pursue of the degree. The value should be ISO8601-formatted date with the following format: yyyy-MM-dd
  • education.description string
    Additional description of the eduction record

experience array of objects
The candidate's work experience

  • experience.title string
    The job title of the candidate's previous role
  • experience.company string
    The name of the candidate's previous company
  • experience.current boolean
    Whether the candidate still holds the role. Set experience.current=true if the candidate is still working on the role.
  • experience.startDate string
    The start date of the candidate first held the role. The value should be ISO8601-formatted date with the following format: yyyy-MM-dd
  • experience.endDate string
    The last date of the candidate is employed for the role. The value should be ISO8601-formatted date with the following format: yyyy-MM-dd
  • experience.location string
    The address of the institution
  • experience.description string
    Additional description of the work record

primaryAssignment objects
The most recently updated application associate to the candidate.

  • primaryAssignment.job array of objects
    The job object of the most recently updated application
    • primaryAssignment.job.id string
      Unique job identifier of the job of the most recently updated application
    • primaryAssignment.job.title string
      The title of the job of the most recently updated application
    • primaryAssignment.job.actions array of objects
      Resource location of the job and method to retrieve the resource
      • primaryAssignment.job.actions.details object
        Details of the job of the most recently updated application
        • primaryAssignment.job.actions.details.url string
        • primaryAssignment.job.actions.details.method string
      • primaryAssignment.job.actions.positionDetails object
        Details of the position of the job of the most recently updated application
        • primaryAssignment.job.actions.positionDetails.url string
        • primaryAssignment.job.actions.positionDetails.method string
    • primaryAssignment.status string
      The application status of the most recently updated application
    • primaryAssignment.subStatus string
      The application sub status (also known as hiring step) of the most recently updated application
    • primaryAssignment.startsOn date-time
      The start date when the application is created
    • primaryAssignment.source string
      The source information of the most recently updated application
    • primaryAssignment.reasonOfRejection object
      The reason for rejecting the application.
      • primaryAssignment.reasonOfRejection.id string
        Unique rejection reason identifier. Possible values can be retrieved in via the Configuration API
      • primaryAssignment.reasonOfRejection.label string
        The reason of rejection label. Possible values can be retrieved in via the Configuration API
    • primaryAssignment.reasonOfWithdrawal object
      The reason for the candidate withdrawing the application.
      • primaryAssignment.reasonOfWithdrawal.id string
        Unique withdrawal reason identifier. Possible values can be retrieved in via the Configuration API
      • primaryAssignment.reasonOfWithdrawal.label string
        The reason of withdrawal label. Possible values can be retrieved in via the Configuration API
    • primaryAssignment.actions object
      • primaryAssignment.actions.sourceDetails object
        Resource location of the application source information and method to retrieve the resource
        • primaryAssignment.actions.sourceDetails.url string
        • primaryAssignment.actions.sourceDetails.method string

secondaryAssignment array of objects
All other applications associate to the candidate except the most recently updated application

  • secondaryAssignment.job array of objects
    The job object of an application
    • secondaryAssignment.job.id string
      Unique job identifier of an application
    • secondaryAssignment.job.title string
      The title of the job of the application
    • secondaryAssignment.job.actions array of objects
      Resource location of the job and method to retrieve the resource
      • secondaryAssignment.job.actions.details object
        Details of the job of the application
        • secondaryAssignment.job.actions.details.url string
        • secondaryAssignment.job.actions.details.method string
      • secondaryAssignment.job.actions.positionDetails object
        Details of the position of the job of the application
        • secondaryAssignment.job.actions.positionDetails.url string
        • secondaryAssignment.job.actions.positionDetails.method string
    • secondaryAssignment.status string
      The application status of the application
    • secondaryAssignment.subStatus string
      The application sub status (also known as hiring step) of the application
    • secondaryAssignment.startsOn date-time
      The start date when the application is created
    • secondaryAssignment.source string
      The source information of the application
    • secondaryAssignment.reasonOfRejection object
      The reason for rejecting the application.
      • secondaryAssignment.reasonOfRejection.id string
        Unique rejection reason identifier. Possible values can be retrieved in via the Configuration API
      • secondaryAssignment.reasonOfRejection.label string
        The reason of rejection label. Possible values can be retrieved in via the Configuration API
    • secondaryAssignment.reasonOfWithdrawal object
      The reason for the candidate withdrawing the application.
      • secondaryAssignment.reasonOfWithdrawal.id string
        Unique withdrawal reason identifier. Possible values can be retrieved in via the Configuration API
      • secondaryAssignment.reasonOfWithdrawal.label string
        The reason of withdrawal label. Possible values can be retrieved in via the Configuration API
    • secondaryAssignment.actions object
      • secondaryAssignment.actions.sourceDetails object
        Resource location of the application source information and method to retrieve the resource
        • secondaryAssignment.actions.sourceDetails.url string
        • secondaryAssignment.actions.sourceDetails.method string

actions objects
Resource location of the additional candidate information and method to retrieve those resources

  • actions.properties objects
    Resource location of candidate properties and method to retrieve the resource
    • actions.properties.url string
    • actions.properties.method string
  • actions.attachments objects
    Resource location of application attachment and method to retrieve the resource
    • actions.attachments.url string
    • actions.attachments.method string
  • actions.consent objects
    Resource location of candidate consent and method to retrieve the resource
    • actions.consent.url string
    • actions.consent.method string
  • actions.consents objects
    Resource location of candidate consent decisions and method to retrieve the resource
    • actions.consents.url string
    • actions.consents.method string