Create a person record

Purpose

Use this call to add a person to a list from a photo. The platform finds the faces on the image, applies the new_person_* rules, and creates a record for each face that passes. A face that matches a person already stored updates that person instead of creating a new one.

Request

POST <API_BASE_URL>/person/create. 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: multipart/form-data. Send the fields as a multipart form. The image file goes in the form field image.

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.
`list_id`	string (uuid)	no	The list the person is added to. When left out, the default list is used.
`group_id`	string (uuid)	no	The data source group the image is attributed to.
`source_id`	string (uuid)	no	The data source the image is attributed to.
`fields`	array of string or string	no	Strings stored with the record for your own business logic, for example your customer reference.
`multi`	boolean	no	Create a separate person for each face found. When `false`, only the largest face is processed.
`new_person_threshold`	value	no	The match threshold for creating a new person. The value `never` creates none; `no_match` uses the platform default.
`new_person_square_min`	value	no	The smallest face side, in pixels, from which a person is created.
`new_person_yaw_max`	value	no	The largest left or right rotation, in degrees.
`new_person_pitch_max`	value	no	The largest up or down tilt, in degrees.
`replace_on_found`	boolean	no	The identifier of a person record to replace.
`feature_check`	array of object or string	no	Features to detect on each face: a name or an array of names such as `age`, `gender` or `quality`.
`thumb`	boolean	no	Return a pre-processed crop of each face, base64 encoded.
`drop_image`	boolean	no	Do not store the image in the actions history.
`embedding`	string	no	A vector representation of a face. Send it to create a person from a vector instead of from an image.

Response

HTTP 201. At least one person record was created.

Field	Type	Description
`status`	string	Always `ok` on this body.
`message`	string	What the recognition step concluded. Never branch on it.
`persons_new`	array of object or object	The records created by this call. Each has the fields of get person.
`persons_updated`	array of object	Existing records the image was added to, one per face that matched a stored person.
`faces_total`	integer	How many faces were found on the image.
`matches`	array of object	The hits of every found face against the person lists. Empty when nothing matched.
`spent`	integer	Processing time in milliseconds.

HTTP 200. No new record: every face on the image matched a person already stored, so only persons_updated is filled.

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.

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/create" \
  -F "token=<your permanent API token>" \
  -F "list_id=<person list id>" \
  -F "fields=<your reference>" \
  -F "image=@photo.jpg"

Response:

{
  "status": "ok",
  "message": "<detail>",
  "persons_new": [
    {
      "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": []
    }
  ],
  "persons_updated": [],
  "faces_total": 1,
  "matches": [],
  "spent": 540
}