Skip to content

General Migration Considerations

As part of the latest version of the API, several structural and functional changes have been introduced to improve modularity, clarity, and maintainability of integrations. Below are the key migration considerations for developers and integration teams.

1. New optional Content-Type Support

The API continues to support the application/json content type, and support for multipart/form-data has now been added.

The API supports requests with the following headers:

Content-Type: application/json
Content-Type: multipart/form-data

This new format enables sending multiple structured files in a single request. The integration currently supports three optional files:

  • texts: A JSON file containing references to all textual content used in the integration (e.g., labels, messages, titles).
  • medias: A JSON file defining references to media resources such as images.
  • styles: A JSON file that centralizes user interface customization options such as colors and visual themes.

Each file must be provided under its respective key in the multipart/form-data payload.

If multipart/form-data is configured but no file is sent, the API will return an error. Likewise, attempting to send a file using application/json will also result in an error.

These keys can only be configured through a single channel, meaning that if you configure the texts, you must do it either in the JSON or in the texts file — the same applies to styles and media.

Sending a file using Content-Type

Below is an example, written in Python, of how to send a texts.json file when requesting the token for a document & country selector flow:

payload={
  'data': '
    {
        "platform": "ios",
        "language": "en",
        "operationMode": "idv",
        "flowSetup": {
            "core": {"confirmProcess": true},
            "stages": ["document"]
        }
    }
'}
}

files=[
  ('texts',('texts.json',open('/your_route_to/texts.json','rb'),'application/json')),
]

headers = {
  'Content-Type': 'multipart/form-data'
  'apikey': 'API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)
See details here

IMPORTANT NOTE

  • If you want to adapt the texts of any screen to your language or region, click here
  • If you want to customize the UI styles, including themes or component-level appearance to match your brand, click here.
  • If you want to customize the image resources, such as logos, instruction images, click here.

2. iFrame Integration

The integration remains the same; however, the XpressID_URL has changed with the addition of /v3/. Please refer to this table to determine which URL to use.

https://XpressID_URL?access_token=YOUR_ACCESS_TOKEN

Important: The access_token must be obtained beforehand by making a request to the authentication API. Ensure secure handling of the token, and be aware of its expiration and usage scope.

This URL should be used as the src attribute of an <iframe> element to properly embed the integration in your application.

Example:

<iframe
  src="XpressID_URL?access_token=YOUR_ACCESS_TOKEN"
  width="100%"
  height="100%"
  style="border: none;"
  allow="camera; microphone; geolocation; gyroscope; accelerometer;"
></iframe>

Replace YOUR_ACCESS_TOKEN with the valid token retrieved via API.

When integrating XpressID Web within an iframe, it is essential to ensure proper rendering on mobile devices. Without the appropriate viewport configuration, browsers may scale the content incorrectly, causing text and interface elements to appear too small. To prevent this, add the following tag inside the section of your HTML document:

<meta name="viewport" content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content"/>

3. Reorganized JSON Configuration Structure

The configuration structure has been modularized into three distinct sections, each managed either through a separate file or as a root-level key within the JSON structure.

  • Texts (texts)
    • All text-related content must be placed in the dedicated texts file, or under the root-level texts key in the JSON.
    • This includes interface messages, titles, instructions, etc.
  • Medias (medias)
    • All references to images and media resources (e.g., logos, images) must now be placed in the medias file, or under the root-level medias key in the JSON.
    • This can include URLs or identifiers pointing to pre-uploaded assets.
  • Styles (styles)
    • All UI customization parameters (e.g., color palette, typography, component styles) must be declared within the styles file, or under the root-level styles key in the JSON.
    • This ensures a clean separation between content and presentation.

4. Migration Summary and Best Practices

To migrate successfully:

  • Update your integration to use multipart/form-data with the appropriate attachments (texts, medias, and styles), or alternatively, use application/json by updating the root-level keys texts, medias, and styles within the JSON. Choose the method that best suits your needs.
  • Structure your JSON configurations according to the new modular model.
  • Request and manage the access_token securely via the authentication API.
  • Embed the integration using the new iframe URL format.

This new structure enables a more flexible and scalable approach to configuration, especially for clients requiring dynamic, localized, or branded experiences.