Face Match API - Detailed Documentation

Facematch provides biometric face comparison as a standalone service or as a building block in composite flows. You can compare:

Two open images (Base64 JPEG/PNG)
Two biometric templates
Open image ↔ biometric template
ID document portrait (TokenFaceImage) ↔ image/template Optionally enable Liveness to add passive liveness analysis in the same request.

API Playground:

/faceMatch

You can try the openJourney endpoint here.

Endpoints Overview

Face Match: Compare two faces and return a similarity score and decision.

Authentication

To access the Address Verification API, authentication is required. A Bearer Token must be included in every request.

Tokens are valid for 60 minutes and must be refreshed after expiration.
Refer to the Authentication for detailed steps on obtaining a token.
Include the token in the Authorization header as follows:

Authorization: Bearer YOUR_ACCESS_TOKEN

API Base URL

Production:

https://api-umbrella.io/api/services

Sandbox:

https://sandbox-umbrella-api.azurewebsites.net/api/services

1. Face Match

Endpoint

POST /faceMatch

Description

This endpoint compares two faces and return a similarity score and decision.

Required Headers

Header	Value
Content-Type	`application/json`
Authorization	`Bearer yourAccessToken`

Request Body Parameters

Field	Type	Required	Description
`comparisonMethod`	string (enum)	Yes	One of:`openImages` (image vs image), `biometricTemplates` (template vs template), `imageToTemplate` (image ↔ template), `docPhotoToImage` (ID portrait token ↔ image), `docPhotoToTemplate` (ID portrait token ↔ template)
`token1`	string	Yes	First face source. Base64 image, template raw, or `tokenFaceImage` per method.
`token2`	string	Yes	Second face source. Base64 image or template raw per method.
`livenessMode`	string (enum)	No	`none` (default) or `passive`. When not `none`, liveness is evaluated for `token2` (the selfie).
`decisionThreshold`	number	No	Default `0.85`. Score ≥ threshold → `approve`; otherwise `decline` (unless policy uses `review`).
`callbackUrl`	string (URL)	No	If set, returns 202 with `RequestId` and posts a webhook upon completion.
`externalReferenceId`	string	No	Your correlation ID, echoed in responses/webhooks.
`idempotencyKey`	string (UUID)	No	Required when `callbackUrl` is used. Prevents duplicate processing.
`tracking.extraData`	string (Base64)	No	Tokenized SDK tracking blob.
`tracking.operationId`	string	No	Client-side operation identifier.

Response Structure

Field	Type	Description
`status`	string	`success`, `accepted`, or `error`.
`requestId`	string	Server-side identifier for this request.
`externalReferenceId`	string	Echo of your correlation ID.
`decision`	string	`approve`	`decline`	`review` (threshold/policy-based).
`facialSimilarityScore`	number	0..1 (1.0 = identical).
`facialAuthenticationResult`	integer	Provider result code (e.g., 3 = positive).
`serviceResultCode`	integer	Provider execution code (0 = OK).
`serviceResultLog`	string	Execution log / reason.
`serviceTimeMs`	integer	Processing time (ms).
`transactionId`	string	Upstream transaction ID.
`facialAuthenticationHash`	string	Integrity hash for template comparisons.
`liveness.livenessStatus`	string	`pass`	`fail`	`inconclusive`	`notPerformed`.
`liveness.livenessScore`	number	Confidence when liveness is performed.
`liveness.hints`	string[]	Optional guidance/quality hints.
`policy.decisionThreshold`	number	Effective threshold used.

Example Request

{
  "comparisonMethod": "openImages | biometricTemplates | imageToTemplate | docPhotoToImage | docPhotoToTemplate",
  "token1": "BASE64_OR_TEMPLATE_OR_TOKEN",
  "token2": "BASE64_OR_TEMPLATE_OR_TOKEN",
  "livenessMode": "none | passive",
  "decisionThreshold": 0.85,
  "callbackUrl": "https://example.com/webhooks/faceMatch",
  "externalReferenceId": "your-id-123",
  "idempotencyKey": "0e2b7a6c-5a6f-4f5e-8e88-0b0f29b87f2a",
  "tracking": {
    "extraData": "BASE64_TRACKING_BLOB",
    "operationId": "abcde-12345-xyz"
  }
}

Example Response

{
  "status": "success",
  "requestId": "a29cbe15-2b68-495f-b7eb-be985b21c486",
  "externalReferenceId": "your-id-123",
  "decision": "approve | decline | review",
  "facialSimilarityScore": 0.9915,
  "facialAuthenticationResult": 3,
  "serviceResultCode": 0,
  "serviceResultLog": "positive",
  "serviceTimeMs": 516,
  "transactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486",
  "facialAuthenticationHash": "47D0ACD...74289E",
  "liveness": {
    "livenessStatus": "pass | fail | inconclusive | notPerformed",
    "livenessScore": 0.97,
    "hints": ["low_light"]
  },
  "policy": {
    "decisionThreshold": 0.85
  }
}

Getting Started

Essentials

Face Match

Face Match API - Detailed Documentation

API Playground:

Endpoints Overview

Authentication

API Base URL

Production:

Sandbox:

1. Face Match

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Example Request

Example Response

​Face Match API - Detailed Documentation

​API Playground:

​Endpoints Overview

​Authentication

​API Base URL

​Production:

​Sandbox:

​1. Face Match

​Endpoint

​Description

​Required Headers

​Request Body Parameters

​Response Structure

​Example Request

​Example Response

Face Match API - Detailed Documentation

API Playground:

Endpoints Overview

Authentication

API Base URL

Production:

Sandbox:

1. Face Match

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Example Request

Example Response