HomeDocumentationKnowledge HubSupportRelease NotesSearch Box
Documentation

Known Faces

Known Faces – API Integration Guide

Known Faces automatically performs a 1:N face match to detect if a submitted selfie matches any previously stored faces within a customer’s retention window — helping identify repeat users, fraudsters, or VIPs.

Activation

Known Faces is not enabled by default. To activate it, please contact your Trulioo Customer Success Manager or Product contact. Once enabled:

  • Trulioo will load up to 90 days (or your configured retention period) of historical selfies.
  • Filtering will exclude poor-quality images (e.g., face coverings, low light).

API Usage

No Separate API Call Required

Known Faces is auto-triggered during any DocV transaction that includes a selfie. Whether initiated via SDK or API, the system will:

  • Perform a 1:N match against your retained face gallery.
  • Return match results in the standard transaction response.

Response Payload

Matches are returned as part of the JSON response:

"knownFacesMatches": 
  {
    "transactionId": "18bd0254-12b9-48c3-a0bf-de95fb652c84",
    "imageId": "4c107eac-32a2-411e-b0ef-9d4b46a10c4f",
    "similarityScore": 100.0,
    "status": "DECLINED",
    "timeOfTransaction": "2025-05-21T23:10:43Z",
    "selfieUrl": "https://docv-dev-us-images.s3.amazonaws.com/4c107ea"
  },
  ...
]

Each match includes:

  • transactionId: Prior transaction where the face was seen
  • similarityScore: Confidence of the facial match
  • status: Outcome of the past transaction (e.g., DECLINED, ACCEPTED)
  • timeOfTransaction: Timestamp of the original submission
  • selfieUrl: Image URL (if enabled)

Key Notes

  • Known Faces does not alter transaction decisions. It simply surfaces matched history.
  • Match results are visible in:
    • API response under knownFacesMatches
    • Customer Portal > Known Faces tab
  • Uses the default retention period based on your agreement (extendable on request)
  • No self-serve enable/disable toggle; all config changes require CSM support

Access

  • Works across both SDK and API flows
  • Requires selfie image to be present in the transaction payload

For enablement or support, contact your Trulioo CSM or email [email protected]