--- updatedAt: 2026-08-11T11:40:18.000Z agentTools: projectIndex: https://developer.personio.de/llms.txt --- # List all job categories. Returns a list of job categories for an authorized company. The endpoint requires the `personio:recruiting:read` scope. # 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/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" } } } }, "/v2/recruiting/categories": { "get": { "summary": "List all job categories.", "description": "Returns a list of job categories for an authorized company.\nThe endpoint requires the `personio:recruiting:read` scope.", "tags": [ "Categories" ], "x-path-examples": { "200 List all job categories": { "value": "/v2/recruiting/categories" }, "403 Forbidden response": { "value": "/v2/recruiting/categories" } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "_meta": { "$ref": "#/paths/~1v2~1recruiting~1jobs/get/responses/200/content/application~1json/schema/properties/_meta" } } }, "examples": { "200 List all job categories": { "$ref": "#/components/examples/CategoryListResponse" } } } } }, "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": { "Stage": { "description": "Recruiting pipeline stage for application.", "type": "object", "required": [ "kind", "type" ], "properties": { "kind": { "type": "string", "description": "Recruiting stage type.", "enum": [ "custom", "system" ], "example": "system" }, "type": { "type": "string", "description": "The type of a recruiting stage.", "enum": [ "new", "screening", "interviews", "offer", "hired", "talent pool", "other", "unassigned", "rejected", "withdrawn" ], "example": "screening" }, "name": { "description": "The name of a custom recruiting stage. Relevant only for custom stages.", "type": "string" }, "id": { "type": "string", "description": "The unique identifier of a custom recruiting stage. Relevant only for custom stages.", "example": "234098" } } }, "Category": { "description": "Recruiting category.", "type": "object", "required": [ "id", "company", "name", "stages" ], "properties": { "id": { "description": "The unique identifier of a category.", "type": "string", "readOnly": true, "example": "9823749" }, "company": { "$ref": "#/components/schemas/CompanyRef" }, "name": { "description": "The name of a category.", "type": "string", "readOnly": true, "example": "Recruiting" }, "stages": { "description": "Ordered list of recruiting stages for this category.", "type": "array", "items": { "$ref": "#/components/schemas/Stage" } }, "_meta": { "$ref": "#/paths/~1v2~1recruiting~1jobs/get/responses/200/content/application~1json/schema/properties/_meta" } } }, "CompanyRef": { "description": "The company object.", "type": "object", "required": [ "id" ], "properties": { "id": { "description": "The unique identifier of a company.", "readOnly": true, "type": "string", "example": "324" }, "_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" } ] } }, "CategoryListResponse": { "value": { "_data": [ { "id": "495039", "company": { "id": "10567" }, "name": "Recruiting", "stages": [ { "id": "209321", "kind": "custom", "name": "Technology", "type": "screening" }, { "id": "209322", "kind": "custom", "name": "Interview", "type": "interview" }, { "kind": "system", "type": "unassigned" }, { "kind": "system", "type": "rejected" }, { "kind": "system", "type": "withdrawn" }, { "kind": "system", "type": "offer" }, { "kind": "system", "type": "accepted" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/categories/495039" } } } }, { "id": "3459829", "company": { "id": "10567" }, "name": "Recruiting", "stages": [ { "id": "209323", "kind": "custom", "name": "Technology", "type": "screening" }, { "id": "209324", "kind": "custom", "name": "Interview", "type": "interview" }, { "kind": "system", "type": "unassigned" }, { "kind": "system", "type": "rejected" }, { "kind": "system", "type": "withdrawn" }, { "kind": "system", "type": "offer" }, { "kind": "system", "type": "accepted" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/recruiting/categories/3459829" } } } } ] } } } } } ```