Affirm Customizations (Code Customization API)

Customizations

Code customizations override HYPR Affirm's default behavior at defined points in the verification flow. This page describes the contracts of the following customization types, listed by their names in the Customization Type drop-down:

• User Directory Source
• SMS Sending and SMS Verifying
• Email Sending
• Outcome API Call
• User Image Writeback Directory

The drop-down also lists the following types:

• User Image Directory Source: fetches a reference image for the Photo ID and Liveness Capture step. See Configure a custom image repository.
• User Phone Number Directory Source, User Email Directory Source and User Extended Info Directory Source: assigned under the flow's Advanced Customization > User Directory
• Custom Step Preprocessor, Custom Step Function and Custom Step Postprocessor: listed when custom verification steps are enabled for your tenant. See Custom Verification Step.

OIDC client settings are not a code customization. See OIDC Settings.

You manage code customizations in HYPR Affirm > Advanced Settings > Code Customizations. Advanced Settings is the tab inside the HYPR Affirm menu, not the Control Center Advanced View toggle.

Customization scripts run in an ES2022 runtime. This page is the contract reference. For the script entry point, design patterns, error handling and the edit-and-test workflow, see Writing Affirm Code Customizations.

Execution Timeout

Code customization scripts time out after 6 seconds by default. The timeout is a server setting; contact your HYPR representative to change it for your deployment. The timeout matters for customizations that upload files, call external APIs or run other operations that can take longer.

You assign each customization to a verification flow in that flow's configuration in the Verification Flows editor. For example, you assign a User Image Directory Source customization under Advanced Customization → Image Directory, in the Custom Directory Source drop-down. For an end-to-end example, see Liveness-Only (Anchor Image). You can also assign customizations with the Affirm API.

Create a Customization

1. Click New Customization.

   

2. Choose the type of customization from the Customization Type drop-down. The drop-down lists every customization type the tenant supports.

   

   Choosing the customization type. Each type is described later on this page.

3. Enter the required details.

4. Click Continue to save the customization.

5. Choose your new customization from the drop-down menu.

6. Turn on Edit Mode to edit the customization.

7. Add custom attributes to set the sensitive values your customization uses. Custom attributes are protected by encryption.

   

8. Click Save when you are finished or ready for testing, or click Discard to undo your changes.

9. Click Test.

10. Enter input values and click Execute Test to confirm the customization works.

    

11. Click Exit Test when you are done.

User Directory

The User Directory customization sets the source of user information. Without it, Affirm gets user information from one of the following sources, depending on whether the verification flow was created in the UI or with the API:

• The assigned integration
• The API, which provides all of the user information

When you assign a user directory source customization to a verification flow, Affirm looks up the user information with a REST call instead. This gives you control over how user information reaches HYPR Affirm.

The customization receives the following inputs.

Input	Description
loginIdentifier	The username of the subject
isApprover	A Boolean indicating whether the user is the requester or the approver. [ true | false ]

The script returns the following outputs.

Output	Required	Description
loginIdentifier	Always	The username of the user
email	Flow-dependent	The email of the user. Required when the verification flow includes the Phone Number / Email Verification step or sends approver-invitation emails.
firstName	Flow-dependent	The first name of the user
lastName	Flow-dependent	The last name of the user
mobilePhone	Flow-dependent	The mobile phone number of the user. For example, +15555555555
streetAddress	Flow-dependent	The street address of the user. For example, 20 W 34th St
city	Flow-dependent	The city of the user. For example, New York
state	Flow-dependent	The state of the user. For example, NY
postalCode	Flow-dependent	The postal code of the user. For example, 10001
countryCode	Flow-dependent	The country code of the user. For example, US
status	Always	The status of the user. [ ACTIVE_FOR_AFFIRM | INACTIVE_FOR_AFFIRM ]
managerLoginId	Flow-dependent	The username of the user's manager. Affirm uses this value to look up the manager if the verification flow requires it, as the loginIdentifier in a separate lookup.
buildingNumber	Flow-dependent	The building number of the user's address
dateOfBirth	Flow-dependent	The date of birth of the user

Handling Non-required Fields

You can omit a flow-dependent field from the return object, or pass null, when the field does not apply to the verification flow. For example, if the verification flow has no Location step, you can omit any of the address fields or pass null.

When the script cannot obtain the user directory record, it can return an empty object {}. To handle an error or condition of your own, return a custom error such as { error: "My error message"}.

SMS Sending

The SMS Sending customization sends SMS messages through a custom REST call instead of HYPR's SMS service.

When isApprover is true, secret is the magic link that opens the flow for the approver. When isApprover is false, secret is the SMS code the requester must verify.

The customization receives the following inputs.

Input	Description
loginIdentifier	The username of the user
phoneNumber	The mobile phone number of the user
isApprover	A Boolean string denoting whether the SMS is for a user or an approver. [ true | false ]
secret	The secret portion of the SMS
formattedMsg	The formatted message sent to the user or approver, which also contains the secret

The script returns the following output.

Output	Description
isSuccess	The result of the REST call, as a string. [ "true" | "false" ]

SMS Verifying

The SMS Verifying customization handles the result of a verified SMS code through a custom REST call instead of HYPR's SMS service.

The customization receives the following inputs.

Input	Description
loginIdentifier	The username of the requester
phoneNumber	The mobile phone number of the requester
inputCode	The SMS code the requester entered
result	A Boolean string denoting whether the requester entered the correct SMS code. [ true | false ]

The script returns the following output.

Output	Description
isSuccess	The result of the REST call, as a string. [ "true" | "false" ]

Email

The Email customization sends email through a custom REST call instead of HYPR's SMTP servers.

When isApprover is true, the email subject and body invite the approver to a user's flow for live attestation.

When isApprover is false, the email delivers the one-time verification code to the requester for the Phone Number / Email Verification step.

The customization receives the following inputs.

Input	Description
loginIdentifier	The username of the user
recipient	The email address of the user
isApprover	A Boolean string denoting whether the email is for a user or an approver. [ true | false ]
subject	The subject title of the email
htmlBody	An HTML representation of the email
textBody	A text-only representation of the email

The script returns the following output.

Output	Description
isSuccess	The result of the REST call, as a string. [ "true" | "false" ]

Outcome API Call

The Outcome API Call customization runs custom API calls before Affirm issues the configured outcome to the user.

When the user is approved and the verified outcome is set to display results to the user, the customization can display custom results to the user. Otherwise, the customization runs silently in the background.

For a worked example, see Issue a pass outside 60 to 480 minutes, which creates an Entra Temporary Access Pass with a lifetime the built-in outcome cannot produce.

If the workflow is approved but the Outcome API Call customization fails, the user can be failed if necessary. If the script returns an empty result or throws an error, Affirm treats the call as isSuccess false.

The customization receives the following inputs.

Input	Description
loginIdentifier	The username of the user
email	The email address of the user
isApproved	A Boolean denoting whether the user is approved according to the verification flow. [ true | false ]
workflowId	The Workflow ID of the user's verification flow instance

The script returns the following outputs.

Output	Description
isSuccess	The result of the custom outcome API call. [ true | false ]
outcomeToDisplay	The string Affirm displays when the user is approved and the verification flow has a verified outcome set to display results to the user. Return null otherwise.

Image Writeback

The USER_DIRECTORY_IMAGE_WRITEBACK customization lets administrators write images captured during a verification step back to an external user directory, such as Entra ID, Okta, Ping Identity or a custom destination. The script receives the captured images and saves them to the target system.

Affirm runs this customization when Directory Image Writeback is enabled on a verification flow and a verification of that flow is approved.

The customization receives the following inputs.

Input	Type	Description
loginIdentifier	String	The username of the subject
workflowId	String	The ID of the verification workflow instance
images	List<WritebackImage>	List of image objects to write back, described in the following table

Each WritebackImage object has the following fields.

Field	Type	Description
sourceType	String	The verification step and capture that produced the image. See the values in the following table
imageBytes	String	Base64-encoded image data
imageFormat	String	Image format. [ jpeg | png ]
documentType	String	The document type reported for a document capture, for example passport or driving_licence. Omitted for selfies
isCropped	Boolean	true for a cropped face extract, false for a full-frame capture

sourceType takes one of the following values.

Value	Produced by
PHOTO_ID_AND_LIVENESS_SELFIE	Photo ID and Liveness — the selfie
PHOTO_ID_AND_LIVENESS_DOCUMENT	Photo ID and Liveness — the document
DOCUMENT_AND_BIOMETRICS_SELFIE	Document and Biometric — the selfie
DOCUMENT_AND_BIOMETRICS_DOCUMENT_FRONT	Document and Biometric — primary document, front
DOCUMENT_AND_BIOMETRICS_DOCUMENT_BACK	Document and Biometric — primary document, back
DOCUMENT_AND_BIOMETRICS_DOCUMENT_SECONDARY_FRONT	Document and Biometric — second document, front
DOCUMENT_AND_BIOMETRICS_DOCUMENT_SECONDARY_BACK	Document and Biometric — second document, back

The script returns the following output.

Output	Description
outcome	Result of the writeback. [ SUCCESS | FAILURE ]

On failure or exception, the script can return { "error": "My error message" } instead of an outcome field. Affirm treats it as a failure and puts your message in the audit record.

Affirm handles the script's result as follows:

• If the script returns { "outcome": "SUCCESS" }, the writeback is recorded as successful.
• If the script returns { "outcome": "FAILURE" }, returns no outcome or throws an error, the attempt is retried. HYPR sets the retry count (three attempts by default), and each failed attempt is recorded as AFFIRM_WRITEBACK_FAILURE with its reason.
• A writeback that does not succeed leaves the verification outcome unchanged. The result is visible in the Audit Trail.

For how HYPR processes and retains biometric data, see the HYPR Affirm Biometric Data Policy and Consent.

Related

• Writing Affirm Code Customizations — developer guide to building a customization against the contracts on this page
• Affirm Studio (Admin) — end-user screen content and style customization
• Directory Image Writeback — admin configuration for the USER_DIRECTORY_IMAGE_WRITEBACK customization
• Risk-Signal Escalation Policy — how per-action policy rules decide whether a verification is denied, escalated, redirected or continued
• Advanced Setup — integration prerequisites and IdP attribute requirements
• Affirm Content Customization API — API reference