--- updatedAt: 2026-08-11T11:40:18.000Z agentTools: projectIndex: https://developer.personio.de/llms.txt --- # List all candidates. Returns a list of candidates for an authorized company, sorted by last updated date, newest first. The endpoint supports pagination. The endpoint requires the `personio:recruiting:read` scope. > 📘 Note > > Currently, the Candidates and Applications API does not return custom attributes and tags. > Please consider this limitation when using the API. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Recruiting", "description": "Collection of endpoints to manage recruiting applications.", "version": "2.0.0" }, "servers": [ { "url": "https://api.personio.de" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v2/recruiting/candidates": { "get": { "summary": "List all candidates.", "description": "Returns a list of candidates for an authorized company, sorted by last updated date, newest first.\nThe endpoint supports pagination. The endpoint requires the `personio:recruiting:read` scope.\n\n> 📘 Note\n>\n> Currently, the Candidates and Applications API does not return custom attributes and tags.\n> Please consider this limitation when using the API.", "tags": [ "Candidates" ], "parameters": [ { "$ref": "#/paths/~1v2~1recruiting~1jobs/get/parameters/0" }, { "$ref": "#/paths/~1v2~1recruiting~1jobs/get/parameters/1" }, { "description": "Return candidates updated before given time.\nMutually exclusive with `updated_at.gt`.", "name": "updated_at.lt", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "description": "Return candidates updated after given time.\nMutually exclusive with `updated_at.lt`.", "name": "updated_at.gt", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "description": "Return candidates with given email.", "name": "email", "required": false, "in": "query", "schema": { "type": "string", "example": "john.doe@example.com" } } ], "x-path-examples": { "200 List all candidates": { "value": "/v2/recruiting/candidates" }, "200 List all candidates with non-default limit": { "value": "/v2/recruiting/candidates", "query": "limit=150" }, "200 List all candidates after given date": { "value": "/v2/recruiting/candidates", "query": "updated_at.gt=2025-02-20T13:19:40" }, "200 List all candidates before given date": { "value": "/v2/recruiting/candidates", "query": "updated_at.lt=2025-02-20T13:19:40" }, "200 List all candidates by email": { "value": "/v2/recruiting/candidates", "query": "email=test@personio.de" }, "200 List candidates by cursor": { "value": "/v2/recruiting/candidates", "query": "cursor=cur_15sdwf2eIvLilN2dKFh211Js" }, "400 List candidates using wrong pagination value": { "value": "/v2/recruiting/candidates", "query": "limit=400" }, "403 Forbidden response": { "value": "/v2/recruiting/candidates" } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_data": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" } }, "_meta": { "$ref": "#/paths/~1v2~1recruiting~1jobs/get/responses/200/content/application~1json/schema/properties/_meta" } } }, "examples": { "200 List all candidates": { "$ref": "#/components/examples/CandidateListResponse" }, "200 List all candidates with non-default limit": { "$ref": "#/components/examples/CandidateListResponse" }, "200 List all candidates after given date": { "$ref": "#/components/examples/CandidateListResponse" }, "200 List all candidates before given date": { "$ref": "#/components/examples/CandidateListResponse" }, "200 List all candidates by email": { "$ref": "#/components/examples/CandidateListResponse" }, "200 List candidates by cursor": { "$ref": "#/components/examples/CandidateListByCursorResponse" } } } } }, "400": { "description": "Bad request.", "content": { "application/problem+json": { "schema": { "$ref": "#/paths/~1v2~1recruiting~1jobs/get/responses/400/content/application~1problem+json/schema" }, "examples": { "400 List candidates using wrong pagination value": { "$ref": "#/components/examples/InvalidFilterValue" } } } } }, "403": { "$ref": "#/components/responses/ForbiddenResponse" } } } }, "/v2/recruiting/jobs": { "get": { "summary": "List all jobs.", "description": "Returns a list of jobs for an authorized company, sorted by last updated date, newest first.\nThe endpoint supports pagination.\nThe endpoint requires the `personio:recruiting:read` scope.", "tags": [ "Jobs" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "example": 100, "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "description": "The amount of resources to be returned per one request. It can range between 1 and 200, and the default is 100." }, { "in": "query", "name": "cursor", "example": "cur_82sQwR2eZvKilo2duNh219Kw", "required": false, "schema": { "type": "string" }, "description": "The pagination cursor to navigate over to the next list of resources. If you pass a specific limit to your request, or you rely on the default value of the number of resources to be returned, then your subsequent call has to include the cursor in order to retrieve the next list of resources. If cursor is missing, the first page is returned." }, { "description": "Return jobs updated before given time.\nMutually exclusive with `updated_at.gt`.", "name": "updated_at.lt", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "description": "Return jobs updated after given time.\nMutually exclusive with `updated_at.lt`.", "name": "updated_at.gt", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "x-path-examples": { "200 List all jobs": { "value": "/v2/recruiting/jobs" }, "200 List all jobs with non-default limit": { "value": "/v2/recruiting/jobs", "query": "limit=150" }, "200 List all jobs after given date": { "value": "/v2/recruiting/jobs", "query": "updated_at.gt=2025-02-20T13:19:40" }, "200 List all jobs before given date": { "value": "/v2/recruiting/jobs", "query": "updated_at.lt=2025-02-20T13:19:40" }, "200 List jobs by cursor": { "value": "/v2/recruiting/jobs", "query": "cursor=cur_15sdwf2eIvLilN2dKFh211Js" }, "400 List jobs using wrong pagination value": { "value": "/v2/recruiting/jobs", "query": "limit=400" }, "400 List jobs using invalid cursor": { "value": "/v2/recruiting/jobs", "query": "cursor=invalid-cursor" }, "403 Forbidden response": { "value": "/v2/recruiting/jobs" } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "_meta": { "description": "This object represents the metadata information for an object. It's a set of arbitrary key/value attributes such as `links`.", "type": "object", "readOnly": true, "properties": { "links": { "type": "object", "additionalProperties": { "description": "This objects represents a hyperlink.", "type": "object", "readOnly": true, "properties": { "href": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "example": { "links": { "self": { "href": "https://api.personio.de/v2/person?cursor=" } } } } } } } }, "examples": { "200 List all jobs": { "$ref": "#/components/examples/JobListResponse" }, "200 List all jobs with non-default limit": { "$ref": "#/components/examples/JobListResponse" }, "200 List all jobs after given date": { "$ref": "#/components/examples/JobListResponse" }, "200 List all jobs before given date": { "$ref": "#/components/examples/JobListResponse" }, "200 List jobs by cursor": { "$ref": "#/components/examples/JobListByCursorResponse" } } } } }, "400": { "description": "Bad request.", "content": { "application/problem+json": { "schema": { "type": "object", "description": "This object represents an error response.", "properties": { "personio_trace_id": { "type": "string", "example": "aswo3f-a202lfso-312123sld-1230ddd", "description": "A unique ID that was created for this error." }, "timestamp": { "type": "string", "format": "date-time", "example": "2021-05-28T11:17:30.000Z", "description": "The timestamp of when the error occurred." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "example": "Not found", "description": "The title of the error." }, "detail": { "type": "string", "example": "The requested resource was not found.", "description": "A short description about the error." }, "type": { "type": "string", "format": "uri", "example": "https://developer.personio.de/reference/errors#common.requested_resource_not_found", "description": "A link to the developer hub where more information can be found for the encountered error." }, "_meta": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "examples": { "400 List jobs using wrong pagination value": { "$ref": "#/components/examples/InvalidFilterValue" }, "400 List jobs using invalid cursor": { "$ref": "#/components/examples/InvalidFilterValue" } } } } }, "403": { "$ref": "#/components/responses/ForbiddenResponse" } } } } }, "components": { "responses": { "ForbiddenResponse": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/paths/~1v2~1recruiting~1jobs/get/responses/400/content/application~1problem+json/schema" }, "examples": { "403 Forbidden response": { "$ref": "#/components/examples/ForbiddenResponse" } } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Candidate": { "description": "Recruiting candidate object (aka 'applicant').", "type": "object", "required": [ "id", "company_id", "first_name", "last_name", "email" ], "properties": { "id": { "description": "The unique identifier of a candidate.", "type": "string", "readOnly": true, "example": "9823749" }, "company": { "description": "The company, the candidate's application is for.", "type": "object", "properties": { "id": { "description": "The unique identifier of a company.", "readOnly": true, "type": "string", "example": "324" } } }, "applications": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationRef" } }, "first_name": { "description": "The Candidate's first name.", "type": "string", "example": "John" }, "last_name": { "description": "The Candidate's last name.", "type": "string", "example": "Doe" }, "email": { "description": "The Candidate's email.", "type": "string", "format": "email" }, "gender": { "description": "The Candidate's gender.", "type": "string", "enum": [ "MALE", "FEMALE", "DIVERSE", "UNDEFINED" ], "example": "FEMALE" }, "birthday": { "description": "The Candidate's birth date.", "type": "string", "format": "date" }, "phone": { "description": "The Candidate's phone number.", "type": "string", "example": "+4915212345678" }, "location": { "description": "The Candidate's location.", "type": "string" }, "available_from": { "description": "The Candidate's availability.", "type": "string", "example": "Jan 2024" }, "linkedin_profile": { "description": "The Candidate's link to LinkedIn profile.", "type": "string", "example": "https://www.linkedin.com/in/much-candidate-very-awesome/" }, "created_at": { "description": "Creation date of a candidate.", "readOnly": true, "type": "string", "format": "date-time" }, "updated_at": { "description": "Last modification date of a candidate.", "readOnly": true, "type": "string", "format": "date-time" }, "_meta": { "$ref": "#/paths/~1v2~1recruiting~1jobs/get/responses/200/content/application~1json/schema/properties/_meta" } } }, "ApplicationRef": { "description": "Recruiting application.", "type": "object", "required": [ "id", "application_date" ], "properties": { "id": { "description": "The unique identifier of an application.", "type": "string", "readOnly": true, "example": "9823749" }, "application_date": { "description": "Date when the application was submitted.", "readOnly": true, "type": "string", "format": "date" }, "_meta": { "$ref": "#/paths/~1v2~1recruiting~1jobs/get/responses/200/content/application~1json/schema/properties/_meta" } } } }, "examples": { "ForbiddenResponse": { "value": { "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd", "timestamp": "2021-05-28T11:17:30+00:00", "errors": [ { "title": "Insufficient scopes", "detail": "Required scope is missing from token", "type": "https://developer.personio.de/v2.0/page/public-api-error-codes#credentialsoauth2invalid_scope" } ] } }, "InvalidFilterValue": { "value": { "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd", "timestamp": "2021-05-28T11:17:30+00:00", "errors": [ { "title": "Bad request", "detail": "Provided request parameters are invalid.", "type": "https://developer.personio.de/v2.0/page/public-api-error-codes#common.bad_request" } ] } }, "CandidateListResponse": { "value": { "_data": [ { "id": "495039", "company": { "id": "10567" }, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "gender": "MALE", "birthday": "1989-10-15", "phone": "+4915212345678", "location": "Berlin", "available_from": "Jan 2024", "applications": [ { "id": "3223455", "application_date": "2023-12-11", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/applications/3223455" } } } }, { "id": "5293879", "application_date": "2023-12-15", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/applications/5293879" } } } } ], "linkedin_profile": "https://www.linkedin.com/in/much-candidate-very-awesome/", "created_at": "2023-12-11T14:50:17Z", "updated_at": "2023-12-11T14:50:17Z", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/candidates/495039" } } } }, { "id": "3459829", "company": { "id": "10567" }, "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "gender": "FEMALE", "birthday": "1991-12-31", "phone": "+4915240983405", "location": "Stuttgart", "available_from": "Summer", "applications": [ { "id": "3409284", "application_date": "2023-12-11", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/applications/3409284" } } } }, { "id": "23985792", "application_date": "2023-12-15", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/applications/23985792" } } } } ], "linkedin_profile": "https://www.linkedin.com/in/i-am-cool/", "created_at": "2023-12-11T14:50:17Z", "updated_at": "2023-12-11T14:50:17Z", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/candidates/3459829" } } } } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/candidates" }, "next": { "href": "https://api.personio.de/v2/recruiting/candidates?cursor=cur_234ls0f02lalfdd" } } } } }, "CandidateListByCursorResponse": { "value": { "_data": [ { "id": "495039", "company": { "id": "10567" }, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "gender": "MALE", "birthday": "1989-10-15", "phone": "+4915212345678", "location": "Berlin", "available_from": "Jan 2024", "applications": [ { "id": "3223455", "application_date": "2023-12-11", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/applications/3223455" } } } }, { "id": "5293879", "application_date": "2023-12-15", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/applications/5293879" } } } } ], "linkedin_profile": "https://www.linkedin.com/in/much-candidate-very-awesome/", "created_at": "2023-12-11T14:50:17Z", "updated_at": "2023-12-11T14:50:17Z", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/candidates/495039" } } } }, { "id": "3459829", "company": { "id": "10567" }, "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "gender": "FEMALE", "birthday": "1991-12-31", "phone": "+4915240983405", "location": "Stuttgart", "available_from": "Summer", "applications": [ { "id": "4203948", "application_date": "2023-12-11", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/applications/4203948" } } } }, { "id": "4304980", "application_date": "2023-12-15", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/applications/4304980" } } } } ], "linkedin_profile": "https://www.linkedin.com/in/i-am-cool/", "created_at": "2023-12-11T14:50:17Z", "updated_at": "2023-12-11T14:50:17Z", "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/candidates/3459829" } } } } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/candidates?cursor=cur_15sdwf2eIvLilN2dKFh211Js" }, "next": { "href": "https://api.personio.de/v2/recruiting/candidates?cursor=cur_234ls0f02lalfddQrefvA2fe" } } } } } } } } ```