MobileID

The following page contains step by step description of integration with asynchronous MobileID strategy via the headless API.

Creating Conversation

We use the same conversation creation endpoint as usually. All you need to be aware of is providing countryCode attribute in settings section. This attribute MUST contain one of the two alpha2 country codes EE or LT. Setting this value allows precise method selection in verification process right in its beginning.

{
  "userKey": "7dfb9ded-c38f-49ae-95e2-307283a0b1f6",
  "returnUrl": "https://sandbox.authologic.com/tests/return/?conversation={conversationId}",
  "strategy": "public:mobileid-async",
  "query": {
    "identity": {
      "requireOneOf": [["PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]]
    }
  },
  "settings": {
    "countryCode": "EE"
  }
}

In the response you will receive common values:

{
  "id": "9711e1db-7eea-4a19-a05d-4729512e3626",
  "userKey": "7dfb9ded-c38f-49ae-95e2-307283a0b1f6",
  "url": "https://id.sandbox.authologic.com/c/9711e1db-7eea-4a19-a05d-4729512e3626",
  "status": "CREATED",
  "result": {
    "identity": {
      "status": "IN_PROGRESS",
      "user": {}
    }
  }
}

Process Initiation

Now you need to initialize interaction with verification process. All you need to do is just call /api/conversations/{conversationId}/headless endpoint.

Example below:

curl -u my_login "https://sandbox.authologic.com/api/conversations/9711e1db-7eea-4a19-a05d-4729512e3626/headless" \
-H "Accept: application/vnd.authologic.v1.1+json" \
-H 'X-User-IP: XXX.X.X.X' \
-H "Content-Type: application/vnd.authologic.v1.1+json"

What you can expect is response like this:

{
  "component": "MOBILEID_EE/SHOW_CODE",
  "next": "712eacdc-e859-4ce4-8e91-272daad7dbe8",
  "args": {
    "securityCode": "2436"
  }
}

This means that verification method is MOBIEID_EE and current action that you need to perform in your UI is SHOW_CODE. Value taken from securityCode attribute (in this example it is 2436) must be displayed to the user. 2436 is the security code that will be displayed on user's mobile device to confirm verification and share identity. User must confirm that codes displayed in verification process and on mobile device match.

Collecting National Identifier And Phone Number

The verification process requires collecting two values from the user national identifier and phone number related to user's identity wallet. Both values are mandatory and must be validated against the format: national identifier - 11 digits contact phone number - starts with country code (+372 or +370) and followed by minimum 5 up to 27 digits

Please make sure that values are valid.

Once the code is displayed and the value is obtained, you can move on.

Triggering Process and Move Process Forward

Now it is time to send obtained values to Authologic. All you need to do is just call /api/conversations/{conversationId}/headless/{next} endpoint.

Example below:

curl -X POST -u my_login "https://sandbox.authologic.com/api/conversations/9711e1db-7eea-4a19-a05d-4729512e3626/headless/712eacdc-e859-4ce4-8e91-272daad7dbe8" \
-H "Accept: application/vnd.authologic.v1.1+json" \
-H 'X-User-IP: XXX.X.X.X' \
-H "Content-Type: application/vnd.authologic.v1.1+json" \
-d "{
  "args": {
    "nationalIdentifier": "50001018908", "contactPhone" : "+37266000266"
  }
}"

What you can expect is response like this:

{
  "component": "GLOBAL/ACCEPTED"
}

This means provided values are correct. We are taking care of everything else. We are trying to start process with our provider. We are waiting for user to confirm verification. What you need to do is just wait for callback with conversation results from Authologic.

However, response may contain several errors:

{
  "component": "MOBILEID_EE/SHOW_CODE",
  "next": "712eacdc-e859-4ce4-8e91-272daad7dbe8",
  "args": {
    "securityCode": "2436"
  },
  "errors": [
    {
      "field": "contactPhone",
      "error": "EMPTY"
    },
    {
      "field": "nationalIdentifier",
      "error": "FORMAT_ERROR"
    }
  ]
}

This means that one of the values is missing or the format does not meet the requirements.

Moreover, sometimes in cases where national identifier and phone number meet the requirements but in some circumstances provider is unable to start verification process we must finish conversation with status FAILED. These are the errors which cannot be handled in the asynchronous mode via headless API e.g. user's mobile device is out of range of network.

In such cases the reason of error is sent in callback.

Here you can find description of possible error reasons.

Reasons that apply:

• NO_DATA_SHARED - e.g. user refused to share identity
• ABANDONED - e.g. timeout occurred while waiting on user's activity
• NO_IDENTITY_FOUND - e.g. provider was unable to match given national identifier or phone number to existing account
• INSUFFICIENT_PRIVILEGES - e.g. provider was unable to fetch the identity from existing user account
• USER_NOT_AUTHORIZED - e.g. user selected wrong security code on mobile device
• E_IDENTITY_ACCESS_ERROR - e.g. mobile device is out of range of network