Affirm Content Customization API

The Affirm Content Customization API (introduced in HYPR 10.3.0) provides endpoints for managing content customizations used by Affirm Studio.

API-Only Implementation

This feature currently has API-only support. No Control Center user interface is available yet.

General Branding

For general branding customization (logos, backgrounds, colors), see Custom Branding.

Base URL

/content-customization

Authentication

All API endpoints require proper authentication. Include your API credentials in the request headers.

Endpoints

Create Content Customization

Creates a new content customization configuration.

POST /content-customization
Content-Type: application/json

Request Body:

{
  "displayName": "Content Customization 2",
  "description": "Company-specific branding for verification screens",
  "contentMap": {
    "consentScreen": {
      "cardHeader": {
        "title": "Welcome to Company Verification",
        "description": "Please review and accept our terms"
      },
      "cardContent": {
        "mainContent": "By proceeding, you agree to our verification process",
        "extraContent": "This process helps us verify your identity securely"
      },
      "cardFooter": {
        "caption1": "Secure verification process",
        "caption2": "Powered by HYPR"
      },
      "buttonLabels": {
        "accept": "I Accept",
        "decline": "Decline"
      }
    },
    "instructionsScreen": {
      "cardHeader": {
        "title": "Verification Instructions",
        "description": "Follow these steps to complete verification"
      },
      "cardContent": {
        "mainContent": "Please follow the instructions carefully to complete your verification",
        "extraContent": "Ensure you have a valid government-issued ID ready"
      },
      "cardFooter": {
        "caption1": "Secure verification process",
        "caption2": "Powered by HYPR"
      },
      "buttonLabels": {
        "continue": "Continue",
        "back": "Back"
      }
    }
  }
}

Response:

{
  "id": 123,
  "displayName": "Content Customization 2",
  "description": "Company-specific branding for verification screens",
  "contentMap": {
    "consentScreen": {
      "cardHeader": {
        "title": "Welcome to Company Verification",
        "description": "Please review and accept our terms"
      },
      "cardContent": {
        "mainContent": "By proceeding, you agree to our verification process",
        "extraContent": "This process helps us verify your identity securely"
      },
      "cardFooter": {
        "caption1": "Secure verification process",
        "caption2": "Powered by HYPR"
      },
      "buttonLabels": {
        "accept": "I Accept",
        "decline": "Decline"
      }
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Update Content Customization

Updates an existing content customization configuration.

POST /content-customization/:content-customization-id
Content-Type: application/json

Request Body:

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

Response:

{
  "id": 123,
  "displayName": "Content Customization 2.2",
  "description": "Company-specific branding for verification screens",
  "contentMap": {
    "consentScreen": {
      "cardHeader": {
        "title": "Welcome to Company Verification",
        "description": "Please review and accept our terms"
      }
    },
    "instructionsScreen": {
      "cardHeader": {
        "title": "Updated Instructions"
      }
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:45:00Z"
}

List All Content Customizations

Retrieves all content customizations.

GET /content-customization

Response:

{
  "contentCustomizations": [
    {
      "id": 123,
      "displayName": "Content Customization 2.2",
      "description": "Company-specific branding for verification screens",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T11:45:00Z"
    },
    {
      "id": 124,
      "displayName": "Spanish Localization",
      "description": "Spanish language content for global teams",
      "createdAt": "2024-01-16T09:15:00Z",
      "updatedAt": "2024-01-16T09:15:00Z"
    }
  ],
  "total": 2
}

Retrieve Specific Content Customization

Retrieves a specific content customization by ID.

GET /content-customization/:content-customization-id

Response:

{
  "id": 123,
  "displayName": "Content Customization 2.2",
  "description": "Company-specific branding for verification screens",
  "contentMap": {
    "consentScreen": {
      "cardHeader": {
        "title": "Welcome to Company Verification",
        "description": "Please review and accept our terms"
      },
      "cardContent": {
        "mainContent": "By proceeding, you agree to our verification process",
        "extraContent": "This process helps us verify your identity securely"
      },
      "cardFooter": {
        "caption1": "Secure verification process",
        "caption2": "Powered by HYPR"
      },
      "buttonLabels": {
        "accept": "I Accept",
        "decline": "Decline"
      }
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:45:00Z"
}

Data Models

ContentCustomization

Field	Type	Description
id	Long	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
createdAt	DateTime	Creation timestamp
updatedAt	DateTime	Last update timestamp

AffirmContentMap

Contains configuration for all customizable screens:

Screen	Type	Description
consentScreen	BaseContentCustomizationMap	Initial consent screen
instructionsScreen	BaseContentCustomizationMap	Step-by-step guidance
loginIdentifierScreen	BaseContentCustomizationMap	Username/email input
phoneNumberOrEmailScreen	BaseContentCustomizationMap	Contact information collection
otpScreen	BaseContentCustomizationMap	One-time password verification
locationScreen	BaseContentCustomizationMap	Location-based verification
idvAwaitScreen	BaseContentCustomizationMap	Waiting for identity verification
idvRequestorReportScreen	BaseContentCustomizationMap	Verification status reporting
documentLivenessScreen	BaseContentCustomizationMap	Document and biometric verification
autoApprovalAwaitScreen	BaseContentCustomizationMap	Waiting for automatic approval
outcomeScreen	BaseContentCustomizationMap	Final verification results
deniedScreen	BaseContentCustomizationMap	Access denial notification

BaseContentCustomizationMap

Field	Type	Description
cardHeader	CardHeaderContentCustomizationMap	Header content configuration
cardContent	CardContentContentCustomizationMap	Main content configuration
cardFooter	CardFooterContentCustomizationMap	Footer content configuration
buttonLabels	Map<String, String>	Customizable button text

CardHeaderContentCustomizationMap

Field	Type	Description
title	String	Main screen title
description	String	Screen description text

CardContentContentCustomizationMap

Field	Type	Description
mainContent	String	Primary instructional text
extraContent	String	Additional information or tips

CardFooterContentCustomizationMap

Field	Type	Description
caption1	String	Primary footer text
caption2	String	Secondary footer text

Error Handling

The API returns standard HTTP status codes:

• 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

Rate Limiting

API requests are subject to rate limiting. See the response headers for current rate limit information:

• X-RateLimit-Limit - Maximum requests per time window
• X-RateLimit-Remaining - Remaining requests in current window
• X-RateLimit-Reset - Time when the rate limit resets

Related Documentation

• Affirm Studio
• Affirm Installation and Configuration