# List all workplaces. - Returns a list of existing workplaces for an authorized company. - Supports pagination using the `cursor` and `limit` query parameters. - Supports filtering workplaces by `name` and `id` query parameters. - Supports sorting workplaces 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": "Workplaces (Beta)", "description": "Collection of endpoints to manage workplace data.", "version": "2.0.0" }, "servers": [ { "url": "https://api.personio.de" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v2/workplaces": { "get": { "summary": "List all workplaces.", "description": "- Returns a list of existing workplaces for an authorized company.\n- Supports pagination using the `cursor` and `limit` query parameters.\n- Supports filtering workplaces by `name` and `id` query parameters.\n- Supports sorting workplaces 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": "listWorkplaces", "tags": [ "Workplaces" ], "parameters": [ { "in": "query", "name": "id", "description": "Filter results matching one or more provided workplace IDs. Multiple IDs should be comma-separated.", "required": false, "schema": { "type": "string", "example": "1,2" } }, { "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 workplace names. Multiple names should be comma-separated.", "required": false, "schema": { "type": "string", "example": "Main Office" } }, { "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" } }, { "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 workplaces": { "value": "/public/organization/papi/v2/workplaces" }, "200 Success - List workplaces with limit": { "value": "/public/organization/papi/v2/workplaces", "query": "limit=1" }, "200 Success - List workplaces with cursor": { "value": "/public/organization/papi/v2/workplaces", "query": "cursor=cur_V3lJeE1qTWlMQ0k0WmpaaVpURTNNV1JoT0dVNE9EUmlNMlUwTXpVelltVmtOVE5rT1RGak1pSmR8MXx8" }, "200 Success - List workplaces filtered by name": { "value": "/public/organization/papi/v2/workplaces", "query": "name=Main Office" }, "200 Success - List workplaces filtered by IDs": { "value": "/public/organization/papi/v2/workplaces", "query": "id=1,2" }, "200 Success - List workplaces sorted by name": { "value": "/public/organization/papi/v2/workplaces", "query": "sort=name" }, "400 Bad Request - Invalid cursor provided": { "value": "/public/organization/papi/v2/workplaces", "query": "cursor=invalid" }, "400 Bad Request - Invalid limit value": { "value": "/public/organization/papi/v2/workplaces", "query": "limit=abc" } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkplaceListResponse" }, "examples": { "200 Success - List all workplaces": { "value": { "_data": [ { "id": "1", "name": "Main Office" }, { "id": "2", "name": "Branch Office" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/workplaces" } } } } }, "200 Success - List workplaces with limit": { "value": { "_data": [ { "id": "1", "name": "Main Office" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/workplaces?limit=1" }, "next": { "href": "https://api.personio.de/v2/workplaces?cursor=cur_V3lJeE1qTWlMQ0k0WmpaaVpURTNNV1JoT0dVNE9EUmlNMlUwTXpVelltVmtOVE5rT1RGak1pSmR8MXx8" } } } } }, "200 Success - List workplaces with cursor": { "value": { "_data": [ { "id": "2", "name": "Branch Office" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/workplaces?cursor=cur_V3lJeE1qTWlMQ0k0WmpaaVpURTNNV1JoT0dVNE9EUmlNMlUwTXpVelltVmtOVE5rT1RGak1pSmR8MXx8" } } } } }, "200 Success - List workplaces filtered by name": { "value": { "_data": [ { "id": "1", "name": "Main Office" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/workplaces?name=Main Office" } } } } }, "200 Success - List workplaces filtered by IDs": { "value": { "_data": [ { "id": "1", "name": "Main Office" }, { "id": "2", "name": "Branch Office" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/workplaces?id=1,2" } } } } }, "200 Success - List workplaces sorted by name": { "value": { "_data": [ { "id": "2", "name": "Branch Office" }, { "id": "1", "name": "Main Office" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/workplaces?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": { "Workplace": { "description": "Represents a workplace in the organization.", "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the workplace.", "example": 1, "readOnly": true }, "name": { "type": "string", "description": "The name of the workplace.", "example": "Main Office" } } }, "WorkplaceListResponse": { "type": "object", "description": "Represents a paginated list of workplaces.", "required": [ "_data", "_meta" ], "properties": { "_data": { "type": "array", "description": "List of workplaces.", "items": { "$ref": "#/components/schemas/Workplace" } }, "_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=" } } } } } } } } } } } ```