The purpose of the document is to provide information about the advanced modification of the appearance of the user verification process. We assume knowledge of the information contained in the documents Overview and Integration in 5 minutes: Basic information. Also check: Customizing the user interface, maybe the information from this chapter will be sufficient for your integration.

By default, Authologic displays all pages that the user visits. These pages can be adapted to your visual identity, but sometimes it is necessary to prepare a more complex user interface.

Therefore, Authologic provides advanced customization options, where the entire appearance is generated on your side. Importantly, this way of integration is an extension of the standard integration, so the decision on additional customization can be made at any time.

Scheme of operation

In the basic integration, after creating a conversation, the user is redirected to the address on the Authologic side, where information is presented and the necessary data is collected from the user.

In the advanced integration, the user is not redirected to the Authologic pages. Instead, through the API, information is retrieved about which page and how should be displayed and what data from the user should be collected.

Thus, you yourself render the necessary page based on the provided data. Then the data collected from the user is transferred again via API and information about the next step (page) will be returned again. The transmission of data and the return of information about the following pages takes place until the identification is made or it is necessary to redirect the user to an external website, e.g. a bank.

The Customization API consists of the two methods described below.

Current Page

In order to get the current page, please execute the query GET/api/conversations/{conversationId}/page/current. It is also necessary to set the header X-User-IP with the IP address of the user to whom the page will be shown. Of course, the Accept,` Content-Type` and Authorization headers should also be set in the same way as for other API methods.

In response, Authologic returns information about the following format:

Format of the response for advanced UI
{
    "render":{
      "page": "pageName",
      "redirect": "https://page.to.redirect/",
      "header": {
        "main": {
          "title": "Page title",
          "subtitle": "Page subtitle",
          "howItWorks": "Description of how the process works on a given page"
        },
        "group": {
          "title": "Subpage title",
          "subtitle": "Subpage subtitle",
          "howItWorks": "Description of how the process works on a given subpage"
        }
      },
      "args": {
        "list": ["value"],
        "obj": {
          "field": "value"
        }
      },
      "errors": {
        "fields": {
          "fieldName": "error description"
        },
        "accepted": {
          "fieldName": "correct value"
        },
        "rejected":{
          "fieldName": "denied value"
        },
        "globals": [
          "error description"
        ]
      },
      "reloadCurrent": false
    },
    "next": {
      "call": "nextPageID",
      "args": [
        "parameterName"
      ],
      "options": {
        "_optionName": ["value1", "value2"]
      },
      "async": 5
    }
}

Below is a description of each parameter:

Parameter Required Example Description

render.page

baList

Name of the page that should be shown. If it is not present, it means that the user should be redirected to the page specified in render.redirect.

render.redirect

https address

The address of the page to which the user should be redirected in order to continue the process. In this case, subsequent pages, if needed, will be generated by Authologic. If render.page is not present, redirection is mandatory.

render.header.main

-

A section that defines page descriptions, i.e. the title, subtitle and description of how the process works on the page

render.header.main.title

title

Page title

render.header.main.subtitle

subtitle

Page subtitle

render.header.main.howItWorks

action description

Description of how the process works on a given page

render.header.group

-

Section defining subpage descriptions. A subpage can be defined, for example, when we have grouped data to present, where an additional sub-selection is possible for the selected element. An example of a section defining a subpage can be seen in the description of strategy public:bn

render.header.group.title

title

Subpage title

render.header.group.subtitle

subtitle

Subpage subtitle

render.header.group.howItWorks

action description

Description of how the process works on a given subpage

render.args

any json

Parameters necessary to display a given page, depending on a specific page. For example, for a page with a list of banks to choose from by the user, it will be a structure containing, among other things, information about available banks.

render.errors.fields

map with field name and error description

A map specifying incorrectly entered form fields and a description of the associated error.

render.errors.accepted

map containing the name of the field and its correctly given value

A map that specifies correctly entered form fields and the value of this field. For example, for a page with validation errors, but the values are also correct.

render.errors.rejected

map containing the field name and its incorrect value

A map specifying incorrectly entered form fields and the value of this field.

render.errors.globals

list of error descriptions

A list containing errors not related to specific form fields.

render.reloadCurrent

true

Parameter informing that information about the next page should be obtained by calling the method GET /api/conversations/{conversationId}/page/current. It is used when the page is updated asynchronously (see async below).

next.call

fd78cf43-12a7…​

Name of the page to which the user information should be submitted. Information is sent via the method POST /api/conversations/{conversationId}/page/{pageId}.

next.args

parameter name list

List of parameters that should be collected from the user and sent via the method POST /api/conversations/{conversationId}/page/{pageId}.

next.options

parameter name list

Optional parameters that can be sent via the POST /api/conversations/{conversationId}/page/{pageId} method instead of the required parameters defined in the next.args list. A detailed description and application of the optional parameters can be found in the description of the definition of specific pages.

next.async

numerical value

The occurrence of this parameter informs that the current page should remain displayed for the user, and at the same time the method POST /api/conversations/{conversationId}/page/{pageId} should be called periodically with the page identifier contained in next.call. This option is used in all kinds of expectations for the end of the process. The numeric value of the next.async parameter specifies the minimum time in seconds between each invocation of the method.

The field content may contain additional information about the format that needs to be modified before displaying, e.g. replacing with appropriate HTML tags. There are currently two types of this information:

  • links in the form of [Display Name] (URL).

  • bold text in the form: *text*

Example of text with formatting
{
  "disclaimer": "Link to the *Authologic* page is [here](https://www.authologic.com)"
}

Data retrieving

After collecting this data from the user (field next.args), it should be passed to the` POST/api/conversations/{conversationId}/page/{pageId}` method.

This method is responsible for collecting and analyzing this data. In the query it is also necessary to set the header X-User-IP with the IP address of the user to whom the page will be shown. Of course, the Accept,` Content-Type` and Authorization headers should also be set in the same way as for other API methods. The content of the query contains a map of parameter values, for example:

Example of data format when sending user data
{
  "consent": true,
  "phone": "+48123123123"
}

Multi-step verifications

If the process requires multiple redirection of the user to external websites (e.g. logging in to a bank), Authologic must know how to pass control to the place where subsequent pages will be rendered. For this purpose, when creating a conversation, the layoutUrl parameter should be specified. The user will be redirected there if there is a need to view further pages. If the address contains the string {conversationId}, it will be replaced with the current conversation ID.

Multiple Language

Support Authologic returns messages and texts to be displayed in the language specified with the standard HTTP header: Accept-Language.

Identifiers and names

When creating your integration, please take into account that any identifiers and content provided by Authologic are dynamically generated based on the data of specific identity providers. This means that they can change at any time, and you should not create any business logic from these values. An example of this is bank identifiers. Assigning an identifier to a specific bank may change over time.

Image file formats

In some cases, the identity verification pages present images. An example is the icons of banks. Authologic will then prefer SVG files, but this will not always be possible. By creating your integration, you should assume that the format of these files depends on specific vendors and may change in time.


Despite our sincere intentions, it is difficult to create perfect technical documentation. If you have an idea on how to improve this documentation, or you have trouble understanding any section, please email us at tech-support@authologic.com