POST /Document/facematch

Compares a selfie against the photo on one or more identity documents. Use it in onboarding and KYC flows, where you already hold a captured selfie and the identity document the applicant uploaded.

Endpoint

POST https://api-us.cogneris.ai/Document/facematch

Authentication

Send your API key as a Bearer token. See Getting Started for how to generate one.

Authorization: Bearer xtkt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Request

Content-Type: multipart/form-data

Field	Type	Required	Description
selfie	file	✅	The captured selfie to compare. Exactly one.
documents	file (repeatable)	✅	One or more identity documents to compare the selfie against. Repeat the documents field for each file.

Constraints

• Allowed extensions: .pdf, .png, .jpg, .jpeg, .tiff, .tif, .bmp, .doc, .docx.
• Max size: 10 MB per file.
• Rate limit: 50 requests per API key per fixed 1-minute window.

Example

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $COGNERIS_API_KEY" \
  --form "selfie=@./selfie.jpg" \
  --form "documents=@./passport.jpg" \
  --form "documents=@./drivers-licence.jpg" \
  "https://api-us.cogneris.ai/Document/facematch"

Response

200 OK — the standard service envelope. data.metadata carries the comparison result; its exact shape is driven by the configured engine, so read it defensively rather than assuming a fixed field set.

{
  "data": {
    "id": "7c3e9a10-42bd-4f6a-9e21-8b0c5d7f1234",
    "metadata": {
      "...": "engine-specific comparison payload"
    },
    "createdDate": "2026-08-07T09:14:33Z"
  },
  "meta": { "httpStatusCode": 200, "messages": [] },
  "hasErrors": false
}

Notes

• This endpoint is synchronous only. Unlike extraction, classification, zero-shot, crop and split, it has no counterpart operation on POST /api/v1/document-jobs.
• Both fields are required. Posting a selfie with no documents, or documents with no selfie, fails validation.

Errors

See API errors. The usual cases here are 401 for a key that does not begin with xtkt_live_, 413 for a file over 10 MB, 415 for an unsupported extension, and 429 when the per-key window is exhausted.