# Retrieve a person.

This endpoint returns a specific person identified by the ID parameter. 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/{id}": {
      "get": {
        "summary": "Retrieve a person.",
        "description": "This endpoint returns a specific person identified by the ID parameter. The endpoint requires the personio:persons:read scope.",
        "tags": [
          "Persons"
        ],
        "x-path-examples": {
          "200 Person response": {
            "value": "/v2/persons/some-normal-id"
          },
          "404 Person not found": {
            "value": "/v2/persons/id-that-does-not-exist"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "description": "The identifier of the person.",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Person"
                },
                "examples": {
                  "200 Person response": {
                    "$ref": "#/components/examples/PersonsResponse"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Person not found.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/paths/~1v2~1persons/get/responses/400/content/application~1problem%2Bjson/schema"
                },
                "examples": {
                  "404 Person not found": {
                    "$ref": "#/components/examples/ResourceNotFound"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "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": {
      "PersonsResponse": {
        "value": {
          "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"
              }
            }
          }
        }
      },
      "ResourceNotFound": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30+00:00",
          "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"
            }
          ]
        }
      }
    }
  }
}
```