VerifEye Face API Release Notes

Version History

Release Date: 2026-11-03

Idempotency-Key on onboard: send the header and a retry after your client timed out or lost the response returns the original result, including the original faceId, instead of onboarding again. Optional, onboard only. See Idempotent retries.

Onboard can answer 503 with Retry-After: when the faces cannot be onboarded right now, wait the seconds in the header and send the same request again. See Onboard.

Release Date: 2026-09-28

external-key/get-face-id: looks up the face an external key is associated with and answers with just its faceId. See Get Face ID by External Key.

external-key/get-face-ids is deprecated: switch to get-face-id, which returns the same faceId without the deprecated faceIds array. get-face-ids stays supported until 31 December 2026 and is removed after that date.

Release Date: 2026-09-28

Stored images: an image can be uploaded once (POST /v1/image/upload) and referred to by its id as image.id on onboard, identify and compare, for up to 30 days. GET /v1/image/get returns a stored image and DELETE /v1/image/delete removes one. Reading an image back needs image access enabled on the account — contact support. See Stored Images.

Release Date: 2026-09-24

external-key/get-face-ids now answers with a single faceId: an external key is associated with exactly one face, so the response carries that face id directly instead of leaving you to unwrap a one-element array. The faceIds array is still returned and still holds the same id, but it is now deprecated: it stays supported until 31 December 2026 and is removed after that date. Read faceId and you are ready for that.
allowDuplicates removed from external-key/set: the parameter offered to map one external key to several faces, which the rest of the API never supported - a lookup, an onboard result and an identify result each carry one face per key. Every external key in production maps to a single face, so nothing changes for your integration, and a request that still sends the field is accepted with the field ignored. Setting a key that is already associated with a different face is rejected with 400 and a message naming the association to remove first.

Release Date: 2026-09-10

Image URLs behind a CDN or a bot filter now download: the fetch of your image.url identifies itself with a User-Agent. Hosts that refuse a request without one - a common CDN and bot-filter default - answered 403 or 406, and the call came back saying the image could not be downloaded, for an image that opens in your own browser. If you worked around that by re-hosting such images, you no longer need to.

Release Date: 2026-08-06

Initial Release: First public release of the VerifEye Face API — the single entry point for face onboarding, identification and analysis.
Onboard (POST /v1/face/onboard): looks every face on the image up in the collection and adds the ones that are not already there.
Identify (POST /v1/face/identify): looks every face on the image up in the collection and never adds anything.
Compare (POST /v1/face/compare): the 1:1 check. Scores the faces on an image against one face already in the collection, named by its faceId, and answers similarity and isMatch for each. The collection is never searched and never written to. Use it when you already know who the person claims to be; use Identify when you do not.
Optional attributes: request the age, gender, emotions and attention of every face alongside its face id through the include object, in the same call.
Multiple faces per call: maxFaces answers about up to 4 faces on one image; every face left out is counted in unprocessedFaceCount.
Collection management: create, retrieve, update, reset and delete collections.
External keys: associate your own identifier with a face and look faces up by it (set, get-face-ids, delete).

The VerifEye Face API supersedes the Face Recognition, Face Verification, Demographic Estimation and Emotion & Attention APIs for new integrations. Those APIs continue to work unchanged until September 30, 2026, after which they will be retired.

For the latest updates, visit the VerifEye Developer Console