Skip to main content

​
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

  1. 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

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

​
1. Face Match

​
Endpoint

POST /faceMatch

​
Description

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

​
Required Headers

HeaderValue
Content-Typeapplication/json
AuthorizationBearer yourAccessToken

​
Request Body Parameters

FieldTypeRequiredDescription
comparisonMethodstring (enum)YesOne of:openImages (image vs image), biometricTemplates (template vs template), imageToTemplate (image ↔ template), docPhotoToImage (ID portrait token ↔ image), docPhotoToTemplate (ID portrait token ↔ template)
token1stringYesFirst face source. Base64 image, template raw, or tokenFaceImage per method.
token2stringYesSecond face source. Base64 image or template raw per method.
livenessModestring (enum)Nonone (default) or passive. When not none, liveness is evaluated for token2 (the selfie).
decisionThresholdnumberNoDefault 0.85. Score ≥ threshold → approve; otherwise decline (unless policy uses review).
callbackUrlstring (URL)NoIf set, returns 202 with RequestId and posts a webhook upon completion.
externalReferenceIdstringNoYour correlation ID, echoed in responses/webhooks.
idempotencyKeystring (UUID)NoRequired when callbackUrl is used. Prevents duplicate processing.
tracking.extraDatastring (Base64)NoTokenized SDK tracking blob.
tracking.operationIdstringNoClient-side operation identifier.

​
Response Structure

FieldTypeDescription
statusstringsuccess, accepted, or error.
requestIdstringServer-side identifier for this request.
externalReferenceIdstringEcho of your correlation ID.
decisionstringapprovedeclinereview (threshold/policy-based).
facialSimilarityScorenumber0..1 (1.0 = identical).
facialAuthenticationResultintegerProvider result code (e.g., 3 = positive).
serviceResultCodeintegerProvider execution code (0 = OK).
serviceResultLogstringExecution log / reason.
serviceTimeMsintegerProcessing time (ms).
transactionIdstringUpstream transaction ID.
facialAuthenticationHashstringIntegrity hash for template comparisons.
liveness.livenessStatusstringpassfailinconclusivenotPerformed.
liveness.livenessScorenumberConfidence when liveness is performed.
liveness.hintsstring[]Optional guidance/quality hints.
policy.decisionThresholdnumberEffective 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
  }
}
⌘I