Configuring End User Screen Customizations

This guide describes how to set up and apply end-user screen customizations for HYPR Affirm with Affirm Studio and the Content Customization API.

Scope

This article focuses on enabling the feature, managing content through Control Center or the API and applying customizations to workflows. For what users see on each screen, branding guidelines and examples, see User Experience: Affirm Studio.

General Branding

For general branding customization (your logo and background image, or a solid background color), see Custom Branding.

Prerequisites

Before you begin, make sure you have the following:

• HYPR Control Center access with Affirm administration permissions
• HYPR 10.7.0 or later (for Control Center UI)
• HYPR 10.3.0 or later (for API-only configuration)
• API access credentials (if using API-based configuration)

Permissions

Only Control Center administrators can create, edit and manage content customizations.

Creating Content Customizations

You can create and manage content customizations in the Control Center user interface (HYPR 10.7.0 and later) or with the REST API.

Prepare Your Content

Before you create content customizations, plan your content:

1. Identify Target Screens: Determine which verification screens need customization
2. Define Content: Prepare titles, descriptions, instructions and button labels
3. Consider Localization: Plan for multiple languages if needed
4. Align with Branding: Make sure content aligns with corporate branding

Using Control Center Interface

To open Affirm Studio:

1. Log in to HYPR Control Center.
2. In the left navigation menu, click HYPR Affirm.
3. In the top navigation bar, click the Affirm Studio tab.

Affirm Studio provides the following features:

• Kit Management: Create, edit and delete workflow customization kits
• Step-Based Editing: Edit content for each verification flow step: Instructions, Consent, Login Identifier, Extended Information, Phone Number / Email Verification, Location, Verified Credential, Document and Biometric Verification, Photo ID and Liveness Capture, Final Await and Approver Attestation
• Content Editor: Edit Card Header, Card Footer, Button Labels, Error Messages, Success Messages, Field Related Content, Screen Specific Content and Text Assets, plus Style Customizations
• Screen Preview: Review how customized screens appear to end users

To create and edit a kit:

1. From the Welcome screen or the Kit Management screen, click + Create Your First Kit or + Create New Kit.
2. In the Create New Kit modal, enter a Kit Name and an optional Description.
3. Click Create Kit to create the kit.

4. From the Kit Management screen, click Open Kit on the kit you want to edit.

5. In the Kit Editing screen, select a step from the verification flow in the left panel.
6. Use the Content Editor in the right panel to configure content for each screen type.
7. Use the Preview feature in the center panel to review changes as you make them. The Desktop and Mobile toggle and the Wizard and User mode toggle show how the screen looks to end users.
8. Click Save Changes to save all pending changes together, or Discard to drop them. As you edit, Affirm Studio tracks unsaved changes at the kit level and shows a banner when updates are pending.

Content Validation

Affirm Studio validates content input and blocks saving text that exceeds a field's maximum length. The pending-changes banner shows the number of validation errors and flags changes that contain unsupported HTML; hover over it to see them. HTML tags other than line breaks, bold and italic are shown as plain text on the screen.

Using the API

For programmatic configuration, use the REST API endpoints. See Affirm Content Customization API for the complete API documentation.

Create the Content Customization

Use the API to create your first content customization:

POST /cc/api/idv/content-customization
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "displayName": "Company Branding",
  "description": "Standard company content for all verification screens",
  "contentMap": {
    "loginIdentifierScreen": {
      "cardHeader": {
        "title": "Welcome to [Company Name] Verification",
        "description": "Enter your work email address to get started."
      },
      "cardFooter": {
        "caption1": "Secure verification process",
        "caption2": "Powered by HYPR"
      },
      "buttonLabels": {
        "continueButton": "Begin"
      }
    }
  }
}

Test the Configuration

After you create content customizations, test them in your development environment:

1. Retrieve Configuration: Use the GET endpoint to verify your setup
2. Test Workflows: Run sample verification workflows to see the customizations
3. Validate Content: Make sure all text displays correctly and buttons work
4. Check Localization: If you use multiple languages, test each variant

Screen Configuration

Each customizable screen supports the configuration elements in the following table. Which elements a screen offers depends on the screen.

Element	Field	Content
Header content	Title	Main screen title
Header content	Description	Screen description
Footer content	Caption 1	Primary footer text
Footer content	Caption 2	Secondary footer text
Button labels	Button text	The button text for the screen
Messages and field content	Error Messages and Success Messages	Messages shown on the screen
Messages and field content	Field Related Content	Field placeholder text
Messages and field content	Screen Specific Content	Other text specific to the screen
Messages and field content	Text Assets	Named blocks of formatted text, such as custom consent language, when the customizable consent screen is enabled for your tenant

Applying to Workflows

After you set up a customization, apply it to a workflow in Control Center or with the API.

Using Control Center Interface

1. In the left navigation menu, click HYPR Affirm.
2. Click the Verification Flows tab.
3. Click the workflow you want to customize.
4. In the workflow editor's left sidebar, under Advanced Customization, select Content.

5. From the Content Customization Kit drop-down menu, choose the kit you want to apply.
6. Click Save to apply the kit to the workflow.

Using the API

1. Retrieve Workflow Configuration: Get the current workflow settings
2. Update Configuration: Add the contentCustomizationId to the workflow
3. Save Changes: Apply the updated configuration
4. Test Workflow: Verify the customizations appear correctly

API Configuration Examples

The following examples show request bodies for the create endpoint. For every screen key and field, see Affirm Content Customization API.

Basic Company Branding

The request body in Create the Content Customization is a basic company-branding example: a title, description, footer captions and button label for the login identifier screen.

Localized Content (Spanish)

{
  "displayName": "Spanish Localization",
  "description": "Spanish language content for global teams",
  "contentMap": {
    "loginIdentifierScreen": {
      "cardHeader": {
        "title": "Bienvenido a la Verificación de [Company Name]",
        "description": "Ingrese su correo electrónico de trabajo para comenzar."
      },
      "cardFooter": {
        "caption1": "Proceso de verificación seguro",
        "caption2": "Desarrollado por HYPR"
      },
      "buttonLabels": {
        "continueButton": "Comenzar"
      }
    }
  }
}

Multi-Screen Configuration

{
  "displayName": "Complete Workflow Branding",
  "description": "Content for several verification screens",
  "contentMap": {
    "instructionsScreen": {
      "cardHeader": {
        "title": "Verification Instructions",
        "description": "Follow these steps to complete verification"
      },
      "cardFooter": {
        "caption1": "Have a valid government-issued ID ready",
        "caption2": "Powered by HYPR"
      },
      "buttonLabels": {
        "continueButton": "Continue"
      }
    },
    "consentScreen": {
      "buttonLabels": {
        "continueButton": "I Accept"
      }
    },
    "loginIdentifierScreen": {
      "cardHeader": {
        "title": "Welcome to Company Verification",
        "description": "Enter your work email address to get started."
      },
      "buttonLabels": {
        "continueButton": "Begin"
      }
    }
  }
}

Getting Help

To troubleshoot a customization, use the following resources:

• Check API Documentation: Review the Affirm Content Customization API
• Review Logs: Check system logs for error details
• Test in Development: Verify configurations in a test environment
• Contact Support: Contact HYPR Support for assistance

Related Documentation

• Affirm Studio
• Affirm Content Customization API
• Affirm Installation and Configuration
• Control Center Branding Customization