Skip to main content
Start for free
POST/api/conversations

Start a new user verification process

Each process of getting data and confirming the identity of the user should start by calling this method. The call initiates this process and returns information about the address to which the user should be redirected to gathering the information requested from him.

In order to use the API you need to obtain the login and password for a for a specific environment. You can generate a new API key in the API Keys section of the OmniPanel. The API is accessible via either HTTP Basic authentication or OAuth2 client credentials flow. Both methods accept the same API key.
When using OAuth2, the API key can be sent either via Authentication Bearer header or via HTTP POST body.
This is because all of these fields may have their default values set on the Authologic side when creating your account. If any value does not have a default setting you will get an error and you should either provide that value or report to Authologic to set the default one.

The query contains three groups of information:

  • general information such as:
    • userKey: User ID on your system
    • strategy: information about the identity checking strategy (usually the default value is sufficient)
    • returnUrl: URL to which the user should be redirected after the process is completed
    • callbackUrl: information about the return address to which the system will send the acquired information. If this information is not provided, Authologic assumes that the information will be downloaded by the client
  • query: query definition containing individual products provided by Authologic
The test environment allows the use of an HTTP address for callbackUrl. A production environment always requires HTTPS.
For testing purposes, to check the callback request, you can use online tools that accept and present the outgoing requests. One such tool is, for example, Webhook(opens in new tab). When creating a conversation, it is enough to provide the url generated by Webhook in the callbackUrl parameter.

The information contained in the query section is divided into specific products:

  • identity - fetch user information. This section is always required
    • requireOneOf: User information to be specified by Authologic. This is represented as set of sets and Authologic will try to fetch one of these
    • optional: User information that may be specified by Authologic when the information is available
  • aml - check user on AML lists
    • checks: lists where the user should be checked
  • auth - user authentication product
  • bankTransactions - the process of retrieving information about transactions.
    • type: type of transaction - credit, debit or all
    • flags: Additional information on what to return
  • verify - confirmation of the compliance of user data
    • user: information about user that should be verified

Request Body

Content-Typeapplication/vnd.authologic.v1.1+jsonJSON
userKeystring1–200 charspattern^[a-zA-Z0-9-_+=#@.:]+$

User ID on your system. This property is not used by the Authologic and is returned with the conversation status. If not given will be generated automatically.

Example:7dfb9ded-c38f-49ae-95e2-307283a0b1f6
returnUrlstring

The address on your system where the user will be redirected after verifying his identity. If {conversationId} part was given, it will be replaced with the conversation ID

Example:https://authologic.com/tests/return/?conversation={conversationId}
callbackUrlstring

The address in your system to which information about the user will be sent. You can use placeholders: {conversationId}, {target} and {event}

Example:https://authologic.com/tests/callback/?conversation={conversationId}&target={target}&event={event}
layoutUrlstring

The address on your system where the user will be redirected when Authologic need contact with user. This allows to define process look on your side. If {conversationId} part was given, it will be replaced with the conversation ID

Example:https://authologic.com/tests/layout/?conversation={conversationId}
strategystringpattern^[a-zA-Z]+:[a-zA-Z0-9-_+:]+$

Additional information on the user identity verification strategy

Example:public:default
queryProductQuery

Query definition - List of information to be obtained

settingsobject

Additional, optional settings depend on the selected strategy.

Example:{"countryCode":"PL"}
[additional properties]string

Responses

Conversation started

Content-Typeapplication/vnd.authologic.v1.1+jsonJSON
idstring required

Unique identifier for the conversation

Example:e0c0b3cc-8238-414f-9940-9f14bd1b8693
userKeystring required

Unique user identifier in the Customer's system

Example:d5dbb8e0-192e-4bc6-972c-f7948409d10c
urlstring required

The address where user should be redirected to perform the verification

Example:https://sandbox.authologic.com/c/022e8eaf-b06d-44b9-a68f-45eef1353dbe
statusstring required

Conversation state

  • CREATED - conversation ready to be run
  • IN_PROGRESS - data is being determined from the query
  • FINISHED - query checks have been completed
  • CANCELED - checking interrupted by the user
  • EXPIRED - conversation is expired
Allowed values:CREATEDIN_PROGRESSFINISHEDCANCELEDEXPIRED
resultConversationInfoResult required

The result of checking individual elements

infoarray<ConversationStrategyInfo>

The information about activated strategy elements

Powered by Authologic Nisaba