Search faces in person lists

Purpose

Use this call to look a face up in your person lists, for example to find a returning person or to check a blocklist. Each processed face is recorded as an action and attributed to a data source group and a data source. Persons can be created automatically by the new_person_* rules.

Request

POST <API_BASE_URL>/face/search. 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.

Field	Type	Required	Description
`token`	string	if no header	Your permanent API token. Required unless you send a user token in the `token` header.
`image`	file	yes	The image file. It can contain several faces; see `multi`.
`group_id`	string (uuid)	no	The data source group the action is attributed to.
`source_id`	string (uuid)	no	The data source the action is attributed to.
`multi`	boolean	no	Search every face found. When `false`, only the largest face is processed.
`person_list_search`	array of string (uuid) or string	no	The person list or lists to search. When left out, only the default list is searched.
`person_list_add`	array of string (uuid) or string	no	The list or lists in which persons are created automatically. It is required for person creation.
`new_person_threshold`	value	no	The match threshold for creating a person. The value `never` creates no person; `no_match` uses the platform default.
`results`	string or number	no	How many matching persons to return per face, sorted by distance.
`threshold`	string or number	no	The distance threshold of a match.
`feature_check`	array of object or string	no	A feature name or an array of names to detect on each found face, for example `age`, `gender`, `mood`, `glasses`, `mask` or `quality`. The schema lists the full set of names.
`drop_image`	boolean	no	Do not store the image in the actions history.
`person_data`	boolean	no	Include person data in the matches.

Response

HTTP 201. At least one face was found, recorded and searched.

Field	Type	Description
`status`	string	Always `ok` on this body.
`faces_total`	integer	How many faces the detector found on the image.
`spent`	integer	Processing time in milliseconds.
`results`	array of object	One entry per processed face.
`results[].action_id`	string (uuid)	The identifier of the action this face was recorded as.
`results[].matches`	array of object	The hits of this face against the lists you searched, sorted by distance.
`results[].persons`	array of object	The persons created from this face under the `new_person_*` rules. Null when nothing was created.
`results[].group_id`	string (uuid)	The data source group the action was attributed to.
`results[].source_id`	string (uuid)	The data source the action was attributed to.
`results[].yaw`	number	Head rotation left or right, in degrees.
`results[].pitch`	number	Head tilt up or down, in degrees.

HTTP 200. No face was found on the image; results is empty.

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>/face/search" \
  -F "token=<your permanent API token>" \
  -F "image=@photo.jpg" \
  -F "person_list_search=<person list id>" \
  -F "multi=false"

Response:

{
  "status": "ok",
  "message": "<detail>",
  "faces_total": 1,
  "spent": 560,
  "results": [
    {
      "action_id": "<action id>",
      "group_id": "<group id>",
      "source_id": "<source id>",
      "matches": [],
      "persons": null,
      "yaw": 4,
      "pitch": -2
    }
  ]
}