--- updatedAt: 2026-05-28T05:27:12.000Z agentTools: projectIndex: https://developers.smartrecruiters.com/llms.txt --- # Search candidates Only candidates matching all specified criteria and having at least one job application are returned. # OpenAPI definition ````json { "openapi": "3.0.1", "info": { "version": "1", "title": "Candidates API", "contact": { "name": "SmartRecruiters", "url": "https://developers.smartrecruiters.com" } }, "tags": [ { "name": "candidates" } ], "paths": { "/candidates": { "get": { "responses": { "200": { "description": "Candidates matching search criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Candidates" } } }, "headers": { "Link": { "schema": { "type": "string" }, "description": "Links to related resources, in the format defined by\n[RFC 5988](https://tools.ietf.org/html/rfc5988#section-5).\nThis will include a link with relation type `next` to the\nnext page (containing `pageId` query parameter), if there is a next page.\n" } } }, "400": { "description": "with codes\n* **FIELDS_CRITERIA_SIZE_VIOLATED** when number of elements of query param `propertyId` is not\n equal to number of elements of query param `propertyValueId`\n* **SOURCES_CRITERIA_SIZE_VIOLATED** when number of elements of query param `sourceType` is not\n equal to number of elements of query param `sourceSubType` or not\n equal to number of elements of query param `sourceValueId`\n* **SCREENING_QUESTIONS_CRITERIA_SIZE_VIOLATED** when number of elements of query param `questionCategory` is not\n equal to number of elements of query param `questionFieldId` or not\n equal to number of elements of query param `questionFieldValueId`\n* **ONBOARDING_STATUS_NOT_ACTIVE** when Onboarding Status candidate property is not activated or user's\n company does not have candidate property feature, but user has requested to search candidates by\n onboardingStatus query parameter\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Only candidates matching all specified criteria and having at least one job application are returned.", "tags": [ "candidates" ], "summary": "Search candidates", "operationId": "candidates.all", "security": [ { "key": [] }, { "oauth": [ "candidates_read" ] } ], "parameters": [ { "in": "query", "description": "keyword search, for more information see [SmartRecruiters Help Center](https://customers.smartrecruiters.com/kb/articles/4697-searching-candidates-via-candidate-api)", "name": "q", "schema": { "type": "string" } }, { "in": "query", "description": "number of elements to return. max value is 100", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "in": "query", "description": "page identifier of elements to return\n\nThe `pageId` param can be used to fetch multiple page response, in case\nthe number of results is higher than max number of elements to return (specified in the `limit` parameter).\nThe `pageId` should not be present when requesting the first page of results.\nThe pageId of the following page is returned either in the `nextPageId` property, or is available\nin the HTTP header `Link` value of relation type `next`.\nExample of the `Link` header:\n```\n; rel=\"next\"\n```\n", "name": "pageId", "schema": { "type": "string" } }, { "in": "query", "description": "job filter to display candidates who applied for a job [id]; can be used repeatedly;", "name": "jobId", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "description": "location keyword search which looks up a string in a candidate’s location data; can be used repeatedly; case insensitive; e.g. Krakow", "name": "location", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "description": "average rating filter to display candidates with a specific average rating (integer); can be used repeatedly; e.g. 4", "name": "averageRating", "deprecated": true, "explode": true, "schema": { "type": "array", "items": { "type": "integer", "maximum": 5, "minimum": 1 } } }, { "in": "query", "description": "candidate’s status filter in a context of a job; can be used repeatedly", "name": "status", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "LEAD", "NEW", "IN_REVIEW", "INTERVIEW", "OFFERED", "HIRED", "REJECTED", "WITHDRAWN", "TRANSFERRED" ] } } }, { "in": "query", "description": "candidate’s consent status filter; can be used repeatedly", "name": "consentStatus", "explode": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsentStatus" } } }, { "in": "query", "description": "candidate’s sub-status filter in a context of a job. Works only in a correlation with a set value for the \"status\" field.", "name": "subStatus", "schema": { "type": "string" } }, { "in": "query", "description": "tag assigned to a candidate; can be used repeatedly; case insensitive; e.g. fluent english", "name": "tag", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "description": "ISO8601-formatted time boundaries for the candidate update time, Format: yyyy-MM-ddTHH:mm:ss.SSSZZ", "name": "updatedAfter", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "description": "candidate's onboarding status", "name": "onboardingStatus", "schema": { "type": "string", "enum": [ "READY_TO_ONBOARD", "ONBOARDING_SUCCESSFUL", "ONBOARDING_FAILED" ] } }, { "in": "query", "description": "candidate's property id (1-N). Filter candidates by selection type application fields. Each `propertyId` is paired with `propertyValueId` at the same array index. Both arrays must have equal length (error code FIELDS_CRITERIA_SIZE_VIOLATED if not). Multiple values for the same property are combined with OR, different properties with AND.", "name": "propertyId", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "default": [] } }, { "in": "query", "description": "candidate's property value id (1-N). Paired with `propertyId` by array index. Both arrays must have equal length.", "name": "propertyValueId", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "default": [] } }, { "in": "query", "description": "candidate's source type (1-N)", "name": "sourceType", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "default": [] } }, { "in": "query", "description": "candidate's source subtype (1-N)", "name": "sourceSubType", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "default": [] } }, { "in": "query", "description": "candidate's source value id (1-N)", "name": "sourceValueId", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "default": [] } }, { "in": "query", "description": "screening question category (1-N)", "name": "questionCategory", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "default": [] } }, { "in": "query", "description": "screening question field id (1-N)", "name": "questionFieldId", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "default": [] } }, { "in": "query", "description": "screening question field value id (1-N)", "name": "questionFieldValueId", "explode": true, "schema": { "type": "array", "items": { "type": "string" }, "default": [] } } ] } } }, "components": { "securitySchemes": { "key": { "type": "apiKey", "in": "header", "name": "x-smarttoken" }, "oauth": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://www.smartrecruiters.com/identity/oauth/allow", "tokenUrl": "https://api.smartrecruiters.com/identity/oauth/token", "scopes": { "candidates_read": "Access Candidates", "candidates_create": "Create Candidates", "candidates_offers_read": "Access Offer Terms", "candidates_manage": "Manage Candidate Status and Properties", "candidate_status_read": "Access Candidate's status", "candidates_parse_resume": "Access Resume Parsing" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "Error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "Candidates": { "type": "object", "required": [ "limit", "totalFound", "content" ], "properties": { "limit": { "type": "integer" }, "nextPageId": { "type": "string" }, "totalFound": { "type": "integer" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" } } } }, "Candidate": { "type": "object", "required": [ "id", "internal", "firstName", "lastName", "createdOn", "actions" ], "properties": { "id": { "type": "string" }, "internal": { "type": "boolean", "description": "true, if the candidate has at least one internal application" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "createdOn": { "type": "string", "format": "date-time" }, "updatedOn": { "type": "string", "format": "date-time" }, "location": { "$ref": "#/components/schemas/CandidateLocation" }, "averageRating": { "type": "number", "deprecated": true }, "tags": { "type": "array", "items": { "type": "string" } }, "consent": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ConsentStatus" } } }, "primaryAssignment": { "type": "object", "required": [ "job", "status" ], "properties": { "job": { "type": "object", "required": [ "id", "title", "actions" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "actions": { "type": "object", "required": [ "details" ], "properties": { "details": { "$ref": "#/components/schemas/Action" } } } } }, "status": { "$ref": "#/components/schemas/CandidateStatusEnum" }, "subStatus": { "type": "string" } } }, "secondaryAssignments": { "type": "array", "items": { "type": "object", "required": [ "job" ], "properties": { "job": { "type": "object", "required": [ "id", "actions" ], "properties": { "id": { "type": "string" }, "actions": { "type": "object", "required": [ "details" ], "properties": { "details": { "$ref": "#/components/schemas/Action" } } } } } } } }, "actions": { "type": "object", "required": [ "details", "properties" ], "properties": { "details": { "$ref": "#/components/schemas/Action" }, "properties": { "$ref": "#/components/schemas/Action" } } } } }, "CandidateLocation": { "type": "object", "properties": { "country": { "type": "string", "minLength": 1 }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "regionCode": { "type": "string" }, "region": { "type": "string" }, "city": { "type": "string", "minLength": 1 }, "lat": { "type": "number", "format": "float" }, "lng": { "type": "number", "format": "float" } } }, "CandidateStatusEnum": { "type": "string", "enum": [ "LEAD", "NEW", "IN_REVIEW", "INTERVIEW", "OFFERED", "HIRED", "REJECTED", "WITHDRAWN", "TRANSFERRED" ] }, "Action": { "type": "object", "required": [ "url", "method" ], "properties": { "url": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "OPTIONS", "DELETE", "HEAD", "CONNECT" ] } } }, "ConsentStatus": { "type": "string", "description": "* **REQUIRED** - no request for consent yet,\n* **PENDING** - consent requested,\n* **ACQUIRED** - consent provided by a candidate\n", "enum": [ "REQUIRED", "PENDING", "ACQUIRED" ] } } }, "servers": [ { "url": "https://api.smartrecruiters.com" } ] } ````