# List absence periods. - This endpoint returns a list of absence periods. - It supports pagination and filtering based on various parameters. - Filters are combined using the logical "AND" operator, which requires that all conditions be true for the output to be included - except when filtering by date ranges, as in this case it'll match absences overlapping the provided period. - This endpoint requires the personio:absences:read scope. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Absence Period API", "version": "2.0.0", "description": "Read API for Absence Entities." }, "servers": [ { "url": "https://api.personio.de" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Absence Periods", "description": "Endpoints related to absences taken by employees and the rules that define them." } ], "paths": { "/v2/absence-periods": { "get": { "summary": "List absence periods.", "description": "- This endpoint returns a list of absence periods.\n- It supports pagination and filtering based on various parameters.\n- Filters are combined using the logical \"AND\" operator, which requires that all conditions be true for the output to be included - except when filtering by date ranges, as in this case it'll match absences overlapping the provided period.\n- This endpoint requires the personio:absences:read scope.\n", "tags": [ "Absence Periods" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "example": 50 }, "description": "The maximum number of absence periods returned per request." }, { "$ref": "#/paths/~1v2~1absence-types/get/parameters/0" }, { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Filter results matching any of the provided absence periods' ids.\n", "example": "abc6fa09-d8fe-4de0-be03-f0a1d48df766,bbc6fa09-d8fe-4de0-be03-f0a1d48df766" }, { "name": "absence_type.id", "in": "query", "schema": { "type": "string" }, "description": "Filter results matching any of the provided absence types' ids.\n", "example": "cba6fa09-d8fe-4de0-be03-f0a1d48df766,bbb6fa09-d8fe-4de0-be03-f0a1d48df766" }, { "name": "person.id", "in": "query", "schema": { "type": "string" }, "description": "Filter results matching any of the provided persons' ids.\n", "example": "123,456" }, { "name": "starts_from.date_time.gte", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Matches absence periods starting from (inclusive) the provided date-time.", "example": "2023-01-01T12:00:00Z" }, { "name": "starts_from.date_time.lte", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Matches absence periods starting before or at the provided date-time.", "example": "2023-01-01T12:00:00Z" }, { "name": "ends_at.date_time.lte", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Matches absence periods ending before or at the provided date-time.", "example": "2023-01-01T12:00:00Z" }, { "name": "ends_at.date_time.gte", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Matches absence periods ending after or at the provided date-time.", "example": "2023-01-01T12:00:00Z" }, { "name": "updated_at.gte", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter out absence periods updated before the provided date-time.", "example": "2023-01-01T12:00:00Z" }, { "name": "updated_at.lte", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Filter out absence periods updated after the provided date-time.", "example": "2023-01-01T12:00:00Z" } ], "x-path-examples": { "200 Valid request": { "value": "/papi/v2/absence-periods" }, "200 Valid request with cursor": { "value": "/papi/v2/absence-periods", "query": "cursor=cur_234ls0f02lalfddabcdef==" }, "200 Valid request with filters": { "value": "/papi/v2/absence-periods", "query": "id=cba6fa09-d8fe-4de0-be03-f0a1d48df766" }, "400 Invalid Cursor": { "value": "/papi/v2/absence-periods", "query": "cursor=invalid-cursor-string" }, "400 Invalid filter": { "value": "/papi/v2/absence-periods", "query": "starts_from.date_time.gte=invalid" }, "403 Forbidden": { "value": "/papi/v2/absence-periods" }, "422 Inconsistent filter": { "value": "/papi/v2/absence-periods", "query": "starts_from.date_time.gte=2024-02-02T00:00:00Z&starts_from.date_time.lte=2024-01-01T00:00:00Z" } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "properties": { "_data": { "type": "array", "items": { "$ref": "#/components/schemas/AbsencePeriod" } }, "_meta": { "$ref": "#/paths/~1v2~1absence-types/get/responses/200/content/application~1json/schema/properties/_meta" } } }, "examples": { "200 Valid request": { "$ref": "#/components/examples/ListAbsencePeriodsResponse" }, "200 Valid request with cursor": { "$ref": "#/components/examples/ListAbsencePeriodsWithCursorResponse" }, "200 Valid request with filters": { "$ref": "#/components/examples/ListAbsencePeriodsWithFiltersResponse" } } } } }, "400": { "description": "Bad request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/responses/ForbiddenErrorResponse/content/application~1problem%2Bjson/schema" }, "examples": { "400 Invalid Cursor": { "$ref": "#/components/examples/InvalidCursor" }, "400 Invalid filter": { "$ref": "#/components/examples/InvalidFilter" } } } } }, "403": { "$ref": "#/components/responses/ForbiddenErrorResponse" }, "422": { "description": "Unprocessable content.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/responses/ForbiddenErrorResponse/content/application~1problem%2Bjson/schema" }, "examples": { "422 Inconsistent filter": { "$ref": "#/components/examples/InconsistentFilter" } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "examples": { "ListAbsencePeriodsResponse": { "value": { "_data": [ { "id": "bbc6fa09-d8fe-4de0-be03-f0a1d48df766", "person": { "id": "123" }, "starts_from": { "date_time": "2024-03-01T14:00:00Z" }, "ends_at": { "date_time": "2024-04-01T14:00:00Z" }, "timezone_id": "Europe/Berlin", "absence_type": { "id": "abc6fa09-d8fe-4de0-be03-f0a1d48df7bb" }, "approval": { "status": "APPROVED" }, "created_at": "2024-01-02T13:00:00Z", "updated_at": "2024-01-02T13:00:00Z" }, { "id": "abc6fa09-d8fe-4de0-be03-f0a1d48df766", "person": { "id": "321" }, "starts_from": { "date_time": "2024-01-01T14:00:00Z" }, "ends_at": { "date_time": "2024-02-01T14:00:00Z" }, "timezone_id": "Europe/Berlin", "absence_type": { "id": "abc6fa09-d8fe-4de0-be03-f0a1d48df7bb" }, "approval": { "status": "APPROVED" }, "created_at": "2024-01-01T13:00:00Z", "updated_at": "2024-01-01T13:00:00Z" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/absence-periods" }, "next": { "href": "https://api.personio.de/v2/absence-periods?cursor=cur_234ls0f02lalfdd" } } } } }, "ListAbsencePeriodsWithCursorResponse": { "value": { "_data": [ { "id": "bbc6fa09-d8fe-4de0-be03-f0a1d48df766", "person": { "id": "123" }, "starts_from": { "date_time": "2024-03-01T14:00:00Z" }, "ends_at": { "date_time": "2024-04-01T14:00:00Z" }, "timezone_id": "Europe/Berlin", "absence_type": { "id": "abc6fa09-d8fe-4de0-be03-f0a1d48df7bb" }, "approval": { "status": "APPROVED" }, "created_at": "2024-01-02T13:00:00Z", "updated_at": "2024-01-02T13:00:00Z" }, { "id": "abc6fa09-d8fe-4de0-be03-f0a1d48df766", "person": { "id": "321" }, "starts_from": { "date_time": "2024-01-01T14:00:00Z" }, "ends_at": { "date_time": "2024-02-01T14:00:00Z" }, "timezone_id": "Europe/Berlin", "absence_type": { "id": "abc6fa09-d8fe-4de0-be03-f0a1d48df7bb" }, "approval": { "status": "APPROVED" }, "created_at": "2024-01-01T13:00:00Z", "updated_at": "2024-01-01T13:00:00Z" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/absence-periods?cursor=cur_234ls0f02lalfddabcdef==" }, "next": { "href": "https://api.personio.de/v2/absence-periods?cursor=cur_234ls0f02lalfdd" } } } } }, "ListAbsencePeriodsWithFiltersResponse": { "value": { "_data": [ { "id": "bbc6fa09-d8fe-4de0-be03-f0a1d48df766", "person": { "id": "123" }, "starts_from": { "date_time": "2024-03-01T14:00:00Z" }, "ends_at": { "date_time": "2024-04-01T14:00:00Z" }, "timezone_id": "Europe/Berlin", "absence_type": { "id": "abc6fa09-d8fe-4de0-be03-f0a1d48df7bb" }, "approval": { "status": "APPROVED" }, "created_at": "2024-01-02T13:00:00Z", "updated_at": "2024-01-02T13:00:00Z" }, { "id": "abc6fa09-d8fe-4de0-be03-f0a1d48df766", "person": { "id": "321" }, "starts_from": { "date_time": "2024-01-01T14:00:00Z" }, "ends_at": { "date_time": "2024-02-01T14:00:00Z" }, "timezone_id": "Europe/Berlin", "absence_type": { "id": "abc6fa09-d8fe-4de0-be03-f0a1d48df7bb" }, "approval": { "status": "APPROVED" }, "created_at": "2024-01-01T13:00:00Z", "updated_at": "2024-01-01T13:00:00Z" } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/absence-periods?id=cba6fa09-d8fe-4de0-be03-f0a1d48df766" }, "next": { "href": "https://api.personio.de/v2/absence-periods?cursor=cur_234ls0f02lalfdd" } } } } }, "InvalidFilter": { "value": { "personio_trace_id": "8b46fa09-d8fe-4de0-be03-f0a1d48df766", "timestamp": "2021-05-28T11:17:30+00:00", "errors": [ { "title": "Bad Request", "detail": "Failed to convert 'starts_from.date_time.gte' with value: 'invalid'" } ] } }, "InconsistentFilter": { "value": { "personio_trace_id": "8b46fa09-d8fe-4de0-be03-f0a1d48df766", "timestamp": "2021-05-28T11:17:30+00:00", "errors": [ { "title": "Inconsistent filter", "detail": "Invalid limit." } ] } }, "InvalidCursor": { "value": { "personio_trace_id": "8b46fa09-d8fe-4de0-be03-f0a1d48df766", "timestamp": "2021-05-28T11:17:30+00:00", "errors": [ { "title": "Invalid cursor", "detail": "The provided cursor is not valid." } ] } } }, "schemas": { "PersonId": { "type": "object", "description": "ID of a Person.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "A unique identifier for a Person." } } }, "AbsenceTypeId": { "type": "object", "description": "ID of an Absence Type.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "A unique identifier for an Absence Type." } } }, "Approval": { "type": "object", "description": "Information related to the approval status of a period.", "properties": { "status": { "type": "string", "description": "The approval status of this period.\n* PENDING: This period is awaiting approval.\n* APPROVED: This period has been approved.\n* DELETION_PENDING: The creator of this period has deleted it. The deletion has not yet been approved.\n* SUBSTITUTE_REQUESTED: The creator of this period specified a substitute employee to cover for them. The\n substitute has not yet accepted this request.\n", "enum": [ "PENDING", "APPROVED", "DELETION_PENDING", "SUBSTITUTE_REQUESTED" ] } } }, "DateTimeWithoutTimezone": { "type": "string", "example": "2022-01-01T14:00:00.000", "description": "An RFC3339 date and timestamp without a timezone offset." }, "AbsencePeriod": { "type": "object", "description": "A period of time with an associated absence type.", "properties": { "id": { "type": "string", "description": "A unique identifier for this period." }, "person": { "$ref": "#/components/schemas/PersonId" }, "starts_from": { "description": "This object represents the beginning of the absence period.\n\nThe `starts_from` and `ends_at` fields specify the *calendar duration* of the absence period, without any\nconsideration of a person's working schedule or public holidays. There are 3 different ways that this time\nrange is handled:\n - For periods with a DAILY `AbsenceType`: the start and end must be at midnight in the provided timezone. The\n `type` field may specify that the period starts or ends half way through the day. This information is used\n when computing the absence balance. It cannot accurately determine the exact time that a person will stop\n or start working because the midpoint of a day depends on a person's working schedule.\n - For periods with an HOURLY `AbsenceType` with duration < 24 hours: the start and end time have minute\n granularity and specify the exact period of the absence. The `type` field is not meaningful in this case.\n - For periods with an HOURLY `AbsenceType` with duration > 24 hours: the start and end time fields and the\n `type` fields behave the same as with DAILY `AbsenceType`s.\n\n**Timezones**\n\nAll dates are provided as local times in the locale specified by the `timezone_id` field. The timestamps have\nno offset.\n\nIn all cases there is validation of these constraints on the server side.\n", "type": "object", "properties": { "date_time": { "$ref": "#/components/schemas/DateTimeWithoutTimezone" }, "type": { "type": "string", "nullable": true, "enum": [ "FIRST_HALF", "SECOND_HALF" ], "example": "SECOND_HALF", "description": "Determines whether this period starts from the first half or second half of the day. See the description\nof the `starts_from` field for a detailed explanation.\n" } } }, "ends_at": { "description": "This object represents the end of the absence period. It may be null for periods which are\nongoing and do not have a defined end. For example, `ends_at` will generally be unknown for long term sick\nleave.\n", "type": "object", "nullable": true, "properties": { "date_time": { "$ref": "#/components/schemas/DateTimeWithoutTimezone" }, "type": { "type": "string", "nullable": true, "enum": [ "FIRST_HALF", "SECOND_HALF" ], "description": "Determines whether this period ends after the first half or second half of the day. See the\ndescription of the `starts_from` field for a detailed explanation.\n" } } }, "timezone_id": { "type": "string", "description": "A timezone ID string, as defined in https://www.iana.org/time-zones. The start and end dates of the period\nare specified in this timezone.\n", "example": "Europe/Berlin" }, "comment": { "type": "string", "nullable": true, "description": "A comment attached to this period." }, "absence_type": { "$ref": "#/components/schemas/AbsenceTypeId" }, "approval": { "$ref": "#/components/schemas/Approval" }, "created_at": { "type": "string", "description": "The time at which this period was created. This is a UTC timestamp and is unrelated to the `timezone_id`\nfield.\n", "format": "date-time" }, "updated_at": { "type": "string", "description": "The time at which this period was last updated. This is a UTC timestamp and is unrelated to the `timezone_id`\nfield.\n", "format": "date-time" } } } }, "responses": { "ForbiddenErrorResponse": { "description": "Access to this endpoint is denied.", "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": { "403 Forbidden": { "value": { "personio_trace_id": "8b46fa09-d8fe-4de0-be03-f0a1d48df766", "timestamp": "2021-05-28T11:17:30Z", "errors": [ { "title": "Access Denied", "detail": "Access to this endpoint is denied." } ] } } } } } } } } } ```