Skip to main content
Version: 11.3.0

Directory Image Writeback

Directory Image Writeback lets administrators push verification images (selfies, document captures, biometric evidence captures) captured during an Affirm verification flow directly to enterprise directories — Microsoft Entra ID, Okta, Ping Identity, or a custom endpoint — without persisting those images in HYPR.

This supports privacy-by-design and data-minimization requirements: HYPR processes the verification, transmits the images to the configured target after a successful outcome, and does not retain copies in the HYPR database.

Available in 11.3

Directory Image Writeback is a new feature in HYPR 11.3. Tenant enablement is required — coordinate with your HYPR representative for activation. See the Feature Flags Reference for the canonical flag identifier.

How it works​

After a verification flow completes with an outcome that satisfies the configured outcome gating (PASS only, PASS + no escalation, or PASS + manual approval), HYPR sends the configured set of images to the configured target via a code-customization script (the USER_DIRECTORY_IMAGE_WRITEBACK hook).

The transmission is synchronous; HYPR retries on failure according to the configured attempt limit, and emits writeback lifecycle events (AFFIRM_WRITEBACK_TRIGGERED, _SUCCESS, _SKIPPED, _FAILURE, _EXHAUSTED) to the Audit Trail for full operational visibility. Images are never stored in the HYPR database or surfaced in the HYPR UI.

Configurable elements​

The Directory Writeback configuration UI provides the following controls:

  • Writeback target — choose the destination (Entra ID, Okta, Ping, or a custom endpoint). Each target accepts its own per-tenant credentials.
  • Per-workflow enablement — enable writeback for a specific verification flow, leave others unaffected.
  • Per-step enablement — independently enable writeback for the Photo and Liveness step (selfie) and the Document and Biometric step (document captures + biometric evidence capture).
  • Per-image-type attribute mapping — map each image type (selfie, document front, document back) to a destination attribute on the target system.
  • Rotation / frequency policy — limit how often a given user's image is pushed (for example, "update at most every 12 months" to reduce write volume on repeat verifications).
  • Outcome gating — choose when the writeback fires:
    • PASS only — fire on any successful outcome
    • PASS + no escalation — fire only when the flow passed without entering escalation
    • PASS + manual approval — fire only after an approver explicitly approved
  • Retry policy — set the maximum number of retry attempts on transient failure. After the attempt limit is exhausted, the writeback is marked as failed and the AFFIRM_WRITEBACK_EXHAUSTED event is emitted.

Approver-visible face comparison​

When Directory Image Writeback is configured, the face-from-video extracted during the requester's liveness capture becomes visible to the approver in the Scorecard's Photo ID and Liveness section — side by side with the face extracted from the requester's submitted document.

Photo ID and Liveness panel showing the face extracted from the document (left) and the face extracted from the liveness video (right). The face-from-video render depends on Directory Image Writeback being active for the workflow.

Without Directory Image Writeback, the document face remains visible but the face-from-video does not render in the Scorecard. See What the Approver Sees for the full Scorecard flow.

Code Customization hook​

The actual writeback is performed by a Code Customization script registered with the type USER_DIRECTORY_IMAGE_WRITEBACK. HYPR invokes the script with the captured images (Base64-encoded) and a workflow context. The script is responsible for persisting the images to the target system and returning a success/failure outcome. See Affirm Customizations → Image Writeback for the input/output contract.

Audit and observability​

Writeback activity is fully visible in the Audit Trail and via the Affirm API:

  • AFFIRM_WRITEBACK_TRIGGERED — writeback was initiated for a verification outcome
  • AFFIRM_WRITEBACK_SUCCESS — writeback completed successfully (initial attempt or after retry)
  • AFFIRM_WRITEBACK_SKIPPED — writeback was suppressed because the image is within the configured rotation window
  • AFFIRM_WRITEBACK_FAILURE — writeback attempt failed, includes error reason and retry count
  • AFFIRM_WRITEBACK_EXHAUSTED — all retry attempts exhausted, writeback abandoned

See Audit Trail for the canonical event reference.

Use cases​

  • Employee onboarding — capture identity documents and selfies during the onboarding verification, write them to the employee record in an external directory without HYPR retention
  • Periodic re-verification with capped image refresh — re-verify quarterly but only refresh the stored image yearly (rotation policy)
  • Privacy-regulated jurisdictions — combine with short-retention data residency settings to minimize the time images exist anywhere