SmartID

The following page contains step by step description of integration with asynchronous SmartID 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 three alpha2 country codes EE,LV 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:sid-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": "SMART_ID/SHOW_CODE",
  "next": "712eacdc-e859-4ce4-8e91-272daad7dbe8",
  "args": {
    "securityCode": "2436"
  }
}

This means that verification method is SMART_ID 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

The verification process requires collecting one value from the user national identifier related to user's identity wallet. Value is mandatory and must be validated against the format:

national identifier - 11 digits (format: XXXXXXXXXXX) or 11 digits separated with - after sixth digit (format: XXXXXX-XXXXX)

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 value 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"
  }
}"

What you can expect is response like this:

{
  "component": "GLOBAL/ACCEPTED"
}

This means provided value 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": "SMART_ID/SHOW_CODE",
  "next": "712eacdc-e859-4ce4-8e91-272daad7dbe8",
  "args": {
    "securityCode": "2436"
  },
  "errors": [
    {
      "field": "nationalIdentifier",
      "error": "FORMAT_ERROR"
    }
  ]
}

This means that format of the value does not meet the requirements. In case you missed to send national identifier or there is a typo in name you should get EMPTY error code.

Moreover, sometimes in cases where national identifier meets 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_USER_FOUND - e.g. provider was unable to match given national identifier 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