--- updatedAt: 2026-06-03T14:37:17.000Z agentTools: projectIndex: https://developer.personio.de/llms.txt --- # Retrieves a Job. - Returns the requested Job. - Requires `personio:jobs:read`. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Jobs and Salary Bands", "description": "Collection of endpoints to manage Jobs and Salary Bands.", "version": "2.0.0" }, "servers": [ { "url": "https://api.personio.de" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v2/jobs": { "get": { "summary": "List jobs.", "description": "- Returns a list of existing Jobs for an authorized company.\n- Supports pagination using the `cursor` and `limit` query parameters.\n- Supports filtering Jobs by `name` and `ID` query parameters.\n- Supports sorting Jobs by `name` and `ID` using the `sort` query parameter.\n- Default sort is by `ID` in descending order.\n- Requires `personio:jobs:read`.\n", "operationId": "listJobs", "tags": [ "Jobs" ], "parameters": [ { "in": "query", "name": "id", "description": "Filter results matching one or more provided Job IDs. Multiple IDs should be comma-separated.", "required": false, "schema": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890,b2c3d4e5-f6a7-8901-bcde-f12345678901" } }, { "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." }, { "in": "query", "name": "limit", "description": "The maximum number of results to return per page.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 50 } }, { "in": "query", "name": "name", "description": "Filter results matching one or more provided Job names. Multiple names should be comma-separated.", "required": false, "schema": { "type": "string", "example": "Software Engineer,Product Manager" } }, { "in": "query", "name": "sort", "description": "Defines the sort order of results. - Use field names for ascending (e.g., `name`) - Use a minus sign for descending (e.g., `-name`) - If no sort is provided, results are returned sorted by `ID` in descending order.", "required": false, "schema": { "type": "string", "example": "name,-id" }, "explode": false } ], "x-path-examples": { "200 Success - List all jobs": { "value": "/public/organization/papi/v2/jobs" }, "200 Success - List jobs with limit": { "value": "/public/organization/papi/v2/jobs", "query": "limit=1" }, "200 Success - List jobs with cursor": { "value": "/public/organization/papi/v2/jobs", "query": "cursor=cur_V3lJeE1qTWlMQ0k0WmpaaVpURTNNV1JoT0dVNE9EUmlNMlUwTXpVelltVmtOVE5rT1RGak1pSmR8MXx8" }, "200 Success - List jobs filtered by name": { "value": "/public/organization/papi/v2/jobs", "query": "name=Software Engineer" }, "200 Success - List jobs filtered by IDs": { "value": "/public/organization/papi/v2/jobs", "query": "id=a1b2c3d4-e5f6-7890-abcd-ef1234567890,b2c3d4e5-f6a7-8901-bcde-f12345678901" }, "200 Success - List jobs sorted by name": { "value": "/public/organization/papi/v2/jobs", "query": "sort=name" }, "400 Bad Request - Invalid cursor provided": { "value": "/public/organization/papi/v2/jobs", "query": "cursor=invalid" }, "400 Bad Request - Invalid limit value": { "value": "/public/organization/papi/v2/jobs", "query": "limit=abc" } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobListResponse" }, "examples": { "200 Success - List all jobs": { "value": { "_data": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Product Manager", "job_family": { "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "name": "Product" }, "level": { "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890", "name": "IC3" }, "job_track": { "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890", "name": "Individual Contributor" }, "global_grade": { "id": "d4e5f6a7-b8c9-0123-abcd-ef1234567890", "name": "G09" }, "salary_band_ids": [] }, { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Software Engineer", "job_family": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Engineering" }, "level": { "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", "name": "IC4" }, "job_track": { "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890", "name": "Individual Contributor" }, "global_grade": { "id": "c3d4e5f6-a7b8-9012-abcd-ef1234567890", "name": "G10" }, "salary_band_ids": [] } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/jobs" } } } } }, "200 Success - List jobs with limit": { "value": { "_data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Software Engineer", "job_family": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Engineering" }, "level": { "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", "name": "IC4" }, "job_track": { "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890", "name": "Individual Contributor" }, "global_grade": { "id": "c3d4e5f6-a7b8-9012-abcd-ef1234567890", "name": "G10" }, "salary_band_ids": [] } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/jobs?limit=1" }, "next": { "href": "https://api.personio.de/v2/jobs?cursor=cur_V3lJeE1qTWlMQ0k0WmpaaVpURTNNV1JoT0dVNE9EUmlNMlUwTXpVelltVmtOVE5rT1RGak1pSmR8MXx8" } } } } }, "200 Success - List jobs with cursor": { "value": { "_data": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Product Manager", "job_family": { "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "name": "Product" }, "level": { "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890", "name": "IC3" }, "job_track": { "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890", "name": "Individual Contributor" }, "global_grade": { "id": "d4e5f6a7-b8c9-0123-abcd-ef1234567890", "name": "G09" }, "salary_band_ids": [] } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/jobs?cursor=cur_V3lJeE1qTWlMQ0k0WmpaaVpURTNNV1JoT0dVNE9EUmlNMlUwTXpVelltVmtOVE5rT1RGak1pSmR8MXx8" } } } } }, "200 Success - List jobs filtered by name": { "value": { "_data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Software Engineer", "job_family": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Engineering" }, "level": { "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", "name": "IC4" }, "job_track": { "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890", "name": "Individual Contributor" }, "global_grade": { "id": "c3d4e5f6-a7b8-9012-abcd-ef1234567890", "name": "G10" }, "salary_band_ids": [] } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/jobs?name=Software Engineer" } } } } }, "200 Success - List jobs filtered by IDs": { "value": { "_data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Software Engineer", "job_family": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Engineering" }, "level": { "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", "name": "IC4" }, "job_track": { "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890", "name": "Individual Contributor" }, "global_grade": { "id": "c3d4e5f6-a7b8-9012-abcd-ef1234567890", "name": "G10" }, "salary_band_ids": [] }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Product Manager", "job_family": { "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "name": "Product" }, "level": { "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890", "name": "IC3" }, "job_track": { "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890", "name": "Individual Contributor" }, "global_grade": { "id": "d4e5f6a7-b8c9-0123-abcd-ef1234567890", "name": "G09" }, "salary_band_ids": [] } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/jobs?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890,b2c3d4e5-f6a7-8901-bcde-f12345678901" } } } } }, "200 Success - List jobs sorted by name": { "value": { "_data": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Product Manager", "job_family": { "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890", "name": "Product" }, "level": { "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890", "name": "IC3" }, "job_track": { "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890", "name": "Individual Contributor" }, "global_grade": { "id": "d4e5f6a7-b8c9-0123-abcd-ef1234567890", "name": "G09" }, "salary_band_ids": [] }, { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Software Engineer", "job_family": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Engineering" }, "level": { "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", "name": "IC4" }, "job_track": { "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890", "name": "Individual Contributor" }, "global_grade": { "id": "c3d4e5f6-a7b8-9012-abcd-ef1234567890", "name": "G10" }, "salary_band_ids": [] } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/jobs?sort=name" } } } } } } } } }, "400": { "description": "The current request is invalid. Please make sure you pass all the required parameters and you are using the proper content-type.", "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 Bad Request - Invalid cursor provided": { "value": { "personio_trace_id": "1a9eeaf4-db8f-47a6-b6be-f910e8e63b05", "timestamp": "2025-05-09T11:15:03Z", "errors": [ { "title": "Invalid request parameter", "detail": "Cursor is not valid" } ] } }, "400 Bad Request - Invalid limit value": { "value": { "personio_trace_id": "053a9d39-ff08-48b1-96aa-10704062bd07", "timestamp": "2025-05-09T11:15:03Z", "errors": [ { "title": "Invalid request parameter", "detail": "Invalid value for parameter 'limit'. Expected int." } ] } } } } } }, "401": { "description": "Authentication information is missing or invalid." }, "429": { "description": "Too many requests. The rate limit has been exceeded." } } } }, "/v2/jobs/{id}": { "get": { "summary": "Retrieves a Job.", "description": "- Returns the requested Job.\n- Requires `personio:jobs:read`.", "operationId": "getJob", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The unique identifier (UUID) of the Job to be retrieved.", "schema": { "$ref": "#/components/schemas/JobId" } } ], "x-path-examples": { "200 Success - Retrieve Job by ID": { "value": "/public/organization/papi/v2/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "404 Not Found - Job does not exist": { "value": "/public/organization/papi/v2/jobs/00000000-0000-0000-0000-000000000000" } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "examples": { "200 Success - Retrieve Job by ID": { "value": { "_data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Software Engineer", "job_family": { "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "name": "Engineering" }, "level": { "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890", "name": "IC4" }, "job_track": { "id": "a2b3c4d5-e6f7-8901-abcd-ef1234567890", "name": "Individual Contributor" }, "global_grade": { "id": "c3d4e5f6-a7b8-9012-abcd-ef1234567890", "name": "G10" }, "salary_band_ids": [] }, "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } } } } }, "401": { "description": "Authentication information is missing or invalid." }, "404": { "description": "The Job with the provided ID could not be found.", "content": { "application/problem+json": { "schema": { "$ref": "#/paths/~1v2~1jobs/get/responses/400/content/application~1problem+json/schema" }, "examples": { "404 Not Found - Job does not exist": { "value": { "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd", "timestamp": "2025-05-09T11:15:03Z", "errors": [ { "title": "Resource not found", "detail": "There is no resource for the specified ID.", "type": "https://developer.personio.de/reference/errors#common.resource_not_found" } ] } } } } } }, "429": { "description": "Too many requests. The rate limit has been exceeded." } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "JobId": { "type": "string", "format": "uuid", "description": "The unique identifier of the Job.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "JobName": { "type": "string", "description": "The name of the Job.", "example": "Software Engineer" }, "JobFamilyId": { "type": "string", "format": "uuid", "description": "The unique identifier of the Job Family.", "example": "f1e2d3c4-b5a6-7890-abcd-ef1234567890" }, "JobFamilyName": { "type": "string", "description": "The name of the Job Family.", "example": "Engineering" }, "JobLevelId": { "type": "string", "format": "uuid", "description": "The unique identifier of the Job Level.", "example": "b1c2d3e4-f5a6-7890-abcd-ef1234567890" }, "JobLevelName": { "type": "string", "description": "The name of the Job Level.", "example": "IC4" }, "JobFamily": { "type": "object", "description": "A summarised view of the Job Family that the Job belongs to.", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/JobFamilyId" }, "name": { "$ref": "#/components/schemas/JobFamilyName" } } }, "JobLevel": { "type": "object", "description": "A summarised view of the Job Level that the Job is associated with.", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/JobLevelId" }, "name": { "$ref": "#/components/schemas/JobLevelName" } } }, "JobTrackId": { "type": "string", "format": "uuid", "description": "The unique identifier of the Job Track.", "example": "a2b3c4d5-e6f7-8901-abcd-ef1234567890" }, "JobTrackName": { "type": "string", "description": "The name of the Job Track.", "example": "Individual Contributor" }, "JobTrack": { "type": "object", "description": "A summarised view of the Job Track that the Job is associated with.", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/JobTrackId" }, "name": { "$ref": "#/components/schemas/JobTrackName" } } }, "GlobalGradeId": { "type": "string", "format": "uuid", "description": "The unique identifier of the Global Grade.", "example": "c3d4e5f6-a7b8-9012-abcd-ef1234567890" }, "GlobalGradeName": { "type": "string", "description": "The name of the Global Grade.", "example": "G10" }, "GlobalGrade": { "type": "object", "description": "A summarised view of the Global Grade that the Job is associated with.", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/GlobalGradeId" }, "name": { "$ref": "#/components/schemas/GlobalGradeName" } } }, "SalaryBandId": { "type": "string", "format": "uuid", "description": "The unique identifier of the Salary Band.", "example": "e1f2a3b4-c5d6-7890-abcd-ef1234567890" }, "Job": { "type": "object", "description": "Defines a Job.", "required": [ "id", "name", "salary_band_ids" ], "properties": { "id": { "$ref": "#/components/schemas/JobId" }, "name": { "$ref": "#/components/schemas/JobName" }, "job_family": { "$ref": "#/components/schemas/JobFamily" }, "level": { "$ref": "#/components/schemas/JobLevel" }, "job_track": { "$ref": "#/components/schemas/JobTrack" }, "global_grade": { "$ref": "#/components/schemas/GlobalGrade" }, "salary_band_ids": { "type": "array", "description": "IDs of the Salary Bands associated with the Job. Empty if the Job has no associated Salary Bands. Use these IDs to retrieve full Salary Band details via `GET /v2/salary-bands`.", "items": { "$ref": "#/components/schemas/SalaryBandId" } } } }, "JobResponse": { "type": "object", "description": "A single Job response wrapper.", "required": [ "_data", "_meta" ], "properties": { "_data": { "$ref": "#/components/schemas/Job" }, "_meta": { "$ref": "#/components/schemas/JobListResponse/properties/_meta" } } }, "JobListResponse": { "type": "object", "description": "Represents a paginated list of Jobs.", "required": [ "_data", "_meta" ], "properties": { "_data": { "type": "array", "description": "List of Jobs.", "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=" } } } } } } } } } } } ```