Find a face
Search for a face in collection in one of two ways:
- Pass person_id to look up that exact stored record.
- Pass a base64-encoded image to search for a similar face in the collection.
When both person_id and image are supplied, the person_id lookup takes prority and the image is ignored.
At least one of person_id or image is required. collection defaults to default, custom_collection is required when collection is custom.
HTTP 201 contains a completed session projection with service_name: veriface and result.action: find. A found record gives session_status: pass and service_status: positive, no match gives fail and negative. For image-only searches, the session's person_id is the consumer ID, not a matched person's ID.
curl -X POST "https://demo.verigram.kz/faces:find" \
-H "X-Verigram-Api-Key: $IDENTIFICATION_SAAS_API_KEY" \
-H "X-Verigram-Api-Version: 2.0.0" \
-H "Content-Type: application/json" \
-d '{
"person_id": "person-123"
}'Авторизация
X-Verigram-Api-KeystringheaderобязательноAPI key in the X-Verigram-Api-Key header
Параметры
X-Verigram-Api-VersionstringheaderобязательноRequired API version header.
Значение по умолчанию:2.0.0
Тело
collectionenum<string>Collection name. Default is 'default'.
Одно из:blacklistwhitelistgraylistwatchlistdefaultcustomЗначение по умолчанию:defaultcustom_collectionstringCustom collection name, use when 'collection' is set to 'custom'
person_idstringIdentifier of a person associated with the session. Alphanumeric string.
imagestring<byte>Base64 encoded image
session_idstringSession ID to get the search image from
Ответ
Completed lookup, both positive and negative results return HTTP 201.
session_idstringUnique identifier for the session.
person_idstringIdentifier of a person associated with the session. Alphanumeric string.
consumer_idstringIdentifier of the consumer who owns the session.
flow_idstring | nullIdentifier of the flow associated with the session.
vlink_idstring | nullIdentifier of the vlink associated with the session.
api_versionstringThe version of the API used to create and process this session.
service_nameenum<string>Одно из:veriliveverilive-one-shotverilive-infraredverifaceveridockiscredocegov-docaml-cftflow-formconsentveriphoneesignkyc-listotpnotificationdevice-filterdoc-previewdoc-builderfile-storageclient-carderdinterrupterlanguage-selectoramlcft-servicesession_statusenum<string>The main status of a flow or a service. Helps to make a binary decision whether the flow/service was successful or not. If "pass" - the flow/service was successful, unsuccessful otherwise.
Одно из:passfailunknowntest_sessionboolean | nullWhether the session was created for test purposes.
step_idstring | nullprocessstring | nulluser_ipstring | nullvendorstring | nullcreated_atstring<date-time>Timestamp when the session was created.
updated_atstring<date-time>Timestamp of the last update to the session's state.
session_statesSessionState[]History of execution states reached by this session.
resultone of
{
"session_id": "face-positive-S",
"person_id": "person-123",
"consumer_id": "consumer-123",
"flow_id": "face-flow-F",
"api_version": "2.0.0",
"service_name": "veriface",
"session_status": "pass",
"created_at": "2026-10-02T10:00:00Z",
"updated_at": "2026-10-02T10:00:01Z",
"session_states": [
{
"state_name": "created",
"created_at": "2026-10-02T10:00:00Z"
},
{
"state_name": "processed",
"created_at": "2026-10-02T10:00:01Z"
}
],
"result": {
"service_name": "veriface",
"service_status": "positive",
"action": "find",
"score": null,
"collection": "default",
"custom_collection": null,
"error_code": null,
"error_msg": null,
"created_at": "2026-10-02T10:00:01Z",
"created_by": "system"
}
}