---
updatedAt: 2026-08-11T11:40:18.000Z
agentTools:
  projectIndex: https://developer.personio.de/llms.txt
---

# Retrieve a candidate by ID.

Returns a candidate for the provided ID. 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/{id}": {
      "get": {
        "summary": "Retrieve a candidate by ID.",
        "description": "Returns a candidate for the provided ID. 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": [
          {
            "description": "ID of candidate.",
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string"
            },
            "required": true,
            "example": "495039"
          }
        ],
        "x-path-examples": {
          "200 Retrieve candidate by ID": {
            "value": "/v2/recruiting/candidates/495039"
          },
          "403 Forbidden response": {
            "value": "/v2/recruiting/candidates/495039"
          },
          "404 Retrieve non-existing candidate": {
            "value": "/v2/recruiting/candidates/id-that-does-not-exist"
          }
        },
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Candidate"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "_meta": {
                          "$ref": "#/paths/~1v2~1recruiting~1jobs/get/responses/200/content/application~1json/schema/properties/_meta"
                        }
                      }
                    }
                  ]
                },
                "examples": {
                  "200 Retrieve candidate by ID": {
                    "$ref": "#/components/examples/CandidateResponse"
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenResponse"
          },
          "404": {
            "description": "Candidate not found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/paths/~1v2~1recruiting~1jobs/get/responses/400/content/application~1problem+json/schema"
                },
                "examples": {
                  "404 Retrieve non-existing candidate": {
                    "$ref": "#/components/examples/ResourceNotFound"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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=<current-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"
            }
          ]
        }
      },
      "ResourceNotFound": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30+00:00",
          "errors": [
            {
              "title": "Resource not found",
              "detail": "There is no resource for the specified ID.",
              "type": "https://developer.personio.de/v2.0/page/public-api-error-codes#common.resource_not_found"
            }
          ]
        }
      },
      "CandidateResponse": {
        "value": {
          "id": "495039",
          "company": {
            "id": "10567"
          },
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "gender": "FEMALE",
          "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"
              }
            }
          }
        }
      }
    }
  }
}
```