5 Minutes Tutorial

The Conversation

For the sake of simplicity, we’ll refer to the process of interacting with the API as a conversation.

Whenever you want to:

• verify a user’s identity,
• check AML lists, or
• initiate a verification process,

you start a new conversation.

Creating a Conversation

In this 5-minute tutorial, we’ll simulate a user identity verification process. We use a simulation to keep things simple and to focus on the core interactions needed to get you started.

We will use the curl tool to start a new conversation - one that will return the user first and last name. Keep in mind that the following example requires you to replace the my_login with the credentials that you can find in the OmniPanel and my_callback_url_here with an address that our system will return the data to.

For my_callback_url_here you could use https://webhook.site/(opens in new tab) to generate callback url which will be responsible for receiving user information from Authologic. Whether you will use webhook.site or other similar tool it is crucial that it will correctly receive http request since it is required for the process of identification.

curl -X POST -u my_login "https://sandbox.authologic.com/api/conversations" \
-H "Accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json" \
-d '{
    "userKey": "7dfb9ded-c38f-49ae-95e2-307283a0b1f6",
    "returnUrl": "https://id.sandbox.authologic.com/c/{conversationId}/thankYou",
    "callbackUrl": "my_callback_url_here",
    "strategy": "public:sandbox",
        "query": {
            "identity": {
                "requireOneOf": [
                    [ "PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]
                ]
            }
        }
    }'

Of course, instead of my_login enter your login. You should be prompted for a password - at that point you should enter the API key (do not confuse it with the password to the customer panel).

The response of the above command should look something like this:

{
  "id": "c12c1adc-3ff0-4d32-b95c-c593135c903e",
  "userKey": "7dfb9ded-c38f-49ae-95e2-307283a0b1f6",
  "url": "https://sandbox.authologic.com/c/c12c1adc-3ff0-4d32-b95c-c593135c903e",
  "status": "CREATED",
  "result": {
    "identity": {
      "status": "IN_PROGRESS",
      "user": {}
    }
  }
}

In the above response we got the following information:

• id - the conversation id. We will need it when inquiring about its status.
• userKey - ID of the user to be checked, exactly what you entered when creating the conversation.
• url - the address to which the user should be redirected in order to verify the identity.
• status - conversation status. CREATED marks a new conversation where the user has not yet started the verification process.
• result - conversation result. At the moment we do not have any data, so there appears, within the product for which we asked the status: IN_PROGRESS and an empty structure with data about the user (user)

Identity Check

To start the identity check, direct the user (or yourself during testing) to the url provided in the response in the url field. In the sandbox environment, you’ll see a form where you can enter the details to simulate the identity verification process. Once completed, the user will be redirected to the returnUrl you specified earlier - in the conversation creation request.

Getting the Conversation Results

Now let's check the conversation status. You should get request on url that was provided in callbackUrl field during creating conversation, which should look similar to the following JSON:

{
  "id": "f109ad2b-5e3c-4f9d-b2ea-20379e56f101",
  "created": "2020-12-24T16:00:00.930853456Z",
  "target": "CONVERSATION",
  "event": "FINISHED",
  "payload": {
    "conversation": {
      "id": "c12c1adc-3ff0-4d32-b95c-c593135c903e",
      "userKey": "7dfb9ded-c38f-49ae-95e2-307283a0b1f6",
      "url": "https://sandbox.authologic.com/c/c12c1adc-3ff0-4d32-b95c-c593135c903e",
      "status": "FINISHED",
      "result": {
        "identity": {
          "status": "FINISHED",
          "errors": [],
          "user": {
            "person": {
              "name": {
                "firstName": "Jan",
                "lastName": "Testowy"
              }
            }
          }
        }
      }
    }
  }
}

Conversation Identifier vs Callback Identifier

Please note, that in the above response the top level identifier is the callback identifier, not the conversation identifier. In order to retrieve metadata about the conversation using Authologic APIs, you should use the conversation identifier, which is the id field value that is located in the payload.conversation object.

Now, head to the part of the documentation that describes the product that you would like to use to get a more in-depth information about the integration.