Get a person record

Purpose

Use this call to read a person record by its identifier, optionally with the stored images and vectors.

Request

POST <API_BASE_URL>/person. All calls are POST under your API address. Replace <API_BASE_URL> with the API address provided with your access.

Send a permanent API token in the token field of the body, or a user token in the token header. See authentication.

Content type: application/json.

Field	Type	Required	Description
`token`	string (uuid)	if no header	Your permanent API token. Required unless you send a user token in the `token` header.
`person_id`	string (uuid)	yes	The person to read.
`list_id`	string (uuid)	no	The list the person belongs to. When left out, the default list is used.
`thumbs`	boolean	no	Include the stored images, base64 encoded.
`embeddings`	boolean	no	Include the stored vectors, base64 encoded.

Response

HTTP 200. The person record, sent bare. This operation does not wrap its success in the status envelope.

Field	Type	Description
`person_id`	string (uuid)	The identifier of the person record.
`list_id`	string (uuid)	The person list the record belongs to.
`created`	string (date-time)	When the record was created.
`updated`	string (date-time)	When the record last changed.
`fields`	array of string	The strings stored with the person by create person and update person. Empty when none were.
`group_id`	string (uuid)	The data source group the initial image came from.
`source_id`	string (uuid)	The data source the initial image came from.
`features`	array of object	The results of the checks named in `feature_check`, one entry per feature.
`status`	string	`init` when created explicitly, `auto` when created by a source with automatic person creation, `replaced` when the initial image was replaced, `moved` when the record was moved to another list.
`yaw`	integer	The side angle of the initial face, in degrees.
`thumbs`	array of string (base64)	Stored images of the person, base64 encoded. Empty unless `thumbs` was requested.
`embeddings`	array of string (base64)	Stored vectors of the person, base64 encoded. Empty unless `embeddings` was requested.

Errors

400: The body failed validation. The answer has status of error and a details list with one entry per offending field (path, expected, actual).
401: The token is missing, expired or unknown.
404: A referenced entity does not exist.

A refusal can also come before the operation runs: an address outside your IP allowlist, a token bound to another address, or a body that is not valid JSON. See response format and errors.

Example

Request:

curl -X POST "<API_BASE_URL>/person" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<your permanent API token>",
    "person_id": "<person id>",
    "list_id": "<person list id>"
  }'

Response:

{
  "person_id": "<person id>",
  "list_id": "<person list id>",
  "created": "2026-01-01T10:00:00.000Z",
  "updated": "2026-01-01T10:00:00.000Z",
  "fields": [
    "<your reference>"
  ],
  "group_id": "<group id>",
  "source_id": "<source id>",
  "features": [],
  "status": "init",
  "yaw": 4,
  "thumbs": [],
  "embeddings": []
}