Skip to main content
Version: 11.3.0

Configuring Liveness-Only Verification (Anchor Image)

HYPR Affirm can verify identity by comparing a live selfie with an existing anchor image stored in your own directory or system of record (for example, Entra ID or Okta). When a usable anchor image is found, the requester does not upload a photo ID during the flow.

Liveness-only verification is a mode of the Photo ID and Liveness Capture step. An administrator sets it up with a developer: the developer writes the image repository customization, and the administrator attaches it to a verification flow. This page covers when to use it, how to set it up and how it behaves.

When to Use Liveness-Only Verification​

Liveness-only verification is intended for known users whose identities have already been vetted and who have a reliable photo stored in a corporate directory or another system of record. Example scenarios include:

  • Step-up authentication for workforce access: Verifying that a user attempting to access a sensitive system matches the person whose account is in the directory.
  • Help desk identity verification: Allowing support staff to confirm a caller’s identity by comparing a live selfie with a directory-sourced photo.
  • Ongoing re-verification: Re-validating identity for high-risk operations without repeatedly collecting document images.

In these scenarios, HYPR:

  • Fetches a reference image, the anchor image, from your configured image repository.
  • Performs liveness detection and facial comparison between the live capture and the anchor image.
Privacy and Data Ownership

Anchor images come from the directory or system of record that your image repository customization connects to (such as Entra ID or Okta). For how HYPR processes and retains biometric data, see the HYPR Affirm Biometric Data Policy and Consent and the HYPR Trust Center FAQ.

For the notice requesters see and the settings you control, see Biometric Data and the Privacy Notice.

Prerequisites and Limitations​

Before enabling liveness-only (anchor image) verification:

  • Directory images must exist and be accessible:
    • Your identity provider or system of record must maintain a usable photo for each target user.
    • The image should be reasonably recent and high enough quality for facial comparison.
  • Custom Image Repository customization is required:
    • HYPR uses a User Image Directory Source customization to implement anchor image retrieval logic.
    • A developer or system integrator needs to implement and deploy this customization for your environment.
  • Image size and format constraints apply:
    • The anchor-image attempt fails if the image is larger than 4MB, is not a JPEG or PNG image, or has no detectable face. The requester then uploads a photo ID instead.
  • Scope is limited to internal users:
    • Liveness-only is not a replacement for full KYC with document checks for unknown or external users.

If the anchor image cannot be obtained or does not meet quality requirements, HYPR does the following:

  • Records an AFFIRM_WORKFLOW_ANCHOR_IMAGE event with the reason in the Audit Trail.
  • Falls back to document upload: the requester uploads a photo ID, then takes the selfie.

Configure a Custom Image Repository​

Liveness-only verification relies on a custom image repository, implemented as a User Image Directory Source customization. This customization tells HYPR how to look up and return an anchor image for a given user.

  1. In HYPR Control Center, go to HYPR Affirm > Advanced Settings > Customizations.
  2. Click New Customization in the upper right.
HYPR Affirm Advanced Settings Customizations tab with the New Customization button at the upper right above the Customization Code editor
  1. Select the User Image Directory Source customization type. This customization acts as your image repository implementation.
New Code Customization dialog with the Customization Type list open and User Image Directory Source highlighted
  1. Add a name and description for the customization, and click Continue.
New Code Customization dialog with User Image Directory Source selected, a display name and description entered, and the Continue button
  1. Use the provided customization code sample script as a starting point. To edit the sample script, click Edit Mode. The script logic should do the following:
    • Accept the loginIdentifier.
    • Query your directory or system of record (for example Entra ID, Okta or a custom source).
    • Return the user attributes expected by HYPR Affirm, including the anchor image payload, in the output fields described in Custom Image Repository Contract (Input/Output).
  2. Save the customization.
  3. Test the customization with the Test function in the Customizations UI:
    • Click Execute Test to validate that the expected image is returned.
    • Confirm what happens when no anchor image is available.
Customization Code in Test Mode with a Test Payload containing a user's login identifier, empty Execution Results and the Execute Test button

Custom Image Repository Contract (Input/Output)​

When you implement the custom image repository code customization, use this baseline contract:

  • Input
    • loginIdentifier
  • Output
    • loginIdentifier
    • image (string-form image payload)
    • imageSourceType (base64, url or binary)

For image, HYPR supports these source patterns:

  • base64 (for example, data:image/png;base64,...)
  • url (retrievable image URL)
  • binary (hex-encoded binary payload, because customization output is string-based)

Supported Image Constraints​

The anchor image must meet these constraints:

  • Formats: PNG or JPEG
  • Maximum image size: 4MB

The anchor-image attempt fails if the image type, payload or size is invalid, or if no face can be found in the image. The requester then uploads a photo ID instead, and the step continues with the selfie.

Attach the Image Repository to a Verification Flow​

After you create and test your image repository customization, assign the User Image Directory Source customization to the verification flow and turn on the step.

  1. Go to HYPR Affirm > Verification Flows and click the row of the flow.
  2. In the left navigation pane, scroll down to Advanced Customization and select Image Directory.
  3. In the Custom Directory Source drop-down menu, select the customization you created.
Image Directory section with Custom Directory Source and Custom Writeback Directory drop-downs and a Writeback Rotation Interval of 7 Days

The Image Directory section. Custom Directory Source is the reading half used by this step; Custom Writeback Directory beside it sends captured images out, and is covered in Directory Image Writeback.

  1. In Verification Steps, turn on the Photo ID and Liveness Capture step. The Custom Directory Source is used with this step; there is no separate anchor-image setting on the step itself.
  2. Click Save at the top right of the flow editor.

For more information about User Directory customizations, see Customizations.

What the Requester Sees​

When the flow has a Custom Directory Source and a usable anchor image is found for the requester, the Photo ID and Liveness Capture step skips the photo ID upload and asks only for the selfie. When no usable anchor image is found, the requester uploads a photo ID and then takes the selfie. The selfie screens are the same in both cases; see What the Requester Sees on the Photo ID and Liveness Capture page.

Results, Retries and Failure Outcomes​

The step uses the same controls whether or not the flow has a Custom Directory Source: Retry Limit (attempt count and time window) and Failure Outcome. There is no anchor-image setting on the step.

To set them:

  1. Go to HYPR Affirm > Verification Flows and click the row of the flow.
  2. In the left navigation pane, click Verification Steps and find Photo ID and Liveness Capture.
  3. Set Retry Limit: the maximum number of attempts and the time window for those attempts.
  4. Select a Failure Outcome: Deny Verification, Redirect to URL (with a Redirect URL) or Continue Workflow (with an optional Escalate to Live Chat).
  5. Click Save at the top right of the flow editor.

The step's defaults are 3 attempts and Continue Workflow; see Photo ID and Liveness Capture. For what each failure outcome does, see Injectable Outcomes and Retry Limits.

When your tenant uses the Affirm Risk Policy Builder, the Policy Evaluation Kit assigned to the flow sets retries and failure outcomes instead of these controls. The step card then links to the flow's Advanced Customization > Risk Policy section, where you choose the kit. You build kits under HYPR Affirm > Affirm Risk Policy Builder.

Test Liveness-Only Flows​

After configuration, validate the behavior end to end:

  • User with anchor image:
    • Start a verification flow where the requester has a valid directory photo.
    • Confirm that the Photo ID and Liveness Capture step skips the photo ID upload, prompts for a selfie, and completes successfully when the face matches the anchor image and liveness checks pass.
  • User without anchor image:
    • Use a requester who does not have a directory photo, or temporarily remove the image from the directory.
    • Confirm that the flow prompts for a photo ID upload and then the selfie, and that the Audit Trail records an AFFIRM_WORKFLOW_ANCHOR_IMAGE event with the message "Fallback to document upload".

Monitoring and Events​

When liveness-only (anchor image) flows are enabled, the following event appears in the HYPR Audit Trail:

  • AFFIRM_WORKFLOW_ANCHOR_IMAGE Emitted when an anchor image is captured or associated with an Affirm workflow for visual verification. This event indicates that the liveness step attempted to use a directory-sourced reference image.

Each event carries a message giving the reason, for example "Anchor image does not exist", "Anchor image size is over 4MB", "Face could not be detected" or "Fallback to document upload".

For detailed event definitions, see Audit Trail Events.

To monitor liveness-only verification, use these records:

What to MonitorWhere It Is Recorded
Successful and failed attemptsLiveness Verified under Photo ID and Liveness Verification in the Activity Log, and AFFIRM_WORKFLOW_FACE_MATCH in the Audit Trail
Start and end of the stepAFFIRM_WORKFLOW_DOCUMENT_LIVENESS_START and AFFIRM_WORKFLOW_DOCUMENT_LIVENESS_FINISH in the Audit Trail
Missing or invalid anchor images, and validation failures for image source type, format and sizeAFFIRM_WORKFLOW_ANCHOR_IMAGE failures in the Audit Trail, for example "Anchor image source type is invalid (options are binary, base64 or url)" or "Anchor image format is invalid (only jpeg/png available)"
Fallbacks to document uploadAFFIRM_WORKFLOW_ANCHOR_IMAGE with "Fallback to document upload", followed by AFFIRM_WORKFLOW_DOCUMENT_UPLOAD for the photo ID

Comparing Available Photo and Liveness Options​

HYPR Affirm supports several patterns for combining photo, document and liveness verification:

  • Document and Biometric Verification: Suited to high-assurance onboarding and external KYC-like flows, with document authentication and optional compliance checks.
  • Photo ID and Liveness Capture (Document Upload): Suited to scenarios that rely on a visual comparison of the selfie with a photo ID, without document authentication.
  • Photo ID and Liveness Capture (Anchor Image or Liveness-Only): Suited to internal workforce scenarios where a trusted directory photo already exists and you want to reduce friction.

Choose the combination that best matches your risk profile and data governance requirements, and document your chosen pattern in internal runbooks so approvers and help desk staff understand how identity is being verified.