/candidates – list

Description

Lists candidates for a given company.

Request

GET https://api.smartrecruiters.com/candidates?q={query}&limit={limit}&offset={offset}&jobId={jobId}&location={location}&averageRating={averageRating}&status={status}&tag={tag}

Path Parameters

n/a

Query Parameters

name type description
q string keyword search on all candidate fields; case insensitive; e.g. java developer
limit integer number of records to return. max value is 100
offset integer number of records to skip while processing result; e.g. 10
jobId integer job filter to display candidates who applied for a job [id]; can be used repeatedly; e.g. 78d3ef91-8868-4ff3-b35d-9debf9d6f31f
location string location keyword search which looks up a string in a candidate’s location data; can be used repeatedly; case insensitive; e.g. Krakow
averageRating integer average rating filter to display candidates with a specific average rating; can be used repeatedly; e.g. 4
status string candidate’s status filter in a context of a job; can be used repeatedly; case insensitive; Available statuses: LEAD, NEW, IN_REVIEW, INTERVIEW, OFFERED, HIRED, REJECTED, WITHDRAWN, TRANSFERRED
tag string tag assigned to a candidate; can be used repeatedly; case insensitive; e.g. fluent english

All parameters which can be used repeatedly should follow the below notation example:

curl -i -H "X-SmartToken: abc123" -X GET https://api.smartrecruiters.com/v1/candidates?status=New&status=Lead&tag=j2ee&tag=sql

Request Body

n/a

Response Body

ListResult containing list of Candidate objects. However, some fields might not be set. To get full object use ‘details’ property.

Example request

curl -i -H "X-SmartToken: abc123" -X GET https://api.smartrecruiters.com/candidates?q=developer

Example response

{
  "totalFound": 2,
  "content": [
    {
      "id": "788dfc72-a6eb-441b-837f-d7c39efb3f04",
      "firstName": "Witek",
      "lastName": "Pulawski",
      "email": "witek.pulawski@test.com",
      "averageRating": 3,
      "primaryAssignment": {
        "job": {
          "id": "58ec72e0-05cd-48dc-9a9b-0e0273cbb97c",
          "title": "Smart Developer",
          "actions": {
            "details": {
              "url": "https://api.smartrecruiters.com/jobs/58ec72e0-05cd-48dc-9a9b-0e0273cbb97c",
              "method": "GET"
            }
          }
        },
        "status": "IN_REVIEW"
      },
      "actions": {
        "details": {
          "url": "https://api.smartrecruiters.com/candidates/788dfc72-a6eb-441b-837f-d7c39efb3f04",
          "method": "GET"
        }
      }
    },
    {
      "id": "0b051bf5-3bc5-4ba3-918b-9fbe5dc9e145",
      "firstName": "John",
      "lastName": "Doe",
      "email": "j.doe@smartrecruiters.com",
      "primaryAssignment": {
        "job": {
          "id": "6a07afa3-cd71-4576-b603-7fc03dd5f5ab",
          "title": "Smart Developer",
          "actions": {
            "details": {
              "url": "https://api.smartrecruiters.com/jobs/6a07afa3-cd71-4576-b603-7fc03dd5f5ab",
              "method": "GET"
            }
          }
        },
        "status": "IN_REVIEW"
      },
      "actions": {
        "details": {
          "url": "https://api.smartrecruiters.com/candidates/0b051bf5-3bc5-4ba3-918b-9fbe5dc9e145",
          "method": "GET"
        }
      }
    }
  ]
}