# List persons.

- This endpoint returns a list of persons.
- The endpoint supports pagination and filtering based on various parameters such as id, first_name, last_name, created_at, and updated_at.
  - Filters are combined using the logical "AND" operator, which requires that all conditions be true for the output to be included.
- The endpoint requires the personio:persons:read scope.


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Person",
    "version": "2.0.0",
    "description": "Collection of endpoints to manage persons."
  },
  "servers": [
    {
      "url": "https://api.personio.de"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v2/persons": {
      "get": {
        "summary": "List persons.",
        "description": "- This endpoint returns a list of persons.\n- The endpoint supports pagination and filtering based on various parameters such as id, first_name, last_name, created_at, and updated_at.\n  - Filters are combined using the logical \"AND\" operator, which requires that all conditions be true for the output to be included.\n- The endpoint requires the personio:persons:read scope.\n",
        "tags": [
          "Persons"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "example": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            },
            "description": "The amount of resources to be returned per one request. It can range between 1 and 50, and the default is 10."
          },
          {
            "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."
          },
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter results matching one or more provided person ids.\n",
            "example": "person-id-1,person-id-2"
          },
          {
            "name": "email",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter persons matching one or more provided email addresses\n",
            "example": "person1@example.com,person2@example.com"
          },
          {
            "name": "first_name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter persons matching the provided `first_name`.\n",
            "example": "John"
          },
          {
            "name": "last_name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter persons matching the provided `last_name`.\n",
            "example": "Doe"
          },
          {
            "name": "preferred_name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter persons matching provided `preferred_name`.\n",
            "example": "JohnDoe"
          },
          {
            "name": "created_at",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Filter persons by creation date.",
            "example": "2023-01-01T12:00:00Z"
          },
          {
            "name": "created_at.gt",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Filter persons created after the provided date.",
            "example": "2023-01-01T12:00:00Z"
          },
          {
            "name": "created_at.lt",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Filter persons created before the provided date.",
            "example": "2023-01-01T12:00:00Z"
          },
          {
            "name": "updated_at",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Filter persons by updated date.",
            "example": "2023-01-01T12:00:00Z"
          },
          {
            "name": "updated_at.gt",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Filter persons updated after the provided date.",
            "example": "2023-01-01T12:00:00Z"
          },
          {
            "name": "updated_at.lt",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Filter persons updated before the provided date.",
            "example": "2023-01-01T12:00:00Z"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "INACTIVE"
              ]
            },
            "description": "Filter persons by status. ACTIVE includes persons whose latest employment status is active, leave, or onboarding. INACTIVE includes persons whose latest employment status is inactive.\n",
            "example": "ACTIVE"
          }
        ],
        "x-path-examples": {
          "200 List all persons in single page": {
            "value": ""
          },
          "200 List all persons with multiple pages": {
            "value": ""
          },
          "200 List persons using a filter": {
            "value": "email=jen.doe@personio.de"
          },
          "200 List persons using pagination": {
            "value": "limit=1"
          },
          "200 List persons using filters and pagination": {
            "value": "limit=1&created_at.lt=2017-07-21T17:32:28Z"
          },
          "200 List persons by id": {
            "value": "id=person-id-1,person-id-2"
          },
          "200 List persons by name": {
            "value": "first_name=John&last_name=Doe&preferred_name=JohnDoe"
          },
          "200 List persons by dates": {
            "value": "created_at=2023-01-01T12:00:00Z&created_at.gt=2023-01-01T12:00:00Z&updated_at=2023-01-01T12:00:00Z&updated_at.gt=2023-01-01T12:00:00Z&updated_at.lt=2023-01-01T12:00:00Z"
          },
          "200 List persons by status": {
            "value": "status=ACTIVE"
          },
          "400 List persons using wrong filter value": {
            "value": "created_at.lt=wrong-date-format"
          },
          "400 List persons using wrong filter format": {
            "value": "id.nooperator=0825e977-b879-4106-a73e-3d9aedad733d"
          }
        },
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "_data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Person"
                      }
                    },
                    "_meta": {
                      "$ref": "#/components/schemas/Person/properties/_meta"
                    }
                  }
                },
                "examples": {
                  "200 List all persons in single page": {
                    "$ref": "#/components/examples/PersonsListInSinglePageResponse"
                  },
                  "200 List all persons with multiple pages": {
                    "$ref": "#/components/examples/PersonsListInMultiplePagesResponse"
                  },
                  "200 List persons using a filter": {
                    "$ref": "#/components/examples/PersonsWithParametersAndSinglePageResponse"
                  },
                  "200 List persons using pagination": {
                    "$ref": "#/components/examples/PersonsWithParametersAndMultiplePagesResponse"
                  },
                  "200 List persons using filters and pagination": {
                    "$ref": "#/components/examples/PersonsWithParametersAndMultiplePagesResponse"
                  },
                  "200 List persons by id": {
                    "$ref": "#/components/examples/PersonsWithParametersAndSinglePageResponse"
                  },
                  "200 List persons by name": {
                    "$ref": "#/components/examples/PersonsWithParametersAndSinglePageResponse"
                  },
                  "200 List persons by dates": {
                    "$ref": "#/components/examples/PersonsWithParametersAndSinglePageResponse"
                  },
                  "200 List persons by status": {
                    "$ref": "#/components/examples/PersonsWithParametersAndSinglePageResponse"
                  }
                }
              }
            }
          },
          "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 persons using wrong filter value": {
                    "$ref": "#/components/examples/InvalidFilterValue"
                  },
                  "400 List persons using wrong filter format": {
                    "$ref": "#/components/examples/InvalidFilterFormat"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Person": {
        "description": "Person schema example",
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true,
            "description": "The unique identifier for the `Person`"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "The email address this Person is connected with. The email is unique per Person, and the same Person can hold different Employments sharing the same email."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp of when the person was created in UTC",
            "readOnly": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp of when the person was updated in UTC",
            "readOnly": true
          },
          "first_name": {
            "type": "string",
            "description": "The first name of the person"
          },
          "last_name": {
            "type": "string",
            "description": "The last name of the person"
          },
          "preferred_name": {
            "type": "string",
            "description": "The preferred name of the person"
          },
          "gender": {
            "type": "string",
            "enum": [
              "UNSPECIFIED",
              "MALE",
              "FEMALE",
              "DIVERSE"
            ],
            "description": "The gender of the person"
          },
          "profile_picture": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "url",
                "description": "The URL of the person's profile picture"
              }
            },
            "description": "The person's profile picture"
          },
          "status": {
            "type": "string",
            "enum": [
              "UNSPECIFIED",
              "ACTIVE",
              "INACTIVE"
            ],
            "description": "The status of the person that is derived from the status of the latest person's employment. The person status will be set to ACTIVE if the current employment has ACTIVE, LEAVE or ONBOARDING status, otherwise the person status will be set to INACTIVE. Please use employment status to get more fine grained value for status."
          },
          "custom_attributes": {
            "type": "array",
            "items": {
              "description": "Custom Attribute schema",
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The unique identifier for this `custom_attribute`.",
                  "readOnly": true
                },
                "type": {
                  "type": "string",
                  "description": "The type of the custom attribute. Only listed values are valid.",
                  "enum": [
                    "UNSPECIFIED",
                    "STRING",
                    "INT",
                    "DOUBLE",
                    "DATE",
                    "BOOLEAN",
                    "STRING_LIST"
                  ]
                },
                "global_id": {
                  "type": "string",
                  "description": "The global identifier for this attribute. This value is unique and can be set to a selected value at the creation of the custom attribute.",
                  "readOnly": true
                },
                "label": {
                  "type": "string",
                  "description": "The label defined for this attribute.",
                  "readOnly": true
                },
                "value": {
                  "oneOf": [
                    {
                      "type": "string",
                      "description": "An arbitrary value that can be represented as a string."
                    },
                    {
                      "type": "array",
                      "description": "A list of values.",
                      "items": {
                        "type": "string",
                        "description": "An arbitrary value that can be represented as a string."
                      }
                    },
                    {
                      "type": "array",
                      "description": "A list of objects.",
                      "items": {
                        "type": "object",
                        "description": "An arbitrary object."
                      }
                    }
                  ]
                }
              }
            }
          },
          "employments": {
            "readOnly": true,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PersonEmploymentResponse"
            }
          },
          "_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=<current-cursor>"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "PersonEmploymentResponse": {
        "description": "Reference object to the Persons Employments",
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true
          }
        }
      }
    },
    "examples": {
      "PersonsListInSinglePageResponse": {
        "value": {
          "_data": [
            {
              "id": "3003",
              "email": "jen.doe@personio.de",
              "created_at": "2017-07-21T17:32:28Z",
              "updated_at": "2017-07-21T17:32:28Z",
              "first_name": "John",
              "last_name": "Smith",
              "preferred_name": "John Smith",
              "gender": "MALE",
              "profile_picture": {
                "url": "https://api.personio.de/v1/company/employees/3003/profile-picture"
              },
              "status": "ACTIVE",
              "custom_attributes": [
                {
                  "id": "dynamic_305",
                  "type": "string",
                  "value": "Red",
                  "global_id": "color"
                },
                {
                  "id": "dynamic_306",
                  "type": "string",
                  "value": "DExx-xxff-ss-os02",
                  "global_id": "IBAN"
                }
              ],
              "employments": [
                {
                  "id": "c85d978e-1104-4762-be94-c868525eef45"
                }
              ],
              "_meta": {
                "links": {
                  "employments": {
                    "href": "https://api.personio.de/v2/persons/3003/employments"
                  }
                }
              }
            }
          ],
          "_meta": {
            "links": {
              "self": {
                "href": "https://api.personio.de/v2/persons"
              }
            }
          }
        }
      },
      "PersonsListInMultiplePagesResponse": {
        "value": {
          "_data": [
            {
              "id": "3003",
              "email": "jen.doe@personio.de",
              "created_at": "2017-07-21T17:32:28Z",
              "updated_at": "2017-07-21T17:32:28Z",
              "first_name": "John",
              "last_name": "Smith",
              "preferred_name": "John Smith",
              "gender": "MALE",
              "profile_picture": {
                "url": "https://api.personio.de/v1/company/employees/3003/profile-picture"
              },
              "status": "ACTIVE",
              "custom_attributes": [
                {
                  "id": "dynamic_305",
                  "type": "string",
                  "value": "Red",
                  "global_id": "color"
                },
                {
                  "id": "dynamic_306",
                  "type": "string",
                  "value": "DExx-xxff-ss-os02",
                  "global_id": "IBAN"
                }
              ],
              "employments": [
                {
                  "id": "c85d978e-1104-4762-be94-c868525eef45"
                }
              ],
              "_meta": {
                "links": {
                  "employments": {
                    "href": "https://api.personio.de/v2/persons/3003/employments"
                  }
                }
              }
            }
          ],
          "_meta": {
            "links": {
              "self": {
                "href": "https://api.personio.de/v2/persons"
              },
              "next": {
                "href": "https://api.personio.de/v2/persons?cursor=cur_234ls0f02lalfdd"
              }
            }
          }
        }
      },
      "PersonsWithParametersAndSinglePageResponse": {
        "value": {
          "_data": [
            {
              "id": "3003",
              "email": "jen.doe@personio.de",
              "created_at": "2017-07-21T17:32:28Z",
              "updated_at": "2017-07-21T17:32:28Z",
              "first_name": "John",
              "last_name": "Smith",
              "preferred_name": "John Smith",
              "gender": "MALE",
              "profile_picture": {
                "url": "https://api.personio.de/v1/company/employees/3003/profile-picture"
              },
              "status": "ACTIVE",
              "custom_attributes": [
                {
                  "id": "dynamic_305",
                  "type": "string",
                  "value": "Red",
                  "global_id": "color"
                },
                {
                  "id": "dynamic_306",
                  "type": "string",
                  "value": "DExx-xxff-ss-os02",
                  "global_id": "IBAN"
                }
              ],
              "employments": [
                {
                  "id": "c85d978e-1104-4762-be94-c868525eef45"
                }
              ],
              "_meta": {
                "links": {
                  "employments": {
                    "href": "https://api.personio.de/v2/persons/3003/employments"
                  }
                }
              }
            }
          ],
          "_meta": {
            "links": {
              "self": {
                "href": "https://api.personio.de/v2/persons?cursor=cur_234ls0f02lalfdd"
              }
            }
          }
        }
      },
      "PersonsWithParametersAndMultiplePagesResponse": {
        "value": {
          "_data": [
            {
              "id": "3003",
              "email": "jen.doe@personio.de",
              "created_at": "2017-07-21T17:32:28Z",
              "updated_at": "2017-07-21T17:32:28Z",
              "first_name": "John",
              "last_name": "Smith",
              "preferred_name": "John Smith",
              "gender": "MALE",
              "profile_picture": {
                "url": "https://api.personio.de/v1/company/employees/3003/profile-picture"
              },
              "status": "ACTIVE",
              "custom_attributes": [
                {
                  "id": "dynamic_305",
                  "type": "string",
                  "value": "Red",
                  "global_id": "color"
                },
                {
                  "id": "dynamic_306",
                  "type": "string",
                  "value": "DExx-xxff-ss-os02",
                  "global_id": "IBAN"
                }
              ],
              "employments": [
                {
                  "id": "c85d978e-1104-4762-be94-c868525eef45"
                }
              ],
              "_meta": {
                "links": {
                  "employments": {
                    "href": "https://api.personio.de/v2/persons/3003/employments"
                  }
                }
              }
            }
          ],
          "_meta": {
            "links": {
              "self": {
                "href": "https://api.personio.de/v2/persons?cursor=cur_234ls0f02lalfdd"
              },
              "next": {
                "href": "https://api.personio.de/v2/persons?cursor=cur_82sQwR2eZvKilo2"
              }
            }
          }
        }
      },
      "InvalidFilterValue": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30+00:00",
          "errors": [
            {
              "title": "Bad request",
              "detail": "Provided request parameters are invalid.",
              "type": "https://developer.personio.de/reference/errors#common.bad_request"
            }
          ]
        }
      },
      "InvalidFilterFormat": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30+00:00",
          "errors": [
            {
              "title": "Bad request",
              "detail": "Provided filter encoding is invalid.",
              "type": "https://developer.personio.de/reference/errors#common.bad_request"
            }
          ]
        }
      }
    }
  }
}
```