Affirm Content Customization API

The Affirm Content Customization API (introduced in HYPR 10.3.0) provides endpoints for managing the content customization kits used by Affirm Studio. A kit holds the text of each end-user screen; assign it to a verification flow to apply it.

Control Center or API

In HYPR 10.7.0 and later you can also build and manage kits in Control Center with Affirm Studio. See Configuring End User Screen Customizations.

General Branding

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

Base URL

/cc/api/idv/content-customization

Authentication

Every endpoint requires authentication. Include your API credentials in the request headers.

Endpoints

The following table lists the endpoints. Paths are relative to the base URL.

Method	Path	Purpose
POST	/	Create a content customization. Returns 201 Created
PATCH	/{id}	Update a content customization
PATCH	/{id}/metadata	Update the display name and description
GET	/	List all content customizations
GET	/{id}	Retrieve one content customization
GET	/defaults	Retrieve the default HYPR content for every screen
GET	/{id}/screens	List the names of the screens that have content in a customization
GET	/{id}/screens/{screenName}	Retrieve the content of one screen
PUT	/{id}/screens/{screenName}	Replace the content of one screen
PUT	/{id}/duplicate	Copy a customization. Returns 201 Created
DELETE	/{id}	Delete a content customization

Create Content Customization

Creates a new content customization.

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

Request Body:

{
  "displayName": "Content Customization 2",
  "description": "Company-specific content for 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": ""
      },
      "buttonLabels": {
        "continueButton": "Continue"
      }
    },
    "loginIdentifierScreen": {
      "cardHeader": {
        "title": "Welcome to Company Verification",
        "description": "Enter your work email address to get started."
      },
      "buttonLabels": {
        "continueButton": "Begin"
      }
    }
  }
}

Response:

The response returns the created customization, including its id, displayName, description, contentMap and stylePaletteMap.

{
  "id": "123",
  "displayName": "Content Customization 2",
  "description": "Company-specific content for verification screens",
  "contentMap": {
    "instructionsScreen": {
      "cardHeader": {
        "title": "Verification Instructions",
        "description": "Follow these steps to complete verification"
      },
      "cardFooter": {
        "caption1": "Have a valid government-issued ID ready"
      },
      "buttonLabels": {
        "continueButton": "Continue"
      }
    },
    "loginIdentifierScreen": {
      "cardHeader": {
        "title": "Welcome to Company Verification",
        "description": "Enter your work email address to get started."
      },
      "buttonLabels": {
        "continueButton": "Begin"
      }
    }
  },
  "stylePaletteMap": {}
}

Update Content Customization

Updates an existing content customization.

PATCH /cc/api/idv/content-customization/{id}
Content-Type: application/json

Request Body:

{
  "displayName": "Content Customization 2.2",
  "contentMap": {
    "instructionsScreen": {
      "cardHeader": {
        "title": "Updated Instructions"
      }
    }
  }
}

The response returns the updated customization.

List All Content Customizations

Retrieves all content customizations, newest first.

GET /cc/api/idv/content-customization

Response:

The response is an array. Each entry carries the customization's id, displayName, description and stylePaletteMap.

[
  {
    "id": "124",
    "displayName": "Spanish Localization",
    "description": "Spanish language content for global teams",
    "stylePaletteMap": {}
  },
  {
    "id": "123",
    "displayName": "Content Customization 2.2",
    "description": "Company-specific content for verification screens",
    "stylePaletteMap": {}
  }
]

Retrieve Specific Content Customization

Retrieves a specific content customization by ID.

GET /cc/api/idv/content-customization/{id}

The response has the same shape as the create response.

Data Models

ContentCustomization

The following table describes the fields of a content customization.

Field	Type	Description
id	String	Unique identifier for the content customization
displayName	String	Display name for the customization
description	String	Description of the customization purpose
contentMap	AffirmContentMap	Screen-specific content configuration
stylePaletteMap	StylePaletteMap	Style settings for the customization

AffirmContentMap

The content map holds one entry per customizable screen. The following table lists the screen keys.

Screen	Type	Description
instructionsScreen	BaseContentCustomizationMap	Instructions screen that lists the checks in the flow
consentScreen	BaseContentCustomizationMap	Consent screen
loginIdentifierScreen	BaseContentCustomizationMap	Username or email entry
phoneNumberOrEmailScreen	BaseContentCustomizationMap	Phone number or email selection
otpScreen	BaseContentCustomizationMap	One-time code entry
locationScreen	BaseContentCustomizationMap	Location check
verifiedCredentialScreen	BaseContentCustomizationMap	Verified credential presentation
idv1Screen	BaseContentCustomizationMap	Document and biometric verification
extendedInfoScreen	BaseContentCustomizationMap	Additional information (date of birth and address)
idv1AwaitScreen	BaseContentCustomizationMap	Waiting for the document and biometric result
idv1ReportScreen	BaseContentCustomizationMap	Identity verification results shown to the requester
documentUploadVideoScreen	BaseContentCustomizationMap	Photo ID and liveness capture
awaitScreen	BaseContentCustomizationMap	Waiting for the final decision, and the result
approverPreVerifyScreen	BaseContentCustomizationMap	Approver screen before verification
approverAttestScreen	BaseContentCustomizationMap	Approver attestation
approverAttestationResultsScreen	BaseContentCustomizationMap	Approver attestation results

BaseContentCustomizationMap

Each screen entry can contain the following groups. Which keys a group accepts depends on the screen; retrieve /defaults to see every key with its default text.

Field	Description
cardHeader	title and description of the screen
cardFooter	caption1 and caption2 footer text
buttonLabels	Button text, for example continueButton
errorMessages	Error messages shown on the screen
successMessages	Success messages shown on the screen
fieldRelatedContent	Field placeholder text
screenSpecificContent	Other text specific to the screen
textAssets	References to text assets by ID, such as custom consent language

Code Customizations

This API manages screen content only. For scripts that change Affirm's behavior, and the ctx helper functions they can use, see Writing Affirm Code Customizations.

Error Handling

The API returns the standard HTTP status codes in the following table.

Status	Meaning
200 OK	Request successful
201 Created	Resource created successfully
400 Bad Request	Invalid request data
401 Unauthorized	Authentication required
403 Forbidden	Insufficient permissions
404 Not Found	Resource not found
500 Internal Server Error	Server error

Related

• Affirm Studio (user experience) — what users see with Affirm Studio kits applied
• Configuring End User Screen Customizations — admin walkthrough for building and assigning kits
• Custom Branding — logo, background image or solid background color, and Company Identity
• Advanced Setup — integration prerequisites and IdP attribute requirements