# List cost centers. - Returns a list of existing cost centers for an authorized company. - Supports pagination using the `cursor` and `limit` query parameters. - Supports filtering cost centers by `name` and `id` query parameters. - Supports sorting cost centers by `name` and `id` using the `sort` query parameter. - Default sort is by `id` in ascending order. - Note: This endpoint is in beta mode. Please use the discussion page in the Developer Hub for feedback. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Cost Centers (Beta)", "description": "Collection of endpoints to manage cost center data.", "version": "2.0.0" }, "servers": [ { "url": "https://api.personio.de" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v2/cost-centers": { "get": { "summary": "List cost centers.", "description": "- Returns a list of existing cost centers for an authorized company.\n- Supports pagination using the `cursor` and `limit` query parameters.\n- Supports filtering cost centers by `name` and `id` query parameters.\n- Supports sorting cost centers by `name` and `id` using the `sort` query parameter.\n- Default sort is by `id` in ascending order.\n- Note: This endpoint is in beta mode. Please use the discussion page in the Developer Hub for feedback.\n", "operationId": "listCostCenters", "tags": [ "Cost Centers" ], "parameters": [ { "in": "query", "name": "id", "description": "Filter results matching one or more provided cost center IDs. Multiple IDs should be comma-separated.", "required": false, "schema": { "type": "string", "example": "123,456" } }, { "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 cost center names. Multiple names should be comma-separated.", "required": false, "schema": { "type": "string", "example": "Sales,IT" } }, { "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 ascending order.", "required": false, "schema": { "type": "string", "example": "name,-id" }, "explode": false }, { "in": "header", "name": "Beta", "description": "As this is a Beta endpoint, the Beta header must be provided with the value `true`.", "schema": { "type": "string", "example": "true" } } ], "x-path-examples": { "200 Success - List all cost centers": { "value": "/public/organization/papi/v2/cost-centers" }, "200 Success - List cost centers with limit": { "value": "/public/organization/papi/v2/cost-centers", "query": "limit=1" }, "200 Success - List cost centers with cursor": { "value": "/public/organization/papi/v2/cost-centers", "query": "cursor=cur_V3lJeE1qTWlMQ0k0WmpaaVpURTNNV1JoT0dVNE9EUmlNMlUwTXpVelltVmtOVE5rT1RGak1pSmR8MXx8" }, "200 Success - List cost centers filtered by name": { "value": "/public/organization/papi/v2/cost-centers", "query": "name=Marketing" }, "200 Success - List cost centers filtered by IDs": { "value": "/public/organization/papi/v2/cost-centers", "query": "id=123,456" }, "200 Success - List cost centers sorted by name": { "value": "/public/organization/papi/v2/cost-centers", "query": "sort=name" }, "400 Bad Request - Invalid cursor provided": { "value": "/public/organization/papi/v2/cost-centers", "query": "cursor=invalid" }, "400 Bad Request - Invalid limit value": { "value": "/public/organization/papi/v2/cost-centers", "query": "limit=abc" } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostCenterListResponse" }, "examples": { "200 Success - List all cost centers": { "value": { "_data": [ { "id": "123", "name": "Sales" }, { "id": "456", "name": "Marketing" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/cost-centers" } } } } }, "200 Success - List cost centers with limit": { "value": { "_data": [ { "id": "123", "name": "Sales" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/cost-centers?limit=1" }, "next": { "href": "https://api.personio.de/v2/cost-centers?cursor=cur_V3lJeE1qTWlMQ0k0WmpaaVpURTNNV1JoT0dVNE9EUmlNMlUwTXpVelltVmtOVE5rT1RGak1pSmR8MXx8" } } } } }, "200 Success - List cost centers with cursor": { "value": { "_data": [ { "id": "456", "name": "Marketing" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/cost-centers?cursor=cur_V3lJeE1qTWlMQ0k0WmpaaVpURTNNV1JoT0dVNE9EUmlNMlUwTXpVelltVmtOVE5rT1RGak1pSmR8MXx8" } } } } }, "200 Success - List cost centers filtered by name": { "value": { "_data": [ { "id": "456", "name": "Marketing" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/cost-centers?name=Marketing" } } } } }, "200 Success - List cost centers filtered by IDs": { "value": { "_data": [ { "id": "123", "name": "Sales" }, { "id": "456", "name": "Marketing" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/cost-centers?id=123,456" } } } } }, "200 Success - List cost centers sorted by name": { "value": { "_data": [ { "id": "456", "name": "Marketing" }, { "id": "123", "name": "Sales" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/cost-centers?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." }, "403": { "description": "The request is understood, but authorization is refused or insufficient." } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "CostCenter": { "description": "Represents a cost center in the organization.", "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the cost center.", "example": "123", "readOnly": true }, "name": { "type": "string", "description": "The name of the cost center.", "example": "Sales" } } }, "CostCenterListResponse": { "type": "object", "description": "Represents a paginated list of cost centers.", "required": [ "_data", "_meta" ], "properties": { "_data": { "type": "array", "description": "List of cost centers.", "items": { "$ref": "#/components/schemas/CostCenter" } }, "_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=" } } } } } } } } } } } ```