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

application/vnd.authologic.v1.1+json
userKeystring optional

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.

returnUrlstring optional

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

callbackUrlstring optional

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

layoutUrlstring optional

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

strategystring optional

Additional information on the user identity verification strategy

queryobject optional

Query definition - List of information to be obtained

identityobject optional

Configures the required user information to be provided

verifyobject optional

Configures which user information should be compared and verified

bankTransactionsobject optional

Configures the required information about the user's banking transactions.

amlobject optional

Configures the required information about the AML checks.

authobject optional

Configures the required information about auth product.

enquiryobject optional

Configures the required information about enquiry product.

affordabilityobject optional

Configures the required information about affordability product.

ageVerificationobject optional

BETA Configures the required information about age verification product.

settingsobject optional

Additional, optional settings depend on the selected strategy.

[additional properties]string

Responses

200

Conversation started

application/vnd.authologic.v1.1+json
idstring required

Unique identifier for the conversation

userKeystring required

Unique user identifier in the Customer's system

urlstring required

The address where user should be redirected to perform the verification

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
CREATEDIN_PROGRESSFINISHEDCANCELEDEXPIRED
resultobject required

The result of checking individual elements

identityobject optional

Identity check result

verifyobject optional

Verify step result

bankTransactionsobject optional

The result of retrieving transaction data

amlobject optional

The result of AML checks

authobject optional

The result of authorization

enquiryobject optional

The result of enquiry form

affordabilityobject optional

The result of affordability assessment product

ageVerificationobject optional

BETA The result of age verification

infoarray<object> optional

The information about activated strategy elements

Array of object

The information about activated strategy elements

countrystring optional

Country used.

methodstring optional

Verification method used.

  • PSD2,
  • TRANSFER,
  • MOBYWATEL,
  • MOJEID_PL,
  • EDO_APP
  • and many more
traceobject optional

Additional information returned by the provider.

methodDetailsobject optional

Additional information about verification method.

400

Bad Request

application/vnd.authologic.v1.1+json
One of:
Variant 1
statusstring required

Response status

messagestring required

Descriptive error message

violationsarray<object> required

Validation error list

Array of object

Validation error list

fieldstring required

Field name

messagestring required

Descriptive error message

statusDetailstring optional

Response status detailed information

Variant 2
statusstring required

Response status

messagestring required

Descriptive error message

violationsarray<object> required

Validation error list

Array of object

Validation error list

fieldstring required

Field name

messagestring required

Descriptive error message

statusDetailstring optional

Response status detailed information

Variant 3
statusstring required

Response status

messagestring required

Descriptive error message

violationsarray<object> required

Validation error list

Array of object

Validation error list

fieldstring required

Field name

messagestring required

Descriptive error message

statusDetailstring optional

Response status detailed information

Variant 4
statusstring required

Response status

messagestring required

Descriptive error message

violationsarray<object> required

Validation error list

Array of object

Validation error list

fieldstring required

Field name

messagestring required

Descriptive error message

statusDetailstring optional

Response status detailed information

Variant 5
statusstring required

Response status

messagestring required

Descriptive error message

violationsarray<object> required

Validation error list

Array of object

Validation error list

fieldstring required

Field name

messagestring required

Descriptive error message

statusDetailstring optional

Response status detailed information

Variant 6
statusstring required

Response status

messagestring required

Descriptive error message

violationsarray<object> required

Validation error list

Array of object

Validation error list

fieldstring required

Field name

messagestring required

Descriptive error message

statusDetailstring optional

Response status detailed information

Variant 7
statusstring required

Response status

messagestring required

Descriptive error message

violationsarray<object> required

Validation error list

Array of object

Validation error list

fieldstring required

Field name

messagestring required

Descriptive error message

statusDetailstring optional

Response status detailed information

402

Exhaustion of the plan or limitations related to non-payment

403

Forbidden

application/vnd.authologic.v1.1+json
statusstring required

Response status

messagestring required

Descriptive error message

violationsarray<object> required

Validation error list

Array of object

Validation error list

fieldstring required

Field name

messagestring required

Descriptive error message

statusDetailstring optional

Response status detailed information

500

Server side error

Powered by Authologic Nisaba