Face matching
Compare one enrollment face with one verification face. This is a one-to-one comparison, not a collection-wide search or a liveness check.
Enrollment source, in order of precedence:
- enroll_image: a base64-encoded image.
- enroll_session_id: a Verilive session with a stored bestframe image.
- The face stored for person_id in enroll_collection (default:
default). This fallback is used only when neither enrollment image
nor enrollment session is supplied.
Supply verif_image or verif_session_id for the verification face. Both session ID inputs support only Verilive sessions with a stored bestframe image. If both are supplied, the image takes priority.
Supply person_id, or omit it to get it from verif_session_id. An enrollment session alone does not supply the person ID. flow_id optionally associates the comparison with a flow; otherwise the service obtains an automatic flow ID. enroll_custom_collection is required whenever enroll_collection is custom.
HTTP 201 contains a completed Veriface session with result.action: verify and an integer similarity score from 0 to 100. match maps to session_status: pass, and mismatch maps to fail. Both outcomes return HTTP 201.
Missing required inputs or a missing enrollment database record produce HTTP 422.
curl -X POST "https://demo.verigram.kz/faces:match" \
-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",
"enroll_session_id": "enrollment-session-S",
"verif_session_id": "verification-session-S"
}'Авторизация
X-Verigram-Api-KeystringheaderобязательноAPI key in the X-Verigram-Api-Key header
Параметры
X-Verigram-Api-VersionstringheaderобязательноRequired API version header.
Значение по умолчанию:2.0.0
Тело
person_idstringPerson ID
flow_idstringFlow ID
enroll_collectionenum<string>Collection name. Default is 'default'.
Одно из:blacklistwhitelistgraylistwatchlistdefaultcustomЗначение по умолчанию:defaultenroll_custom_collectionstringCustom collection name, use when 'enroll_collection' is set to 'custom'
enroll_imagestring<byte>Base64 encoded image
enroll_session_idstringSession ID from which to get the enrollment image
verif_imagestring<byte>Base64 encoded image
verif_session_idstringSession ID from which to get the verification image
Ответ
Completed comparison, both match and mismatch 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-match-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": "match",
"action": "verify",
"score": 96,
"collection": null,
"custom_collection": null,
"error_code": null,
"error_msg": null,
"created_at": "2026-10-02T10:00:01Z",
"created_by": "system"
}
}