# Authologic API Documentation
Source: https://developer.authologic.com/docs/home
Title: Authologic API Documentation
Description: One API. One integration. Any ID verification method & process.
One API. One integration. Any ID verification method & process.
***We are aggregating ID verification methods like biometrics/document OCR, gov-issued digital IDs, and Bank IDs into one API.
We let you use those methods in ID verification processes we call "strategies". You integrate once, to get access to any method
in any process. How to start? See below!***
Welcome to the Authologic API documentation. These pages are designed to help you understand how our API works, what we offer,
and how you can integrate our ID verification services into your processes.
At Authologic, we believe in simplicity, modularity, and developer-friendliness. Our API is modular, so you don’t need to grasp
everything upfront. **You can start with a single product and easily add more later** - you will be able to combine multiple products
together using the same API, and don't worry, we'll guide you through the integration process.
> **Note:** If you are new to Authologic and you never worked with our solution follow the [5-minutes tutorial](https://developer.authologic.com/docs/products/5-minutes-tutorial)
> that will get you
> started in no time.
> **Note:** You should start with one of our products, for example the [identity](https://developer.authologic.com/docs/products/identity), but it all depends on your needs.
> Once that is done you can add more products and polish your integration.
> **Note:** We strongly recommend getting familiar with our products first, but if you would like to see how to combine
> multiple of them have a look at [combining products](https://developer.authologic.com/docs/integration/combining-products) section of the documentation.
But before you begin, let us introduce you to the products we offer, so that you know where to start.
- [Identity](https://developer.authologic.com/docs/products/identity): This product enables user identity check process using various methods such as biometric check, document OCR, government issues digital IDs, bank IDs and more.
- [AML](https://developer.authologic.com/docs/products/aml): This product enables verification of a user’s registration on AML lists via the API and provides details on the specific lists where the user’s data appears.
- [Bank Transactions](https://developer.authologic.com/docs/products/bank-transactions): This product enables the retrieval of a user's bank transactions and related statistics.
- [User Authentication](https://developer.authologic.com/docs/products/user-authentication): This product enables you to create a user login process (access authentication) for your system using Authologic.
- [Data Verification](https://developer.authologic.com/docs/products/data-verification): This product allows for the verification of provided data, resulting in a numerical score that indicates how closely the verified data matches the user’s identity.
- [Enquiry](https://developer.authologic.com/docs/products/enquiry): This product allows gathering of custom data from the user via dynamic forms.
# 5 Minutes Tutorial
Source: https://developer.authologic.com/docs/products/5-minutes-tutorial
Title: 5 Minutes Tutorial
> **Note:** This tutorial assumes you already have OmniPanel credentials and access to your API key for communicating with
> Authologic APIs. If you’re not at this stage yet, feel free to reach out to us for help.
> **Note:** We use the `curl` tool to show the API operation.
> If you have not dealt with it, you can find a short guide on it [here](https://www.baeldung.com/curl-rest).
> Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the
> link: [here](https://developer.authologic.com/api),
> or any other tool, such as Postman or Insomnia.
## 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 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*.
```shell
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).
> **Note:** The example given is for a test environment. If you perform these operations on the production environment
> that was provided to you then the `public:sandbox` strategy is not available. You can omit the `strategy` field to
> use the default strategy or use another one that we gave you the name of when determining your needs. As a result,
> nothing bad will happen, but remember that the production environment requires real data. The collected data will
> also be real.
The response of the above command should look something like this:
```json
{
"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:
```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.
> **Tip:** That's it. You managed to use API and get data.
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.
- [Identity](https://developer.authologic.com/docs/products/identity): This product enables user identity check process using various methods such as biometric check, document OCR, government issues digital IDs, bank IDs and more.
- [AML](https://developer.authologic.com/docs/products/aml): This product enables verification of a user’s registration on AML lists via the API and provides details on the specific lists where the user’s data appears.
- [Bank Transactions](https://developer.authologic.com/docs/products/bank-transactions): This product enables the retrieval of a user's bank transactions and related statistics.
- [User Authentication](https://developer.authologic.com/docs/products/user-authentication): This product enables you to create a user login process (access authentication) for your system using Authologic.
- [Data Verification](https://developer.authologic.com/docs/products/data-verification): This product allows for the verification of provided data, resulting in a numerical score that indicates how closely the verified data matches the user’s identity.
- [Enquiry](https://developer.authologic.com/docs/products/enquiry): This product allows gathering of custom data from the user via dynamic forms.
# Identity
Source: https://developer.authologic.com/docs/products/identity
Title: Identity
Description: Our identity verification product is a comprehensive solution designed to streamline Know Your Customer (KYC) processes, ensuring both security and convenience for businesses and their users. While using Authologic you can easily integrate with various providers and include advanced user identification processes such as biometrics, liveness checks, electronic identity (eID) verification, document OCR, bank identify and much more.
Our identity verification product is a comprehensive solution designed to streamline Know Your Customer (KYC) processes,
ensuring both security and convenience for businesses and their users. While using Authologic you can easily integrate with
various providers and include advanced user identification processes such as biometrics, liveness checks, electronic
identity (eID) verification, document OCR, bank identify and much more.
While using Authologic, businesses can quickly and accurately verify the identity of individuals, mitigating the risks of fraud,
identity theft, and other security threats. Our product is highly adaptable and supports multiple verification providers, giving
businesses the flexibility to choose the services that best suit their needs. Whether verifying government-issued IDs, conducting
facial recognition comparisons, or ensuring liveness to confirm that the user is physically present during the verification process,
our solution offers the highest standards of accuracy and security.
## Integration
> **Note:** Now that you are familiar with the product you can start the integration process. Chose the integration option by following the
> **API Integration Guide** or the **Java SDK Integration Guide** depending on your use case. You can find the appropriate links
> at the bottom of the page.
Learn how to integrate with Authologic identity product.
- [API Integration Guide](https://developer.authologic.com/docs/products/identity/api-integration): Learn how to integrate Authologic Identity working directly with the API.
- [Java SDK Integration Guide](https://developer.authologic.com/docs/products/identity/java-sdk): Learn how to integrate Authologic Identity working with the Java API.
# Identity - 5 Minutes Tutorial - API Integration
Source: https://developer.authologic.com/docs/products/identity/api-integration
Title: API Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to verify a user’s identity. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies himself
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification
> **Note:** We use the `curl` tool to show the API operation.
> If you have not dealt with it, you can find a short guide on it [here](https://www.baeldung.com/curl-rest).
> Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the
> link: [here](https://developer.authologic.com/api),
> or any other tool, such as Postman or Insomnia.
## Creating a Conversation
So let's try using the `curl` tool to start a new conversation, which is the identity checking process.
> **Warning:** The conversation creation API does not have any mandatory fields. This is because your account
> may have default values for all fields configured. Thanks to this, possible changes in the requirements are not
> connected with your code.
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
```shell
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).
For `my_callback_url_here` you could use 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*.
Authologic requires you to provide the API version number by providing them as part of the expected document types.
Therefore, in the query, we used the appropriate `Accept` and `Content-Type` headers, thanks to which the server will be
able to choose the appropriate format and API version.
- `userKey` - the field which you can use to provide your own user identification information. Authologic returns this field in the conversation results, but doesn't use the value of the field. It is optional and will be generated for you if omitted.
- `returnUrl` - address to which the user will be redirected by Authologic after verifying the identity. It may contain the fragment: `{conversationId}` - if it exists, it will be replaced with the conversation ID.
- `callbackUrl` - after process is completed, on this url we will send you user information or information that process has failed.
- `strategy` - information on how Authologic should perform the verification. This field is *optional*. If not specified, the system will use the default value. In our case, we used the `public:sandbox` strategy, which does not perform real verification, but allows you to select the result, which is convenient for implementation and integration tests.
- `query` - it is the query definition that contains the set of information we want to receive.
- `identity`- is the name of the product we want to ask for data. `Identity` specifies identity recognition. You will learn about other methods later.
- `requireOneOf` - data you want to be specified.
> **Note:** We set the default strategy together when setting up an account. If you need to change it, please contact us.
> **Note:** A list of the available strategies assigned to your account can be found on the main page of the customer portal.
> **Note:** The example given is for a test environment. If you perform these operations on the production environment
> that was provided to you then the `public:sandbox` strategy is not available. You can omit the `strategy` field to
> use the default strategy or use another one that we gave you the name of when determining your needs. As a result,
> nothing bad will happen, but remember that the production environment requires real data. The collected data will
> also be real.
For this tutorial we use very simple set of data, but you probably noticed unusual structure of an array of arrays,
find why and more detailed explanation: [here](https://developer.authologic.com/docs/technical/mandatory-and-optional-queries),
full list of available fields: [here](https://developer.authologic.com/docs/integration/user-info-fields).
The response should look something like this:
```json
{
"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`)
> **Note:** In the response there may be other fields, e.g. `info`. These fields are described separately, and we shouldn't worry about them now.
## Identity check
The user identity is checked by sending the user to the address returned in the `url` field.
So now open your browser and go to the page you got in this parameter. You should see the first screen of
the identity checking process. For our sample strategy, it will be a screen where we can enter the
data that the verification is to return.
After going through the process, you should be redirected to the `returnUrl` page that you entered when creating the conversation.
## Getting conversation result
Now let's check the conversation status. You should get request on url that was provided in `callbackUrl` field during
creating conversation.
```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.
This time the `status` has changed to `FINISHED`, which means the process is complete. At the same time, the `result`
structure also contains the `FINISHED` state, which means that all the data was successfully determined. Retrieved
data appeared in the `user` structure.
> **Tip:** That's it. You managed to use API and get data.
## What's Next
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
- [WebSDK](https://developer.authologic.com/docs/websdk/overview): Embedding the verification process within your website.
> **Note:** Embedding the verification process within your website is completely optional. Using redirection in your process if
> sufficient and more than enough to start working with Authologic. You can consider it when you would like the process
> to be a part of the web application.
## Additional Information
- [Create Conversation](https://developer.authologic.com/api/operations/createConversation): Detailed information about conversation creation API.
- [Conversation Statuses](https://developer.authologic.com/api/operations/getConversation): Working with conversation statuses.
- [Conversation Identity Metadata](https://developer.authologic.com/api/operations/getMetadata): Detailed description of conversation metadata retrieval API.
- [Conversation Identity Media](https://developer.authologic.com/api/operations/getMedia): Detailed description of conversation media retrieval API.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Identity - 5 Minutes Tutorial - Java SDK
Source: https://developer.authologic.com/docs/products/identity/java-sdk
Title: Java SDK Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to verify a user’s identity. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies himself
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification
One API for multiple online identity verification methods written in Java.
## Installation
The installation of the library is as simple as including it as one of the projects dependencies.
We encourage to use the newest version of the library as we are constantly expanding our product
offering and the underlying functionalities.
### Maven
Include the following dependency in your `pom.xml` file to use Authologic Java SDK:
```xml
com.authologic.client
authologic-client
0.2.48
```
### Gradle
Include the following dependency in your `build.gradle` file to use Authologic Java SDK:
```java
implementation("com.authologic.client:authologic-client:0.2.48")
```
## Usage
The following example demonstrate an example on how you can use the Java SDK to interact with the Authologic APIs.
### Creating Conversation
To start a new conversation process, which is the main entry point for the identity checking product the
following example can be used:
```java
import com.authologic.client.api.*;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
Client client = ClientBuilder.builder("username", "password").sandbox().build();
Conversation conversation = client.execute(
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
))
).get();
System.out.println(conversation.getUrl());
}
}
```
#### Creating the Client Instance
We start by creating the Client instance:
```java
Client client = ClientBuilder.builder("username", "password").sandbox().build();
```
API credentials can be generated via OmniPanel.
Because the API is secured you need the provided credentials to be able to interact with it.
Once initialized the `Client` instance may be used to interact with the Authologic API.
#### Creating the Conversation
Next we can create the conversation and request the first and last name of the person we are
requesting the identification for. For that purpose we use the `Requests.createConversation()`
using the following code snippet:
```java
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
))
```
We set:
- the strategy
- the callback URL
- the product that we want to use
The **strategy** is the information that tells Authologic how to perform the operation.
The field is optional, but you can explicitly provide the information to choose the strategy that
you want to use. In the above example we used the `public:sandbox`, a strategy which doesn't perform a
real verification, but allows to test the whole flow.
The **callback URL** is the URL that Authologic will send the user when the process, in our example case
the identification process, will be completed. You should set it to match return to your application or
use a service like [Webhook Site](https://webhook.site/) if you plan on testing the SDK.
The product that we want to use is the **Identity** product, which allows us to specify what kind of
information about the user we want to get. In our example we would like to retrieve the person first
and last name and to do that we use the `IdentityProductQueryBuilder` class and provide the list of
fields to retrieve:
```java
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
))
```
As the final step we print the URL of the created conversation to the standard output to be able to continue
the process. If you are trying out the SDK head to the returned link to fill out the data that will be
returned as test data for your identity verification test.
## What's Next
- [Handling Callbacks](https://developer.authologic.com/docs/integration/callbacks): Handling callbacks using Java SDK.
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# AML
Source: https://developer.authologic.com/docs/products/aml
Title: AML
Description: Our Anti-Money Laundering (AML) product is a solution designed to assist organizations in maintaining compliance with regulatory requirements while mitigating the risks associated with financial crimes. This comprehensive tool encompasses three core functionalities: AML verification combined with user identification, AML verification based on provided data, and AML list change monitoring. By integrating these elements, our solution provides a robust framework for identifying and mitigating potential money laundering activities, thus enhancing their overall risk management strategies. With an intuitive interface and seamless integration capabilities, organizations can easily adapt our AML solution to their existing workflows, ensuring a smooth and efficient compliance process.
Our Anti-Money Laundering (AML) product is a solution designed to assist organizations in maintaining compliance
with regulatory requirements while mitigating the risks associated with financial crimes. This comprehensive tool encompasses
three core functionalities: AML verification combined with user identification, AML verification based on provided data, and AML
list change monitoring. By integrating these elements, our solution provides a robust framework for identifying
and mitigating potential money laundering activities, thus enhancing their overall risk management strategies. With an intuitive
interface and seamless integration capabilities, organizations can easily adapt our AML solution to their existing workflows,
ensuring a smooth and efficient compliance process.
The first component of our AML product focuses on AML verification combined with user identification. This feature allows businesses
to conduct thorough due diligence by verifying the identity of users and assessing their risk profiles in real-time. By combining
user identification processes with AML checks, organizations can identify suspicious patterns and high-risk behaviors before they
escalate into more significant issues. In addition to user identification, our AML solution offers verification based on provided
data, enabling organizations to assess risks effectively even when direct identification may not be feasible. Furthermore, our AML
list change monitoring feature continuously tracks updates to regulatory lists, such as sanctions and watchlists, ensuring that
organizations remain compliant with evolving legal obligations. By providing timely alerts about significant changes to these lists,
businesses can promptly review and update their risk assessments.
## Integration
> **Note:** Now that you are familiar with the product you can start the integration process. Chose the integration option by following the
> **API Integration Guide** or the **Java SDK Integration Guide** depending on your use case. You can find the appropriate links
> at the bottom of the page.
Learn how to integrate with Authologic Anti-Money Laundering product.
- [API Integration Guide](https://developer.authologic.com/docs/products/aml/api-integration): Learn how to integrate Authologic AML working directly with the API.
- [Java SDK Integration Guide](https://developer.authologic.com/docs/products/aml/java-sdk): Learn how to integrate Authologic AML working with the Java API.
# AML - 5 Minutes Tutorial - API Integration
Source: https://developer.authologic.com/docs/products/aml/api-integration
Title: API Integration
Description: As part of the uniform API, Authologic allows you to check whether the user is on the AML lists. The response returns information on which lists the user's data has been found. Detailed information can also be downloaded.
As part of the uniform API, Authologic allows you to check whether the user is on the AML lists.
The response returns information on which lists the user's data has been found. Detailed information
can also be downloaded.
In practice, you want to start with one of the use cases for the AML.
- [With Identification](https://developer.authologic.com/docs/products/aml/api-integration-with-identity): Start the AML process with the user identification - perfect for AML when the user is not known up front.
- [With Provided User](https://developer.authologic.com/docs/products/aml/api-integration-without-identity): Start the AML process with the user data - perfect for AML when the user known up front.
- [Change Monitoring](https://developer.authologic.com/docs/products/aml/api-integration-aml-monitoring): Monitor the changes on the AML lists - perfect for continuous user monitoring.
# AML With Identity - 5 Minutes Tutorial - API Integration
Source: https://developer.authologic.com/docs/products/aml/api-integration-with-identity
Title: API Integration - With Identity
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to initialize the AML verification. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about conversation identifier and status
3. Authologic calls a callback on your server's side with the result of the verification
> **Note:** Please remember that in many cases gathering information requires additional time. When creating your system,
> it should be taken into account that the results of the verification process will be available to the user after some time,
> and thus it is desired to account for asynchronous communication.
> **Note:** We use the `curl` tool to show the API operation.
> If you have not dealt with it, you can find a short guide on it [here](https://www.baeldung.com/curl-rest).
> Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the
> link: [here](https://developer.authologic.com/api),
> or any other tool, such as Postman or Insomnia.
## Creating a Conversation
> **Note:** AML product works together with the `identity` product, so you will need to combine those two.
> You can learn more about the identity product [here](https://developer.authologic.com/docs/products/identity) and read more
> about combining products [here](https://developer.authologic.com/docs/integration/combining-products).
In order to retrieve information about the user's presence on the AML lists, a conversation must be created. In this
example we will use two products together - the `aml` and `identity`. When using the `aml` product it is necessary to
specify which lists should be checked and provide the data that should be checked. Example:
> **Warning:** The conversation creation API does not have any mandatory fields. This is because your account
> may have default values for all fields configured. Thanks to this, possible changes in the requirements are not
> connected with your code.
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
```shell
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",
"callbackUrl": "my_callback_url_here",
"returnUrl": "https://id.sandbox.authologic.com/c/{conversationId}/thankYou",
"query": {
"identity": {
"requireOneOf": [
[ "PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]
]
},
"aml": {
"checks": ["PEP", "SANCTIONS", "ADVERSE_MEDIA", "SIP", "OTHER"]
}
}
}'
```
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).
For `my_callback_url_here` you could use 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*.
In the example above, we have set conversation to check the following lists:
- `PEP` - List of persons in politically exposed positions.
- `SANCTIONS` - List of individuals for whom sanctions have been implemented.
- `SIP` - List of individuals with high risk, typically involved in criminal activities or suspicious activity has been found in the past. May have been involved in court proceedings, had previous criminal allegations, or been involved in financial crimes such as money laundering and terrorist financing.
- `ADVERSE_MEDIA` - List of publications related to a person.
- `OTHER` - List of individuals for whom other categories than `PEP`, `SIP`, `SANCTIONS` have been implemented e.g. `RCA`, `POI`, etc.
> **Warning:** Due to the necessity of checking data in many external databases, the response time may be longer.
> Therefore the data may not be immediately available at the time of creation. We strongly recommend using the
> [callback](https://developer.authologic.com/docs/integration/callbacks) mechanism to receive the AML results along with other requested
> conversation products.
A conversation defined this way returns an additional section in response to a query about its status:
```json
{
"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": {}
},
"aml": {
"status": "IN_PROGRESS"
}
}
}
```
Information: `status` acts identically to the `identity` section.
When a conversation is completed, the AML product reports in the `found` field those lists in which the
current user was found. A detailed report can be obtained by using the dedicated API method described
in the next section.
```json
{
"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",
"user": {
"person": {
"name": {
"firstName": "Maria",
"lastName": "Sochacka"
}
}
}
},
"aml": {
"status": "FINISHED",
"found": ["PEP", "SANCTIONS", "ADVERSE_MEDIA", "SIP", "OTHER"]
}
},
"info": [
{
"country": "PL",
"method": "PSD2"
}
]
}
```
## Downloading Detailed Information
Having information on which lists the user was found on, it is possible to download a detailed report containing the
collected information, e.g.:
```shell
curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/aml/PEP" \
-H "accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"
```
Parameterizing the call of the above method with the name of the AML list
`PEP`, `SANCTIONS`, `SIP`, `ADVERSE_MEDIA` we get the first page of results for a given list.
The response structure varies depending on the selected AML list. A detailed
description of the response structure can be found in the [AML product details](https://developer.authologic.com/api/operations/getAMLList)
section.
> **Tip:** That's it. You managed to use API and get data.
## What's Next
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
- [WebSDK](https://developer.authologic.com/docs/websdk/overview): Embedding the verification process within your website.
> **Note:** Embedding the verification process within your website is completely optional. Using redirection in your process if
> sufficient and more than enough to start working with Authologic. You can consider it when you would like the process
> to be a part of the web application.
## Additional Information
- [Bank Transactions Data](https://developer.authologic.com/api/operations/getBankTransactions): Detailed description of the bank transactions data retrieval.
- [Account Information Retrieval](https://developer.authologic.com/api/operations/getBankTransactionsAccounts): Description of the bank transactions account data information retrieval.
- [Statistics Retrieval](https://developer.authologic.com/api/operations/getBankTransactionsStats): Detailed description of the bank transactions statistics retrieval.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# AML Without Identity - 5 Minutes Tutorial - API Integration
Source: https://developer.authologic.com/docs/products/aml/api-integration-without-identity
Title: API Integration - Without Identity
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to initialize the AML verification. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about conversation identifier and status
3. Authologic calls a callback on your server's side with the result of the verification
> **Note:** Please remember that in many cases gathering information requires additional time. When creating your system,
> it should be taken into account that the results of the verification process will be available to the user after some time,
> and thus it is desired to account for asynchronous communication.
> **Note:** We use the `curl` tool to show the API operation.
> If you have not dealt with it, you can find a short guide on it [here](https://www.baeldung.com/curl-rest).
> Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the
> link: [here](https://developer.authologic.com/api),
> or any other tool, such as Postman or Insomnia.
## Creating a Conversation
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
In order to retrieve information about the user's presence on the AML lists, a conversation must be created. In this
example we will use the `aml` product. When using the `aml` product it is necessary to
specify which lists should be checked and provide the data that should be checked. However, in comparison to the AML
process with identity check we will provide the user details in the request that creates the conversation and initializes
the process. Example:
```shell
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": "your_callback_url_here",
"query": {
"aml": {
"checks": ["PEP", "SANCTIONS", "ADVERSE_MEDIA", "SIP", "OTHER"],
"user": {
"firstName": "Maria",
"lastName": "Sochacka",
"birthDate": "1964-05-11",
"nationality": "PL",
"nationalId": "72111102379"
}
}
}
}'
```
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).
In the example above, we have set conversation to check the following lists:
- `PEP` - List of persons in politically exposed positions
- `SANCTIONS` - List of individuals for whom sanctions have been implemented
- `SIP` - List of individuals with high risk, typically involved in criminal activities or suspicious activity has been found in the past. May have been involved in court proceedings, had previous criminal allegations, or been involved in financial crimes such as money laundering and terrorist financing.
- `ADVERSE_MEDIA` - List of publications related to a person
- `OTHER` - List of RCAs and individuals categorized in AML lists different from PEP, SIP or SANCTIONS.
A conversation defined in this way, in response to a query about its status, immediately returns the result, without the
need for interaction with the user. The result will also be sent using the `callback` mechanism.
> **Warning:** Due to the necessity of checking data in many external databases, the response time may be longer.
> Therefore the data may not be immediately available at the time of creation. We strongly recommend using the
> [callback](https://developer.authologic.com/docs/integration/callbacks) mechanism to receive the AML results along with other requested
> conversation products.
## Downloading Detailed Information
Having information on which lists the user was found on, it is possible to download a detailed report containing
the collected information, e.g.:
```shell
curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/aml/PEP" \
-H "accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"
```
Parameterizing the call of the above method with the name of the AML list `PEP`, `SANCTIONS`, `SIP`, `ADVERSE_MEDIA`, `OTHER`,
we get the first page of results for a given list.
The response structure varies depending on the selected AML list. A detailed description of the response structure can
be found in the [AML product details](https://developer.authologic.com/api/operations/getAMLList) section.
## Example Test Data
We have prepared test data sets on a `sandbox` environment.
In order to obtain differentiated results, in the field `query.aml.user.lastName`, one of the following names should be given:
- `Putin` - `PEP`, `SANCTIONS`, `SIP`, `ADVERSE_MEDIA`, `OTHER`
- `Shoygu` - `SANCTIONS`
- `Kwaśniewski` - `SIP`
- `Biden` - `PEP`
- `Trzaskowski` - `ADVERSE MEDIA`
- `Kowalski` - empty AML list
If you enter a name that is not on the list, the data associated with the name `Putin` will appear in the results.
The above data sets are also valid when running the [AML change monitoring functionality](https://developer.authologic.com/docs/products/aml/api-integration-aml-monitoring).
Then, after 2 and 5 minutes after the first data, we simulate changes in the results of AML lists. The related `callback`
notifications are also sent.
> **Tip:** That's it. You managed to use API and get data.
## What's Next
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
- [WebSDK](https://developer.authologic.com/docs/websdk/overview): Embedding the verification process within your website.
> **Note:** Embedding the verification process within your website is completely optional. Using redirection in your process if
> sufficient and more than enough to start working with Authologic. You can consider it when you would like the process
> to be a part of the web application.
## Additional Information
- [Bank Transactions Data](https://developer.authologic.com/api/operations/getBankTransactions): Detailed description of the bank transactions data retrieval.
- [Account Information Retrieval](https://developer.authologic.com/api/operations/getBankTransactionsAccounts): Description of the bank transactions account data information retrieval.
- [Statistics Retrieval](https://developer.authologic.com/api/operations/getBankTransactionsStats): Detailed description of the bank transactions statistics retrieval.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# AML Change Monitoring - 5 Minutes Tutorial - API Integration
Source: https://developer.authologic.com/docs/products/aml/api-integration-aml-monitoring
Title: API Integration - AML Monitoring
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to initialize the AML verification. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about conversation identifier and status
3. Authologic calls a callback on your server's side with the result of the verification
> **Note:** Please remember that in many cases gathering information requires additional time. When creating your system,
> it should be taken into account that the results of the verification process will be available to the user after some time,
> and thus it is desired to account for asynchronous communication.
> **Note:** Document describes how to track AML changes in the context of a specific user.
> If you want to learn more about AML product please start [here](https://developer.authologic.com/docs/products/aml).
## Create a Conversation
The [AML product](https://developer.authologic.com/docs/products/aml) describes how to create a user verification that includes
one-time check of AML lists. However, in multiple cases you are interested in the changes to
the AML list related to the user, so that you know when that person potentially appears on one of the
sanction list.
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
We will modify the example of setting up a conversation that we've used in our tutorial so that Authologic
informs you us about any changes to the given AML lists related to this user:
```shell
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": "your_callback_url_here",
"query": {
"identity": {
"requireOneOf": [
[ "PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]
]
},
"aml": {
"checks": ["PEP", "SANCTIONS", "ADVERSE_MEDIA", "SIP", "OTHER"],
"subscription": {}
}
}
}'
```
> **Warning:** Due to the necessity of checking data in many external databases, the response time may be longer.
> Therefore the data may not be immediately available at the time of creation. We strongly recommend using the
> [callback](https://developer.authologic.com/docs/integration/callbacks) mechanism to receive the AML results along with other requested
> conversation products.
The difference in the query is adding the fragment: `"subscription": {}`. The answer is automatically expanded
for subscription status, e.g .:
```json
{
"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": {}
},
"aml": {
"status": "IN_PROGRESS",
"subscription": {
"active": true
}
}
}
}
```
After the first check, there will also be an additional `lastChanged` field containing the date the last content change was detected
AML lists provided in the query.
```json
{
"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",
"user": {
"person": {
"name": {
"firstName": "Maria",
"lastName": "Sochacka"
}
}
}
},
"aml": {
"status": "FINISHED",
"found": ["PEP", "SANCTIONS", "ADVERSE_MEDIA", "SIP", "OTHER"],
"subscription": {
"active": true,
"lastChanged": "2022-08-12T13:42:53.018798Z"
}
}
},
"info": [
{
"country": "PL",
"method": "PSD2"
}
]
}
```
## Information About Changes
After detecting changes in monitored AML lists, Authologic automatically sends information about it via the callback mechanism,
where `target` = `SUBSCRIPTION` and `event` = `NEW_DATA`. The general structure of callbacks is described in the dedicated
[callbacks](https://developer.authologic.com/docs/integration/callbacks) section.
## Subscription Cancellation
Authlogic performs AML monitoring until the subscription is canceled. This continues until the
`DELETE /api/subscriptions/{conversationId}/aml` method call. After successfully unsubscribing,
the system responds with a header HTTP: `204 No Content`.
## What's Next
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
- [WebSDK](https://developer.authologic.com/docs/websdk/overview): Embedding the verification process within your website.
> **Note:** Embedding the verification process within your website is completely optional. Using redirection in your process if
> sufficient and more than enough to start working with Authologic. You can consider it when you would like the process
> to be a part of the web application.
## Additional Information
- [Bank Transactions Data](https://developer.authologic.com/api/operations/getBankTransactions): Detailed description of the bank transactions data retrieval.
- [Account Information Retrieval](https://developer.authologic.com/api/operations/getBankTransactionsAccounts): Description of the bank transactions account data information retrieval.
- [Statistics Retrieval](https://developer.authologic.com/api/operations/getBankTransactionsStats): Detailed description of the bank transactions statistics retrieval.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# AML - 5 Minutes Tutorial - Java SDK
Source: https://developer.authologic.com/docs/products/aml/java-sdk
Title: Java SDK Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to initialize the AML verification. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about conversation identifier and status
3. Authologic calls a callback on your server's side with the result of the verification
> **Note:** Please remember that in many cases gathering information requires additional time. When creating your system,
> it should be taken into account that the results of the verification process will be available to the user after some time,
> and thus it is desired to account for asynchronous communication.
One API for multiple online identity verification methods written in Java.
## Installation
The installation of the library is as simple as including it as one of the projects dependencies.
We encourage to use the newest version of the library as we are constantly expanding our product
offering and the underlying functionalities.
### Maven
Include the following dependency in your `pom.xml` file to use Authologic Java SDK:
```xml
com.authologic.client
authologic-client
0.2.48
```
### Gradle
Include the following dependency in your `build.gradle` file to use Authologic Java SDK:
```java
implementation("com.authologic.client:authologic-client:0.2.48")
```
## Usage
The following example demonstrate an example on how you can use the Java SDK to interact with the Authologic APIs.
### Creating Conversation
To start a new conversation process, which is the main entry point for the identity checking product the
following example can be used:
```java
import com.authologic.client.api.*;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
Client client = ClientBuilder.builder("username", "password").sandbox().build();
Conversation conversation = client.execute(
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
)).
addProduct(
new AMLProductQueryBuilder(
Arrays.asList(
AMLList.PEP,
AMLList.SANCTIONS,
AMLList.ADVERSE_MEDIA,
AMLList.SIP,
AMLList.OTHER
)
)
)
).get();
System.out.println(conversation.getUrl());
}
}
```
> **Warning:** Due to the necessity of checking data in many external databases, the response time may be longer.
> Therefore the data may not be immediately available at the time of creation. We strongly recommend using the
> [callback](https://developer.authologic.com/docs/integration/callbacks) mechanism to receive the AML results along with other requested
> conversation products.
#### Creating the Client Instance
We start by creating the Client instance:
```java
Client client = ClientBuilder.builder("username", "password").sandbox().build();
```
API credentials can be generated via OmniPanel.
Because the API is secured you need the provided credentials to be able to interact with it.
Once initialized the `Client` instance may be used to interact with the Authologic API.
#### Creating the Conversation
Next we can create the conversation and request the first and last name of the person we are
requesting the identification for. For that purpose we use the `Requests.createConversation()`
using the following code snippet:
```java
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
)).
addProduct(
new AMLProductQueryBuilder(
Arrays.asList(
AMLList.PEP,
AMLList.SANCTIONS,
AMLList.ADVERSE_MEDIA,
AMLList.SIP,
AMLList.OTHER
)
)
)
```
We set:
- the strategy
- the callback URL
- the products that we want to use and their configuration
The **strategy** is the information that tells Authologic how to perform the operation.
The field is optional, but you can explicitly provide the information to choose the strategy that
you want to use. In the above example we used the `public:sandbox`, a strategy which doesn't perform a
real verification, but allows to test the whole flow.
The **callback URL** is the URL that Authologic will send the user when the process, in our example case
the identification process, will be completed. You should set it to match return to your application or
use a service like [Webhook Site](https://webhook.site/) if you plan on testing the SDK.
The products that we want to use in this example are the [identity](https://developer.authologic.com/docs/products/identity) product
and the [AML](https://developer.authologic.com/docs/products/aml) product.
For the `identity` product we use the `IdentityProductQueryBuilder` class and provide the list of
fields to retrieve:
```java
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
))
```
For the `AML` product we use the `AMLProductQueryBuilder` class and provide the list of AML lists that
we are interested for.
```java
new AMLProductQueryBuilder(
Arrays.asList(
AMLList.PEP,
AMLList.SANCTIONS,
AMLList.ADVERSE_MEDIA,
AMLList.SIP,
AMLList.OTHER
)
)
```
As the final step we print the URL of the created conversation to the standard output to be able to continue
the process. If you are trying out the SDK head to the returned link to fill out the data that will be
returned as test data for your identity verification test.
## What's Next
- [Handling Callbacks](https://developer.authologic.com/docs/integration/callbacks): Handling callbacks using Java SDK.
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# User Authentication
Source: https://developer.authologic.com/docs/products/user-authentication
Title: User Authentication
Description: Authologic user authentication product is a versatile and secure solution designed to streamline access authentication, enabling businesses to build customized login processes for their systems. It supports multiple providers allowing you to choose the one that fits your users the most or integrate with multiple allowing the user to make the choice. All using a single API.
Authologic user authentication product is a versatile and secure solution designed to streamline access authentication,
enabling businesses to build customized login processes for their systems. It supports multiple providers allowing you
to choose the one that fits your users the most or integrate with multiple allowing the user to make the choice. All
using a single API.
## Integration
> **Note:** Now that you are familiar with the product you can start the integration process. Chose the integration option by following the
> **API Integration Guide** or the **Java SDK Integration Guide** depending on your use case. You can find the appropriate links
> at the bottom of the page.
Learn how to integrate with Authologic user authentication product.
- [API Integration Guide](https://developer.authologic.com/docs/products/user-authentication/api-integration): Learn how to integrate Authologic user authentication while working directly with the API.
- [Java SDK Integration Guide](https://developer.authologic.com/docs/products/user-authentication/java-sdk): Learn how to integrate Authologic user authentication while working with the Java API.
# User Authentication - 5 Minutes Tutorial - API Integration
Source: https://developer.authologic.com/docs/products/user-authentication/api-integration
Title: API Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
The entire user authentication process comes down to three steps:
- Sending to Authologic notification what data you want to get and what products you will use
- Redirecting the user to a unique address returned by Authologic
We have called the entire process 'conversation'. In the picture, the process looks like this:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about conversation identifier and status
> **Note:** We use the `curl` tool to show the API operation.
> If you have not dealt with it, you can find a short guide on it [here](https://www.baeldung.com/curl-rest).
> Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the
> link: [here](https://developer.authologic.com/api),
> or any other tool, such as Postman or Insomnia.
Authologic allows you to build a user login process (access authentication) to your system. To do this, the
user must first register. After user registration, the user can be authenticated at any time.
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
## Registration
Registration involves adding the `auth` section when creating a conversation:
```shell
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",
"query": {
"auth": {
}
}
}'
```
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).
After the user has gone through such a process and the conversation has been completed correctly, additional
data will appear in the response in the `auth` section, allowing for future user authentication. The exact
content depends on the specifics of the authentication method.
> **Warning:** Not all strategies support authentication. If you use a strategy that does not support this product, the
> strategy will not return authentication data.
## User Identification Methods
Some verification methods are able to determine the user themselves. In this case, simply redirect the user to
the authentication process. For such methods, a `token` is returned during registration - a unique user identifier.
The response always contains the following section:
```json
"auth": {
"status": "FINISHED",
"token": "d42115b0-58d3-4e9b-b970-12ca7de181c7"
}
```
A `Token` is a unique key associated with a user and authentication method. Each time this user authenticates using
this method, this token will be returned.
> **Note:** A user can have multiple tokens if you allow them to use different authentication methods.
## Methods Verifying Specified User
Some verification methods are only able to answer the question whether the user is who he or she
claims to be. This method requires providing additional information that indicates the user who will
be authenticated. For such methods, `token` - a unique user identifier and `challenge` - the equivalent
of a login, are returned during registration. The response then contains the following section:
```json
"auth": {
"status": "FINISHED",
"token": "d42115b0-58d3-4e9b-b970-12ca7de181c7",
"challenge": "2e3c01a8-a983-4024-acc9-8005c57d10af"
}
```
A `Token` is a unique key associated with a user and authentication method. `Challenge` specifies
the user to be verified. Each time this user authenticates using this method, the appropriate `challenge`
must be sent - after successful authentication, the above token will be returned.
> **Note:** A user can have multiple challenge / token pairs if you allow them to use different authentication methods.
## Authentication
Once the user has successfully registered, authentication operations can be performed. This means creating a
conversation with an `auth` section. There are some minor differences depending on the method used, described below.
## User Identification Methods
For such methods, a sample conversation might look like this:
```shell
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}",
"query": {
"auth": {
}
}
}'
```
As you can see, authentication in practice is no different from registration. After going through the process, the response may contain the following section:
```json
"auth": {
"status": "FINISHED",
"token": "d42115b0-58d3-4e9b-b970-12ca7de181c7"
}
```
`Token` directly identifies which user has passed authentication.
## Methods that verify the specified user
For such methods, a sample conversation might look like this:
```shell
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",
"query": {
"auth": {
"challenge": "2e3c01a8-a983-4024-acc9-8005c57d10af"
}
}
}'
```
In this model, it is necessary to provide `challenge` for the method to be able to determine
which user it is verifying. After going through the process, the response may contain the
following section:
```json
"auth": {
"status": "FINISHED",
"token": "d42115b0-58d3-4e9b-b970-12ca7de181c7",
"challenge": "2e3c01a8-a983-4024-acc9-8005c57d10af"
}
```
`Token` directly identifies which user has passed authentication. `Challenge` should match the value
provided when creating the conversation.
> **Tip:** That's it. You managed to use API and get data.
## What's Next
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
- [WebSDK](https://developer.authologic.com/docs/websdk/overview): Embedding the verification process within your website.
> **Note:** Embedding the verification process within your website is completely optional. Using redirection in your process if
> sufficient and more than enough to start working with Authologic. You can consider it when you would like the process
> to be a part of the web application.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# User Authentication - 5 Minutes Tutorial - Java SDK
Source: https://developer.authologic.com/docs/products/user-authentication/java-sdk
Title: Java SDK Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
The entire user authentication process comes down to three steps:
- Sending to Authologic notification what data you want to get and what products you will use
- Redirecting the user to a unique address returned by Authologic
We have called the entire process 'conversation'. In the picture, the process looks like this:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about conversation identifier and status
One API for multiple online identity verification methods written in Java.
## Installation
The installation of the library is as simple as including it as one of the projects dependencies.
We encourage to use the newest version of the library as we are constantly expanding our product
offering and the underlying functionalities.
### Maven
Include the following dependency in your `pom.xml` file to use Authologic Java SDK:
```xml
com.authologic.client
authologic-client
0.2.48
```
### Gradle
Include the following dependency in your `build.gradle` file to use Authologic Java SDK:
```java
implementation("com.authologic.client:authologic-client:0.2.48")
```
## Usage
The following example demonstrate an example on how you can use the Java SDK to interact with the Authologic APIs.
### Creating Conversation
To start a new conversation process, which is the main entry point for the auth product the
following example can be used:
```java
import com.authologic.client.api.*;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
Client client = ClientBuilder.builder("username", "password").sandbox().build();
Conversation conversation = client.execute(
Requests.
createConversation().
addProduct(
new AuthProductQueryBuilder().addChallenge("challenge")
)
).get();
ConversationAuthResult authResult = conversation.getResult().getAuth();
System.out.println("Status: " + authResult.getStatus());
System.out.println("Token: " + authResult.getToken());
System.out.println("Challenge: " + authResult.getChallenge());
}
}
```
#### Creating the Client Instance
We start by creating the Client instance:
```java
Client client = ClientBuilder.builder("username", "password").sandbox().build();
```
API credentials can be generated via OmniPanel.
Because the API is secured you need the provided credentials to be able to interact with it.
Once initialized the `Client` instance may be used to interact with the Authologic API.
#### Creating the Conversation
Next we can create the conversation and request the first and last name of the person we are
requesting the authentication for. For that purpose we use the `Requests.createConversation()`
using the following code snippet:
```java
Requests.
createConversation().
addProduct(
new AuthProductQueryBuilder().addChallenge("challenge")
)
```
The product that we want to use is the **auth** product, which allows us to specify the challenge that
is used by the authentication method.
As the result an instance of the `ConversationAuthResult` is created and will contain the status of the
execution, token and challenge depending on the authentication provider. We can use the mentioned object
to read those values:
```java
ConversationAuthResult authResult = conversation.getResult().getAuth();
System.out.println("Status: " + authResult.getStatus());
System.out.println("Token: " + authResult.getToken());
System.out.println("Challenge: " + authResult.getChallenge());
```
## What's Next
- [Handling Callbacks](https://developer.authologic.com/docs/integration/callbacks): Handling callbacks using Java SDK.
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Bank Transactions
Source: https://developer.authologic.com/docs/products/bank-transactions
Title: Bank Transactions
Description: Our bank transactions product is a comprehensive solution designed to help businesses and financial institutions efficiently manage and monitor user transactions. One of its primary features is the ability to list bank transactions for a specific user, providing a clear and detailed view of their financial activities. With this functionality, businesses can access the history of a user’s transactions, including deposits, withdrawals, transfers, and purchases. The product and its APIs ensure that transaction data is easy to retrieve and navigate.
Our bank transactions product is a comprehensive solution designed to help businesses and financial institutions
efficiently manage and monitor user transactions. One of its primary features is the ability to list bank
transactions for a specific user, providing a clear and detailed view of their financial activities. With this
functionality, businesses can access the history of a user’s transactions, including deposits, withdrawals,
transfers, and purchases. The product and its APIs ensure that transaction data is easy to retrieve and navigate.
Another key feature of our bank transactions product is its ability to generate detailed transaction statistics for a
user over a given period of time. Businesses can easily access summaries and insights into a user’s financial behaviors,
such as total spending, number of transaction per type, credit and debit spending.
## Integration
> **Note:** Now that you are familiar with the product you can start the integration process. Chose the integration option by following the
> **API Integration Guide** or the **Java SDK Integration Guide** depending on your use case. You can find the appropriate links
> at the bottom of the page.
Learn how to integrate with Authologic bank transactions product.
- [API Integration Guide](https://developer.authologic.com/docs/products/bank-transactions/api-integration): Learn how to integrate Authologic bank transactions while working directly with the API.
- [API Integration Guide](https://developer.authologic.com/docs/products/bank-transactions/api-transaction): Learn how to integrate Authologic bank transactions while working directly with the API.
- [Java SDK Integration Guide](https://developer.authologic.com/docs/products/bank-transactions/java-sdk): Learn how to integrate Authologic bank transactions while working with the Java API.
# Bank Transactions - 5 Minutes Tutorial - API Integration
Source: https://developer.authologic.com/docs/products/bank-transactions/api-integration
Title: API Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to verify a user’s identity. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies himself
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification and the status of the bank transactions
8. After the callback with bank transaction status `FINISHED` is received your system may start fetching the bank transactions via the API
> **Tip:** Sometimes Authologic is able to send the verification information before the user is redirected to the
> return page. However, many types of verification require additional time. When creating your system, it
> should be taken into account in the process that the verification result will be available to the user only
> after some time.
> **Note:** We use the `curl` tool to show the API operation.
> If you have not dealt with it, you can find a short guide on it [here](https://www.baeldung.com/curl-rest).
> Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the
> link: [here](https://developer.authologic.com/api),
> or any other tool, such as Postman or Insomnia.
## Creating a Conversation
In order to retrieve information about the user's bank transactions, a conversation must be created. In this
example we will use two products together - the `bankTransactions` and `identity`. When using the `bankTransactions` product it
is necessary to specify which lists should be checked and provide the data that should be checked. Example:
> **Warning:** The conversation creation API does not have any mandatory fields. This is because your account
> may have default values for all fields configured. Thanks to this, possible changes in the requirements are not
> connected with your code.
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
```shell
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.uthologic.com/c/{conversationId}/thankYou",
"callbackUrl": "my_callback_url_here",
"query": {
"identity": {
"requireOneOf": [
[ "PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]
]
},
"bankTransactions": {
"type": "ALL",
"flags": [ "INCLUDE_TAGS" ]
}
}
}'
```
The `bankTransactions` may include additional properties defining its behavior:
- `type` - the type of transactions you are interested in, can take the value of `ALL`, `CREDIT` or `DEBIT`.
- `flags` - array of additional flags that can include values `INCLUDE_SCHEDULED` to include scheduled transaction and `INCLUDE_TAGS` to include tags.
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).
For `my_callback_url_here` you could use 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*.
Conversation defined this way, in response to a query about its status, returns an additional section:
```json
{
"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": {}
},
"bankTransactions": {
"status": "IN_PROGRESS"
}
}
}
```
Info: `status` behaves identically to the `identity` section.
```json
{
"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",
"user": {
"person": {
"name": {
"firstName": "Maria",
"lastName": "Sochacka"
}
}
}
},
"bankTransactions": {
"status": "FINISHED"
}
},
"info": [
{
"country": "PL",
"method": "PSD2"
}
]
}
```
## Downloading Transactions
After finishing the conversation, we can retrieve the list of transactions using the query:
```shell
curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/bankTransactions" \
-H "Accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"
```
In the response we are getting the first page of results:
```json
{
"more": true,
"items": [
{
"id": "34df2bd6-b790-4560-9fc9-f86c86d87990",
"date": "2020-08-27T10:40:28.348Z",
"bank": "BREXPLPW",
"accountId": "PL68249000050000400075212326",
"type": "DEBIT",
"amount": 10030,
"currency": "PLN",
"title": "Zasilenie konta",
"sender": "Jan Kowalski",
"senderAccountId": "PL68249000050000400075212326",
"recipient": "Jan Kowalski",
"recipientAccountId": "PL32114020040000320250132522",
"postTransactionBalance": 10030,
"tags": ["internal"]
}
]
}
```
The key information here is the: `more`. If it has the value: `true`, then we can query for another page of results
by adding the parameter: `page`:
```shell
curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/bankTransactions?page=1" \
-H "accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"
```
By modifying the `page` parameter we can retrieve subsequent pages of results until the response shows `more` set to `false`.
## Retrieving information about bank accounts
Another element is the possibility of additional information about the returned accounts for which the user has given us permissions.
```shell
curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/bankTransactions/accounts" \
-H "accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"
```
The response is a list of items for each account given to us, e.g .:
```json
{
"items": [
{
"date": "2020-09-17T11:18:21.999Z",
"balance": 10030,
"bank": "BREXPLPW",
"accountId": "PL68249000050000400075212326",
"currency": "PLN",
"activationDate": "2014-11-19"
}
]
}
```
## Retrieving Transaction Statistics
Authologic also provides a number of transaction-related statistics. Here you can see the simplest form, without e.g.
specifying a date range. Details are traditionally described in
[Transaction Statistics](https://developer.authologic.com/api/operations/getBankTransactionsStats).
```shell
curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/bankTransactions/stats" \
-H "accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"
```
An example response of the above command looks as follows:
```json
{
"dateFrom": "2020-09-16T10:44:51.544Z",
"dateTo": "2020-09-16T10:44:51.544Z",
"items": [
{
"dateFirst": "2020-06-16T00:00:00.000Z",
"dateLast": "2020-09-16T00:00:00.000Z",
"numberOfCreditTransactions": 12,
"numberOfDebitTransactions": 12,
"avgCreditPerMonth": 300000,
"avgDebitPerMonth": 258000,
"avgCredit": 30000,
"avgDebit": 40000,
"maxCredit": 110000,
"maxDebit": 132000,
"accountId": "PL68249000050000400075212326",
"currency": "PLN"
}
]
}
```
> **Tip:** That's it. You managed to use API and get data.
## What's Next
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
- [WebSDK](https://developer.authologic.com/docs/websdk/overview): Embedding the verification process within your website.
> **Note:** Embedding the verification process within your website is completely optional. Using redirection in your process if
> sufficient and more than enough to start working with Authologic. You can consider it when you would like the process
> to be a part of the web application.
## Additional Information
- [Bank Transactions Data](https://developer.authologic.com/api/operations/getBankTransactions): Detailed description of the bank transactions data retrieval.
- [Account Information Retrieval](https://developer.authologic.com/api/operations/getBankTransactionsAccounts): Description of the bank transactions account data information retrieval.
- [Statistics Retrieval](https://developer.authologic.com/api/operations/getBankTransactionsStats): Detailed description of the bank transactions statistics retrieval.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Transactions labeling
Source: https://developer.authologic.com/docs/products/bank-transactions/api-transaction
Title: API Transaction
## Schema
Category value is returned in the `tag` field.
## Dictionary
The dictionary is a living document and will continue to evolve over time. New entries may be added, and existing ones may be modified as the business and analytical needs develop.
Category dictionary:
- `income:salary` - employment contract
- `income:bonus` - bonus
- `income:freelance:contract` - civil law contracts
- `income:freelance:b2b` - B2B
- `income:rental` - rental income
- `income:invoicing` - income from invoices
- `income:pension` - pension
- `income:other` - other or unrecognized income
- `income:bond` - bonds / securities
- `income:dividend` - dividends
- `income:gains` - investment gains
- `income:crypto` - cryptocurrencies
- `income:inharitance` - inheritance
- `income:donation` - donation
- `income:interest` - bank account interest
- `benefit:social:state` - general social benefits, e.g. social assistance
- `benefit:social:agricultural` - social insurance for farmers
- `benefit:child` - child benefit (500+)
- `benefit:unemployment` - employment office benefits
- `benefit:alimony:direct` - alimony paid directly by the obligated person
- `benefit:alimony:fund` - alimony fund
- `benefit:housing` - housing subsidies
- `benefit:health` - health reimbursements
- `benefit:pension` - pension / retirement benefits
- `benefit:grant` - grants
- `benefit:other` - other or unrecognized benefits
- `refund` - refund
- `refund:tax` - tax refund
- `refund:merchant` - store / e-commerce refund
- `refund:cashback` - cashback
- `compensation:insurance` - insurance refund
- `compensation:claim` - loan return, correction, complaint
- `compensation:damages` - compensation from court judgment
- `lending:mortgage` - mortgage loan
- `lending:loan` - consumer loan
- `lending:microloan` - payday loans
- `lending:non_bank_loan` - non-bank financial institution loans
- `lending:leasing` - leasing
- `lending:factoring` - factoring
- `lending:repayment:on_time` - loan repayments
- `lending:repayment:card` - credit card repayment
- `lending:repayment:late` - delayed repayments
- `transfer:investment_ops` - deposit/withdrawal from investment/deposit account
- `transfer:savings` - deposits/withdrawals from savings account
- `transfer:bank` - bank transactions
- `transfer:bank:fee` - fees
- `transfer:bank:commission` - commissions
- `transfer:own` - between own accounts
- `transfer:foreign` - foreign transfers
- `transfer:foreign:fx` - currency exchange
- `transfer:domestic` - domestic transfers
- `transfer:domestic:provider` - transactions via online payment provider
- `transfer:domestic:express` - e.g. BLIK
- `transfer:domestic:card` - card transactions
- `transfer:atm` - ATM transactions
- `transfer:atm:deposit` - ATM deposits
- `transfer:atm:withdrawal` - ATM withdrawals
- `transfer:overdraft` - overdraft transactions
- `transfer:overdraft:withdrawal` - overdraft usage
- `transfer:overdraft:repayment` - overdraft repayment
- `transfer:verification` - identity verification transactions
- `transfer:other` - other transfers
- `housing:rent` - rent
- `housing:maintenance` - maintenance / renovations
- `bills` - bills
- `bills:electricity` - electricity
- `bills:heating` - heating
- `bills:gas` - gas
- `bills:water` - water
- `bills:internet` - internet, TV
- `bills:phone` - phone
- `bills:waste` - waste disposal
- `bills:multidistributor` - multi-utility provider
- `bills:other` - other fees
- `bills:streaming` - Netflix, HBO, Spotify
- `shopping` - shopping
- `shopping:groceries` - groceries
- `shopping:clothing` - clothing
- `shopping:electronics` - electronics
- `shopping:homegoods` - home goods
- `shopping:cosmetics` - cosmetics
- `shopping:jewelry` - jewelry
- `shopping:sports` - sports accessories
- `shopping:press` - press
- `shopping:press:books` - books and newspapers
- `shopping:press:magazines` - magazines
- `shopping:online` - online games
- `shopping:multibrand` - multi-brand retail chains
- `shopping:other` - other
- `shopping:ecommerce` - e-commerce
- `shopping:tobacco` - tobacco expenses
- `shopping:alcohol` - alcohol expenses
- `shopping:pets` - pet expenses
- `shopping:flowers` - florists
- `shopping:children` - expenses related to children
- `transport` - transport
- `transport:fuel` - fuel
- `transport:taxi` - taxi, uber etc.
- `transport:parking` - parking
- `transport:highway` - highways
- `transport:repair` - service, repairs
- `transport:public` - public transport
- `transport:other` - other
- `food:restaurant` - restaurants
- `food:bar` - pubs, bars
- `food:delivery` - take-away / food delivery
- `travel` - travel
- `travel:ticket` - tickets
- `travel:hotel` - hotels, apartments, campsites
- `travel:agency` - organized holidays
- `travel:bussiness` - business trips
- `travel:other` - other travel
- `leisure` - leisure
- `leisure:entertainment` - cinema, theatre tickets
- `leisure:sports` - sports events tickets
- `leisure:others` - other leisure
- `health` - health
- `health:doctor` - doctor
- `health:dentist` - dentist
- `health:pharmacy` - pharmacy
- `education` - education
- `education:tuition` - tuition, schools
- `education:course` - courses, training
- `education:books` - books, textbooks
- `education:scholarship` - scholarships and educational grants
- `insurance` - insurance
- `insurance:car` - car insurance
- `insurance:life` - life insurance
- `insurance:home` - home insurance
- `insurance:other` - other insurance
- `insurance:travel` - travel insurance
- `insurance:indemnity` - indemnity insurance
- `tax` - tax
- `tax:property` - property tax
- `tax:income` - includes all personal income taxes
- `tax:income:monthly` - monthly personal income tax
- `tax:income:quartaly` - quarterly personal income tax
- `tax:income:b2b` - business income tax (B2B)
- `tax:vat` - value-added tax (VAT)
- `tax:vat:monthly` - monthly VAT
- `tax:vat:quartaly` - quarterly VAT
- `tax:social` - social contributions
- `tax:corporate` - includes all corporate income taxes
- `tax:corporate:monthly` - monthly corporate income tax
- `tax:corporate:quartaly` - quarterly corporate income tax
- `tax:other` - other taxes
- `tax:transfer_tax` - civil law transaction tax
- `tax:agricultural` - agricultural social insurance
- `tax:penalty` - fines, interest, tax penalties
- `services:legal` - lawyer
- `services:accounting` - accountant
- `services:repair` - repairs
- `services:cleaning` - cleaning
- `services:delivery` - delivery, couriers
- `services:other` - other
- `gambling` - gambling
- `gambling:betting` - sports betting
- `gambling:lotteries` - lotteries
- `gambling:casinos` - casinos
- `gambling:other` - other
- `donations:charity` - public benefit organization
- `donations:ngo` - non-governmental organizations
- `donations:other` - other
- `debt` - debt
- `debt:private` - private debt collection
- `debt:public` - public institution debt collection
- `debt:public:tax` - tax office debt collection
- `debt:public:social` - social insurance (ZUS) debt collection
- `debt:court` - court, bailiff, or enforcement costs
- `debt:other` - other
- `other:monthly` - recurring monthly transactions with similar title, date, and amount
- `other:uncategorized` - uncategorize
# Bank Transactions - 5 Minutes Tutorial - Java SDK
Source: https://developer.authologic.com/docs/products/bank-transactions/java-sdk
Title: Java SDK Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to verify a user’s identity. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies himself
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification and the status of the bank transactions
8. After the callback with bank transaction status `FINISHED` is received your system may start fetching the bank transactions via the API
> **Tip:** Sometimes Authologic is able to send the verification information before the user is redirected to the
> return page. However, many types of verification require additional time. When creating your system, it
> should be taken into account in the process that the verification result will be available to the user only
> after some time.
One API for multiple online identity verification methods written in Java.
## Installation
The installation of the library is as simple as including it as one of the projects dependencies.
We encourage to use the newest version of the library as we are constantly expanding our product
offering and the underlying functionalities.
### Maven
Include the following dependency in your `pom.xml` file to use Authologic Java SDK:
```xml
com.authologic.client
authologic-client
0.2.48
```
### Gradle
Include the following dependency in your `build.gradle` file to use Authologic Java SDK:
```java
implementation("com.authologic.client:authologic-client:0.2.48")
```
## Usage
The following example demonstrate an example on how you can use the Java SDK to interact with the Authologic APIs.
### Creating Conversation
To start a new conversation process, which is the main entry point for the identity checking product the
following example can be used:
```java
import com.authologic.client.api.*;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
Client client = ClientBuilder.builder("username", "password").sandbox().build();
Conversation conversation = client.execute(
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
)).
addProduct(
new BankTransactionsProductQueryBuilder()
)
).get();
System.out.println(conversation.getUrl());
}
}
```
#### Creating the Client Instance
We start by creating the Client instance:
```java
Client client = ClientBuilder.builder("username", "password").sandbox().build();
```
API credentials can be generated via OmniPanel.
Because the API is secured you need the provided credentials to be able to interact with it.
Once initialized the `Client` instance may be used to interact with the Authologic API.
#### Creating the Conversation
Next we can create the conversation and request the first and last name of the person we are
requesting the identification for. For that purpose we use the `Requests.createConversation()`
using the following code snippet:
```java
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
)
).
addProduct(
new BankTransactionsProductQueryBuilder()
)
```
We set:
- the strategy
- the callback URL
- the products that we want to use.
The **strategy** is the information that tells Authologic how to perform the operation.
The field is optional, but you can explicitly provide the information to choose the strategy that
you want to use. In the above example we used the `public:sandbox`, a strategy which doesn't perform a
real verification, but allows to test the whole flow.
The **callback URL** is the URL that Authologic will send the user when the process, in our example case
the identification process, will be completed. You should set it to match return to your application or
use a service like [Webhook Site](https://webhook.site/) if you plan on testing the SDK.
The products that we want to use in this example are the [identity](https://developer.authologic.com/docs/products/identity) product
and the [bank transactions](https://developer.authologic.com/docs/products/bank-transactions) product.
For the `identity` product we use the `IdentityProductQueryBuilder` class and provide the list of
fields to retrieve:
```java
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
))
```
For the `bankTransactions` product we use the `BankTransactionsProductQueryBuilder` class:
```java
addProduct(
new BankTransactionsProductQueryBuilder()
)
```
As the final step we print the URL of the created conversation to the standard output to be able to continue
the process. If you are trying out the SDK head to the returned link to fill out the data that will be
returned as test data for your identity verification test.
### Working with Callbacks
> **Note:** **Project dependencies:**
> Please remember that when working with callbacks you not only need the
> `authologic-client` library, but also `authologic-client-json` and one of the JSON parsing modules, for example
> `authologic-client-module-jackson`.
The Java SDK can also be used to parse the information sent to your callback URL. It is as simple as initializing one
of the JSON parsing engines, deserializing the body of the request received in the callback and using the result data.
For example this is how the code could look like:
```java
JsonEngine jsonEngine = (new JacksonJsonEngineProvider()).createJsonEngine();
Callback callback = jsonEngine.deserialize(callbackBody, Callback.class);
if (callback.isConversationFinished()) {
Conversation conversation = callback.asConversationFinished().getConversation();
if (conversation.getResult().getBankTransactions().getStatus() == ProductResultStatus.FINISHED) {
// TODO: schedule bank transactions fetching
}
}
```
Let's discuss the above example.
#### Initializing JSON Parser
We start by initializing the JSON parser, so we can easily parse the response.
We do it only once as the parser is thread-safe and can be reused later when needed:
```java
JsonEngine jsonEngine = (new JacksonJsonEngineProvider()).createJsonEngine();
```
#### Deserializing the Results
We assume that we got the callback body and stored i tin the `callbackBody` variable. Once we have it
we can easily deserialize it to the `CallbackResult` class using the initialized JSON parser:
```java
Callback callbackResult = jsonEngine.deserialize(ctx.body(), Callback.class);
```
The abstract Callback class provides two methods to identify the type of the result:
- the `isConversationFinished` returning `true` if the result is of type `Conversation` representing conversation
- the `isUnknownCallback` returning `true` if the result is of type `UnknownCallback` representing unknown callback
In the example code we expect the `FinishedConversationCallback`, so we check for it:
```java
if (callback.isConversationFinished()) {
```
After we verified that we got the class we were expecting we can retrieve the conversation from the
deserialized object and check whether the bank transactions are ready and if they are, we can schedule
fetching of the bank transactions via the dedicated API:
```java
Conversation conversation = callback.asConversationFinished().getConversation();
if (conversation.getResult().getBankTransactions().getStatus() == ProductResultStatus.FINISHED) {
// TODO: schedule bank transactions fetching
}
```
## What's Next
- [Handling Callbacks](https://developer.authologic.com/docs/integration/callbacks): Handling callbacks using Java SDK.
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Data Verification
Source: https://developer.authologic.com/docs/products/data-verification
Title: Data Verification
Description: Out data verification product supplements Authologic products offering by allowing verification of the provided data against numerous providers enabling comparison of the user identity with the provided data resulting in a numerical score representing the similarity of the data.
Out data verification product supplements Authologic products offering by allowing verification of the provided
data against numerous providers enabling comparison of the user identity with the provided data resulting in a numerical
score representing the similarity of the data.
## Integration
> **Note:** Now that you are familiar with the product you can start the integration process. Chose the integration option by following the
> **API Integration Guide** or the **Java SDK Integration Guide** depending on your use case. You can find the appropriate links
> at the bottom of the page.
Learn how to integrate with Authologic data verification product.
- [API Integration Guide](https://developer.authologic.com/docs/products/data-verification/api-integration): Learn how to integrate Authologic data verification while working directly with the API.
- [Java SDK Integration Guide](https://developer.authologic.com/docs/products/data-verification/java-sdk): Learn how to integrate Authologic data verification while working directly with Java API.
# Data Verification - 5 Minutes Tutorial - API Integration
Source: https://developer.authologic.com/docs/products/data-verification/api-integration
Title: API Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to verify a user’s identity. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies himself
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification
> **Note:** We use the `curl` tool to show the API operation.
> If you have not dealt with it, you can find a short guide on it [here](https://www.baeldung.com/curl-rest).
> Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the
> link: [here](https://developer.authologic.com/api),
> or any other tool, such as Postman or Insomnia.
## Creating a Conversation
In order to use the data verification product, a conversation must be created. In this
example we will use two products together - the `verify` and `identity`. When using the `verify` product it
is necessary to specify which lists should be checked and provide the data that should be checked. Example:
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
```shell
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",
"query": {
"identity": {
"requireOneOf": [
[ "PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]
]
},
"verify": {
"user": {
"person": {
"name": {
"firstName": "Jon",
"lastName": "Testowy"
}
}
}
}
}
}'
```
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).
For `my_callback_url_here` you could use 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*.
The transaction defined this way, in response to its status, has an additional section:
```json
{
"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": {}
},
"verify": {
"status": "IN_PROGRESS"
}
}
}
```
Note: `status` behaves identically to the `identity` section.
## End of Conversation
After the end of the conversation, information about the result of the comparison is displayed in the section containing
the result of the action:
```json
{
"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",
"user": {
"person": {
"name": {
"firstName": "Jan",
"lastName": "Testowy"
}
}
}
},
"verify": {
"status": "FINISHED",
"reliability": 0.6666666666666667,
"details": [
{
"field": "PERSON_NAME_FIRSTNAME",
"reliability": 0.6666666666666667
},
{
"field": "PERSON_NAME_LASTNAME",
"reliability": 1
}
]
}
},
"info": [
{
"country": "PL",
"method": "PSD2"
}
]
}
```
As you can see in the example, the answer contains a numeric measure of the fit of the data, on a scale of 0 (other data) to
1 (100% match). It also includes a comparison for each field separately.
> **Tip:** That's it. You managed to use API and get data.
## What's Next
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
- [WebSDK](https://developer.authologic.com/docs/websdk/overview): Embedding the verification process within your website.
> **Note:** Embedding the verification process within your website is completely optional. Using redirection in your process if
> sufficient and more than enough to start working with Authologic. You can consider it when you would like the process
> to be a part of the web application.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Data verification - 5 Minutes Tutorial - Java SDK
Source: https://developer.authologic.com/docs/products/data-verification/java-sdk
Title: Java SDK Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to verify a user’s identity. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies himself
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification
One API for multiple online identity verification methods written in Java.
## Installation
The installation of the library is as simple as including it as one of the projects dependencies.
We encourage to use the newest version of the library as we are constantly expanding our product
offering and the underlying functionalities.
### Maven
Include the following dependency in your `pom.xml` file to use Authologic Java SDK:
```xml
com.authologic.client
authologic-client
0.2.48
```
### Gradle
Include the following dependency in your `build.gradle` file to use Authologic Java SDK:
```java
implementation("com.authologic.client:authologic-client:0.2.48")
```
## Usage
The following example demonstrate an example on how you can use the Java SDK to interact with the Authologic APIs.
### Creating Conversation
To start a new conversation process, which is the main entry point for the identity checking product the
following example can be used:
```java
import com.authologic.client.api.*;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
Client client = ClientBuilder.builder("username", "password").sandbox().build();
Conversation conversation = client.execute(
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
)).
addProduct(
(new VerifyProductQueryBuilder())
.withVerifyUser(
UserInfos.person(
PersonName.builder().firstName("Jan").lastName("Kowalski").fullName("Jan Kowalski"),
PersonIds.builder().nationalId("20262801379"),
PersonInfo.builder().birthDate(LocalDate.parse("2000-06-28")).nationality("PL"),
Address.builder().addressLine("ul. Testowa 15/2").city("Warszawa").postalCode("00-999").country("Poland").text("ul. Testowa 15/2 00-999 Warszawa"),
Contact.builder().phoneOtp("+48500600700")
)
)
)
).get();
System.out.println(conversation.getUrl());
}
}
```
#### Creating the Client Instance
We start by creating the Client instance:
```java
Client client = ClientBuilder.builder("username", "password").sandbox().build();
```
API credentials can be generated via OmniPanel.
Because the API is secured you need the provided credentials to be able to interact with it.
Once initialized the `Client` instance may be used to interact with the Authologic API.
#### Creating the Conversation
Next we can create the conversation and request the first and last name of the person we are
requesting the identification for. For that purpose we use the `Requests.createConversation()`
using the following code snippet:
```java
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
)
).
addProduct(
(new VerifyProductQueryBuilder())
.withVerifyUser(
UserInfos.person(
PersonName.builder().firstName("Jan").lastName("Kowalski").fullName("Jan Kowalski"),
PersonIds.builder().nationalId("20262801379"),
PersonInfo.builder().birthDate(LocalDate.parse("2000-06-28")).nationality("PL"),
Address.builder().addressLine("ul. Testowa 15/2").city("Warszawa").postalCode("00-999").country("Poland").text("ul. Testowa 15/2 00-999 Warszawa"),
Contact.builder().phoneOtp("+48500600700")
)
)
)
```
We set:
- the strategy
- the callback URL
- the products that we want to use.
The **strategy** is the information that tells Authologic how to perform the operation.
The field is optional, but you can explicitly provide the information to choose the strategy that
you want to use. In the above example we used the `public:sandbox`, a strategy which doesn't perform a
real verification, but allows to test the whole flow.
The **callback URL** is the URL that Authologic will send the user when the process, in our example case
the identification process, will be completed. You should set it to match return to your application or
use a service like [Webhook Site](https://webhook.site/) if you plan on testing the SDK.
The products that we want to use in this example are the [identity](https://developer.authologic.com/docs/products/identity) product
and the [data verification](https://developer.authologic.com/docs/products/data-verification) product.
For the `identity` product we use the `IdentityProductQueryBuilder` class and provide the list of
fields to retrieve:
```java
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
))
```
For the `dataVerfication` product we use the `VerifyProductQueryBuilder` class:
```java
addProduct(
(new VerifyProductQueryBuilder())
.withVerifyUser(
UserInfos.person(
PersonName.builder().firstName("Jan").lastName("Kowalski").fullName("Jan Kowalski"),
PersonIds.builder().nationalId("20262801379"),
PersonInfo.builder().birthDate(LocalDate.parse("2000-06-28")).nationality("PL"),
Address.builder().addressLine("ul. Testowa 15/2").city("Warszawa").postalCode("00-999").country("Poland").text("ul. Testowa 15/2 00-999 Warszawa"),
Contact.builder().phoneOtp("+48500600700")
)
)
)
```
As the final step we print the URL of the created conversation to the standard output to be able to continue
the process. If you are trying out the SDK head to the returned link to fill out the data that will be
returned as test data for your identity verification test.
## What's Next
- [Handling Callbacks](https://developer.authologic.com/docs/integration/callbacks): Handling callbacks using Java SDK.
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Enquiry
Source: https://developer.authologic.com/docs/products/enquiry
Title: Enquiry
Description: Our Enquiry product is a powerful solution designed to simplify data collection through customizable forms included in the conversation workflow. With Enquiry, businesses can easily create tailored forms to gather essential information from users, streamlining processes such as surveys, registrations, feedback, and more.
Our Enquiry product is a powerful solution designed to simplify data collection through customizable forms
included in the conversation workflow. With Enquiry, businesses can easily create tailored forms to gather essential
information from users, streamlining processes such as surveys, registrations, feedback, and more.
The form structure is dynamic and can be easily tailored to your specific needs, however the form structure is currently
defined in collaboration with our team. Whether you require simple data fields or complex multi-input form, our solution delivers
reliability, adaptability, and ease of use for businesses of all types.
With Enquiry, businesses can efficiently collect, manage, and analyze user-provided data, empowering them to make informed
decisions and enhance customer interactions.
## Integration
> **Note:** Now that you are familiar with the product you can start the integration process. Chose the integration option by following the
> **API Integration Guide** or the **Java SDK Integration Guide** depending on your use case. You can find the appropriate links
> at the bottom of the page.
Learn how to integrate with Authologic enquiry product.
- [API Integration Guide](https://developer.authologic.com/docs/products/enquiry/api-integration): Learn how to integrate Authologic Enquiry working directly with the API.
- [Java SDK Integration Guide](https://developer.authologic.com/docs/products/enquiry/java-sdk): Learn how to integrate Authologic Enquiry working with the Java API.
# Enquiry - 5 Minutes Tutorial - API Integration
Source: https://developer.authologic.com/docs/products/enquiry/api-integration
Title: API Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to gather custom data from the user. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the filled form data.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user fills the form data
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the filled form
> **Note:** We use the `curl` tool to show the API operation.
> If you have not dealt with it, you can find a short guide on it [here](https://www.baeldung.com/curl-rest).
> Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the
> link: [here](https://developer.authologic.com/api),
> or any other tool, such as Postman or Insomnia.
## Creating a Conversation
So let's try using the `curl` tool to start a new conversation, which will include gathering of the enquiry form.
> **Warning:** The conversation creation API does not have any mandatory fields. This is because your account
> may have default values for all fields configured. Thanks to this, possible changes in the requirements are not
> connected with your code.
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
```shell
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:enquiry",
"query": {
"enquiry": {
"formId": "c1655381-b8c9-4598-b861-a6c4ac805504"
}
}
}'
```
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).
For `my_callback_url_here` you could use 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*.
Authologic requires you to provide the API version number by providing them as part of the expected document types.
Therefore, in the query, we used the appropriate `Accept` and `Content-Type` headers, thanks to which the server will be
able to choose the appropriate format and API version.
> **Note:** Our custom forms functionality can be used with the `public:sandbox` strategy, which does not perform real verification,
> but allows you to select the result, which is convenient for implementation and integration. We suggest setting the
> `strategy` parameter to `public:sandbox` in order to test the functionality during the integration process.
- `userKey` - the field which you can use to provide your own user identification information. Authologic returns this field in the conversation results, but doesn't use the value of the field. It is optional and will be generated for you if omitted.
- `returnUrl` - address to which the user will be redirected by Authologic after gathering the form data. It may contain the fragment: `{conversationId}` - if it exists, it will be replaced with the conversation ID.
- `callbackUrl` - after the process is completed, on this url we will send you user information or information that process has failed.
- `strategy` - information on how Authologic should perform the verification. This field is *optional*. If not specified, the system will use the default value. In our case, we used the `public:enquiry` strategy, which only gathers enquiry data and is convenient for implementation and integration tests.
- `query` - it is the query definition that contains the set of information we want to receive.
- `enquiry` - is the name of the product we want to ask for data. `Enquiry` specifies custom information gathered form the user.
- `formId` - the identifier of the enquiry form that you want to display to the user. This field is *optional*. If not specified, the system will use the default form defined for you.
> **Note:** To define a new enquiry form that you can use, please reach out to Authologic.
The response should look something like this:
```json
{
"id": "7bde4014-7144-4090-93fd-d839e840877b",
"userKey": "7dfb9ded-c38f-49ae-95e2-307283a0b1f6",
"url": "https://sandbox.authologic.com/c/c12c1adc-3ff0-4d32-b95c-c593135c903e",
"status": "CREATED",
"result": {
"enquiry": {
"status": "IN_PROGRESS",
"formId": "c1655381-b8c9-4598-b861-a6c4ac805504"
}
}
}
```
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 which data you will gather, 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 the form identifier (`formId`)
## Enquiry Form Display
The form data is gathered by sending the user to the address returned in the `url` field.
So now open your browser and go to the page you got in this parameter. You should see the screen with
the defined form.
After going through the process, you should be redirected to the `returnUrl` page that you entered when creating the conversation.
## Getting Conversation Result
Now let's check the conversation status. You should get request on url that was provided in `callbackUrl` field during
creating conversation.
```json
{
"id": "74b58e66-22c9-40c5-9af1-7ab0efa11753",
"created": "2025-01-07T09:03:45.559584+01:00",
"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": {
"enquiry": {
"status": "FINISHED",
"formId": "c1655381-b8c9-4598-b861-a6c4ac805504",
"formData": {
"email": "john.doe@doe.com",
"residence": "Real Avenue 9",
"termsAcceptance": "true"
}
}
}
}
}
}
```
> #### 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.
This time the `status` has changed to `FINISHED`, which means the process is complete. At the same time, the `result`
structure also contains the `FINISHED` state, which means that all the data was successfully determined. Retrieved
data appeared in the `user` structure.
> **Tip:** That's it. You managed to use API and get data.
## What's Next
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
- [WebSDK](https://developer.authologic.com/docs/websdk/overview): Embedding the verification process within your website.
> **Note:** Embedding the verification process within your website is completely optional. Using redirection in your process if
> sufficient and more than enough to start working with Authologic. You can consider it when you would like the process
> to be a part of the web application.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Enquiry - 5 Minutes Tutorial - Java SDK
Source: https://developer.authologic.com/docs/products/enquiry/java-sdk
Title: Java SDK Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to gather custom data from the user. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the filled form data.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user fills the form data
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the filled form
One API for multiple online identity verification methods written in Java.
## Installation
The installation of the library is as simple as including it as one of the projects dependencies.
We encourage to use the newest version of the library as we are constantly expanding our product
offering and the underlying functionalities.
### Maven
Include the following dependency in your `pom.xml` file to use Authologic Java SDK:
```xml
com.authologic.client
authologic-client
0.2.48
```
### Gradle
Include the following dependency in your `build.gradle` file to use Authologic Java SDK:
```java
implementation("com.authologic.client:authologic-client:0.2.48")
```
## Usage
The following example demonstrate an example on how you can use the Java SDK to interact with the Authologic APIs.
### Creating Conversation
To start a new conversation process, which is the main entry point for the identity checking product the
following example can be used:
```java
import com.authologic.client.api.*;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
Client client = ClientBuilder.builder("username", "password").sandbox().build();
Conversation conversation = client.execute(
Requests.
createConversation().
strategy("public:enquiry").
callbackUrl("some_callback_url").
addProduct(
ProductQueries
.enquiry().withForm("c1655381-b8c9-4598-b861-a6c4ac805504")
)
).get();
System.out.println(conversation.getUrl());
}
}
```
#### Creating the Client Instance
We start by creating the Client instance:
```java
Client client = ClientBuilder.builder("username", "password").sandbox().build();
```
API credentials can be generated via OmniPanel.
Because the API is secured you need the provided credentials to be able to interact with it.
Once initialized the `Client` instance may be used to interact with the Authologic API.
#### Creating the Conversation
Next we can create the conversation and request the form with the provided identifier. For
that purpose we use the `Requests.createConversation()` using the following code snippet:
```java
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
ProductQueries
.enquiry().withForm("c1655381-b8c9-4598-b861-a6c4ac805504")
)
```
We set:
- the strategy
- the callback URL
- the product that we want to use
The **strategy** is the information that tells Authologic how to perform the operation.
The field is optional, but you can explicitly provide the information to choose the strategy that
you want to use. In the above example we used the `public:enquiry`, a strategy which doesn't perform
anything apart from displaying the requested form and gather the data without additional workflow
steps.
The **callback URL** is the URL that Authologic will send the user when the process, in our example case
the identification process, will be completed. You should set it to match return to your application or
use a service like [Webhook Site](https://webhook.site/) if you plan on testing the SDK.
The product that we want to use is the **Enquiry** product, which allows us to specify the form that
will be displayed to the user in order to gather custom data. In our example we request a form with
the identifier `c1655381-b8c9-4598-b861-a6c4ac805504` which needs to be defined upfront.
```java
ProductQueries
.enquiry().withForm("c1655381-b8c9-4598-b861-a6c4ac805504")
```
The identifier is optional and when not provided the form that was marked as default will be used.
In such case the code would look as follows:
```java
ProductQueries
.enquiry().withDefaultForm()
```
As the final step we print the URL of the created conversation to the standard output to be able to continue
the process. If you are trying out the SDK head to the returned link to fill out the data that will be
returned as test data for your identity verification test.
## What's Next
- [Handling Callbacks](https://developer.authologic.com/docs/integration/callbacks): Handling callbacks using Java SDK.
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Affordability assessment
Source: https://developer.authologic.com/docs/products/affordability
Title: Affordability assessment
Description: Our Affordability Assessment product is a comprehensive solution designed to ensure that end users can realistically afford a product, service, or financial commitment. In an increasingly regulated landscape, affecting industries such as gambling, banking, telecom, and insurance etc., verifying a user's financial capacity is no longer just a best practice—it is a legal necessity. Our tool streamlines this process, helping businesses meet legal requirements by accurately verifying Source of Funds (SoF) and Source of Wealth (SoW).
Our Affordability Assessment product is a comprehensive solution designed to ensure that end users can realistically
afford a product, service, or financial commitment. In an increasingly regulated landscape, affecting industries such as
gambling, banking, telecom, and insurance etc., verifying a user's financial capacity is no longer just a best
practice—it is a legal necessity. Our tool streamlines this process, helping businesses meet legal requirements by
accurately verifying Source of Funds (SoF) and Source of Wealth (SoW).
### Multi-Source Financial Insights
The power of our Affordability Assessment lies in its ability to aggregate and normalize data from various reliable
sources, integrating diverse data streams to provide a holistic view of a user’s financial situation. This approach
ensures a consistent and high-quality dataset that remains reliable regardless of the information's origin.
### Advanced Analysis & Customization
Our product provides deep financial insights through automated analysis of income and expenditures. Businesses can
easily configure the scope of data they receive, ranging from general income verification to detailed breakdowns of
spending habits and financial patterns. This flexibility allows for a tailored approach that fits specific business
needs while maintaining a seamless experience for the end user.
## Integration
> **Note:** Now that you are familiar with the product you can start the integration process. Chose the integration option by following the
> **API Integration Guide** or the **Java SDK Integration Guide** depending on your use case. You can find the appropriate links
> at the bottom of the page.
Learn how to integrate with Authologic affordability assessment product.
- [API Integration Guide](https://developer.authologic.com/docs/products/affordability/api-integration): Learn how to integrate Authologic Affordability assessment working directly with the API.
- [Java SDK Integration Guide](https://developer.authologic.com/docs/products/affordability/java-sdk): Learn how to integrate Authologic Identity Affordability assessment with the Java API.
# Affordability assessment - 5 Minutes Tutorial - API Integration
Source: https://developer.authologic.com/docs/products/affordability/api-integration
Title: API Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to check a user’s affordability assessment. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the affordability assessment verification process. Your server calls the API method called: *POST
/api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies himself
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification
> **Note:** We use the `curl` tool to show the API operation.
> If you have not dealt with it, you can find a short guide on it [here](https://www.baeldung.com/curl-rest).
> Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the
> link: [here](https://developer.authologic.com/api),
> or any other tool, such as Postman or Insomnia.
## Creating a Conversation
So let's try using the `curl` tool to start a new conversation, which is the identity checking process.
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
Here's how to create a conversation with minimal user information required:
```shell
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": {
"affordability": {
"user": {
"country": "PL"
}
}
}
}'
```
The next example shows a similar conversation, but with all user information provided:
```shell
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": {
"affordability": {
"user": {
"firstName": "John",
"lastName": "Doe",
"birthDate": "1990-01-01",
"houseNumber": "44",
"postalCode": "00-999",
"country": "PL",
"email": "johndoe@email.com"
}
}
}
}'
```
With both examples taken into account, one can see the only required user information is `country`. All other pieces of
information are optional.
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).
For `my_callback_url_here` you could use 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*.
Authologic requires you to provide the API version number by providing them as part of the expected document types.
Therefore, in the query, we used the appropriate `Accept` and `Content-Type` headers, thanks to which the server will be
able to choose the appropriate format and API version.
- `userKey` - the field which you can use to provide your own user identification information. Authologic returns this
field in the conversation results, but doesn't use the value of the field. It is optional and will be generated for
you if omitted.
- `returnUrl` - address to which the user will be redirected by Authologic after verifying the identity. It may contain
the fragment: `{conversationId}` - if it exists, it will be replaced with the conversation ID.
- `callbackUrl` - after process is completed, on this url we will send you user information or information that process
has failed.
- `strategy` - information on how Authologic should perform the verification. This field is *optional*. If not
specified, the system will use the default value. In our case, we used the `public:sandbox` strategy, which does not
perform real verification, but allows you to select the result, which is convenient for implementation and integration
tests.
- `query` - it is the query definition that contains the set of information we want to receive.
- `affordability`- is the name of the product we want to ask for data. `Affordability` specifies affordability
assessment check. You will
learn about other methods later.
> **Note:** We set the default strategy together when setting up an account. If you need to change it, please contact us.
> **Note:** A list of the available strategies assigned to your account can be found on the main page of the customer portal.
> **Note:** The example given is for a test environment. If you perform these operations on the production environment
> that was provided to you then the `public:sandbox` strategy is not available. You can omit the `strategy` field to
> use the default strategy or use another one that we gave you the name of when determining your needs. As a result,
> nothing bad will happen, but remember that the production environment requires real data. The collected data will
> also be real.
The response should look something like this:
```json
{
"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": {
"affordability": {
"status": "IN_PROGRESS"
}
}
}
```
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`
> **Note:** In the response there may be other fields, e.g. `info`. These fields are described separately, and we shouldn't worry
> about them now.
## Affordability assessment check
The user affordability assessment is verified by sending the user to the address returned in the `url` field.
So now open your browser and go to the page you got in this parameter. You should see the first screen of
the affordability assessment process. For our sample strategy, it will be a screen where we can enter the
data that the verification is to return.
After going through the process, you should be redirected to the `returnUrl` page that you entered when creating the
conversation.
## Getting conversation result
Now let's check the conversation status. You should get request on url that was provided in `callbackUrl` field during
creating conversation.
```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": {
"affordability": {
"status": "FINISHED",
"errors": []
}
}
}
}
}
```
> #### 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.
This time the `status` has changed to `FINISHED`, which means the process is complete. At the same time, the `result`
structure also contains the `FINISHED` state, which means that all the data was successfully determined.
## Downloading affordability assessment results
After finishing the conversation, we can retrieve the set of data representing affordability assessment results by using
the query:
```shell
curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/affordability/info" \
-H "Accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"
```
In the response we are getting the results:
```json
{
"items": [
{
"personalInformation": {
"firstName": "Jan",
"lastName": "Polny",
"birthDate": "1998-01-14",
"address": {
"text": "Dolna 12 00-999 Warszawa Polska",
"addressLine": "Dolna 12",
"postalCode": "00-999",
"city": "Warszawa",
"country": "PL"
}
},
"accountInformation": {
"account": [
{
"accountNumber": "PL12345678901234567890123456",
"bankName": "Bank Millennium",
"accountType": "Current",
"balance": 15450.75,
"overdraft": "true",
"currency": "PLN"
}
]
},
"sourceOfFundsInformation": {
"sourceOfFunds": [
{
"type": "Employment",
"name": "Tech Solutions sp. z o.o.",
"grossAmount": 8500,
"netAmount": 6120.5,
"frequency": "Monthly",
"contractType": "Permanent",
"contractEndDate": "2099-12-31",
"partTimePercentage": 1,
"currency": "PLN",
"currencyConversion": {
"convertedAmount": 4766.94,
"targetCurrency": "USD",
"exchangeRate": 1.1770
}
}
]
},
"documentInformation": {
"type": "Employment",
"number": "FD/HKJ/45/2025",
"issueDate": "2025-08-25",
"confidenceScore": "0.88",
"trustScore": 0.7,
"periodStart": "2025-09-01",
"periodEnd": "2025-12-31"
},
"financialAnalysis": {
"income": 7500,
"expenditure": 4200.5,
"currency": "PLN"
}
},
...
]
}
```
> **Tip:** That's it. You managed to use API and get data.
## What's Next
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
- [WebSDK](https://developer.authologic.com/docs/websdk/overview): Embedding the verification process within your website.
> **Note:** Embedding the verification process within your website is completely optional. Using redirection in your process if
> sufficient and more than enough to start working with Authologic. You can consider it when you would like the process
> to be a part of the web application.
## Additional Information
- [Affordability assessment data](https://developer.authologic.com/api/operations/getAffordability): Detailed description of the affordability assessment data retrieval.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Affordability assessment - 5 Minutes Tutorial - Java SDK
Source: https://developer.authologic.com/docs/products/affordability/java-sdk
Title: Java SDK Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to check a user’s affordability assessment. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the affordability assessment verification process. Your server calls the API method called: *POST
/api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies himself
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification
One API for online affordability assessment verification written in Java.
## Installation
The installation of the library is as simple as including it as one of the projects dependencies.
We encourage to use the newest version of the library as we are constantly expanding our product
offering and the underlying functionalities.
### Maven
Include the following dependency in your `pom.xml` file to use Authologic Java SDK:
```xml
com.authologic.client
authologic-client
0.2.48
```
### Gradle
Include the following dependency in your `build.gradle` file to use Authologic Java SDK:
```java
implementation("com.authologic.client:authologic-client:0.2.48")
```
## Usage
The following example demonstrate an example on how you can use the Java SDK to interact with the Authologic APIs.
### Creating Conversation
To start a new conversation process, which is the main entry point for the identity checking product the
following example can be used:
```java
import com.authologic.client.api.*;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
Client client = ClientBuilder.builder("username", "password").sandbox().build();
Conversation conversation = client.execute(
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new AffordabilityProductQueryBuilder(
new AffordabilityUser("John", "Doe", "J", "1990-01-01", "44", "00-999", "PL", "johndoe@email.com")
))
).get();
System.out.println(conversation.getUrl());
}
}
```
#### Creating the Client Instance
We start by creating the Client instance:
```java
Client client = ClientBuilder.builder("username", "password").sandbox().build();
```
API credentials can be generated via OmniPanel.
Because the API is secured you need the provided credentials to be able to interact with it.
Once initialized the `Client` instance may be used to interact with the Authologic API.
#### Creating the Conversation
Next we can create the conversation and request the first and last name of the person we are
requesting the identification for. For that purpose we use the `Requests.createConversation()`
using the following code snippet:
```java
Requests.createConversation().strategy("public:sandbox").callbackUrl("some_callback_url").addProduct(
new AffordabilityProductQueryBuilder(
new AffordabilityUser("John", "Doe","J","1990-01-01","44","00-999","PL","johndoe@email.com")
)
)
```
We set:
- the strategy
- the callback URL
- the product that we want to use
The **strategy** is the information that tells Authologic how to perform the operation.
The field is optional, but you can explicitly provide the information to choose the strategy that
you want to use. In the above example we used the `public:sandbox`, a strategy which doesn't perform a
real verification, but allows to test the whole flow.
The **callback URL** is the URL that Authologic will send the user when the process, in our example case
the identification process, will be completed. You should set it to match return to your application or
use a service like [Webhook Site](https://webhook.site/) if you plan on testing the SDK.
The product that we want to use is the **Affordability assessment** product, which allows us to perform verification.
In our example we provide all information required to perform affordability assessment check.
To do that we use the `AffordabilityProductQueryBuilder` class and provide the person's data:
```java
new AffordabilityProductQueryBuilder(
new AffordabilityProductUserBuilder(
new AffordabilityUser("John", "Doe","J","1990-01-01","44","00-999","PL","johndoe@email.com")
)
)
```
As the final step we print the URL of the created conversation to the standard output to be able to continue
the process. If you are trying out the SDK head to the returned link to fill out the data that will be
returned as test data for your affordability assessment verification test.
### Working with Callbacks
> **Note:** **Project dependencies:**
> Please remember that when working with callbacks you not only need the
> `authologic-client` library, but also `authologic-client-json` and one of the JSON parsing modules, for example
> `authologic-client-module-jackson`.
The Java SDK can also be used to parse the information sent to your callback URL. It is as simple as initializing one
of the JSON parsing engines, deserializing the body of the request received in the callback and using the result data.
For example this is how the code could look like:
```java
JsonEngine jsonEngine = (new JacksonJsonEngineProvider()).createJsonEngine();
Callback callback = jsonEngine.deserialize(callbackBody, Callback.class);
if (callback.isConversationFinished()) {
Conversation conversation = callback.asConversationFinished().getConversation();
if (conversation.getResult().getAffordability().getStatus() == ProductResultStatus.FINISHED) {
// TODO: schedule affordability assessment result fetching
}
}
```
Let's discuss the above example.
#### Initializing JSON Parser
We start by initializing the JSON parser, so we can easily parse the response.
We do it only once as the parser is thread-safe and can be reused later when needed:
```java
JsonEngine jsonEngine = (new JacksonJsonEngineProvider()).createJsonEngine();
```
#### Deserializing the Results
We assume that we got the callback body and stored i tin the `callbackBody` variable. Once we have it
we can easily deserialize it to the `CallbackResult` class using the initialized JSON parser:
```java
Callback callbackResult = jsonEngine.deserialize(ctx.body(), Callback.class);
```
The abstract Callback class provides two methods to identify the type of the result:
- the `isConversationFinished` returning `true` if the result is of type `Conversation` representing conversation
- the `isUnknownCallback` returning `true` if the result is of type `UnknownCallback` representing unknown callback
In the example code we expect the `FinishedConversationCallback`, so we check for it:
```java
if (callback.isConversationFinished()) {
```
After we verified that we got the class we were expecting we can retrieve the conversation from the
deserialized object and check whether the affordability assessment results are ready and if they are, we can schedule
fetching of the affordability assessment results via the dedicated API:
```java
Conversation conversation = callback.asConversationFinished().getConversation();
if (conversation.getResult().getAffordability().getStatus() == ProductResultStatus.FINISHED) {
// TODO: schedule affordability assessment results fetching
}
```
#### Collecting affordability product results from API endpoint
The Java SDK can also be used to call API endpoint to retrieve the information about affordability assessment
results.
Simply initialize the client and call `getAffordabilityResults` method and provide `conversationId` parameter.
You should then parse the response and retrieve the result data from individual sections.
For example this is how the code could look like:
```java
Client client = ClientBuilder.builder("your-username", "your-password")
.sandbox()
.build();
String conversationId = "Authologic conversation identifier";
// Execute GET /conversations/{conversationId}/affordability/info
AffordabilityResults results = client
.execute(Requests.getAffordabilityResults(conversationId))
.getOrThrow(ex -> ex); // rethrows ApiException
results.getItems().forEach(item -> {
//Fetch personal information
item.getPersonalInformation().getFirstName()
item.getPersonalInformation().getLastName());
//Fetch account information
item.getAccountInformation().getAccount().forEach(...);
//Fetch source of funds information
item.getSourceOfFundsInformation().getSource().forEach(...);
//Fetch financial analysis information
item.getFinancialAnalysis().getIncome()
item.getFinancialAnalysis().getExpenditure());
});
```
## What's Next
- [Handling Callbacks](https://developer.authologic.com/docs/integration/callbacks): Handling callbacks using Java SDK.
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Age Verification - 5 Minutes Tutorial - API Integration [BETA]
Source: https://developer.authologic.com/docs/products/age-verification/api-integration
Title: API Integration
> **⚠️ BETA Product**: This product is currently in beta. Features and integrations are under active development.
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to verify a user's age. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the age verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies their age
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification
> **Note:** We use the `curl` tool to show the API operation.
> If you have not dealt with it, you can find a short guide on it [here](https://www.baeldung.com/curl-rest).
> Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the
> link: [here](https://developer.authologic.com/api),
> or any other tool, such as Postman or Insomnia.
## Creating a Conversation
Let's try using the `curl` tool to start a new conversation for age verification.
> **Warning:** The conversation creation API does not have any mandatory fields. This is because your account
> may have default values for all fields configured. Thanks to this, possible changes in the requirements are not
> connected with your code.
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
```shell
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": {
"ageVerification": {
"over": 18
}
}
}'
```
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).
For `my_callback_url_here` you could use 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*.
Authologic requires you to provide the API version number by providing them as part of the expected document types.
Therefore, in the query, we used the appropriate `Accept` and `Content-Type` headers, thanks to which the server will be
able to choose the appropriate format and API version.
- `userKey` - the field which you can use to provide your own user identification information. Authologic returns this field in the conversation results, but doesn't use the value of the field. It is optional and will be generated for you if omitted.
- `returnUrl` - address to which the user will be redirected by Authologic after verifying the age. It may contain the fragment: `{conversationId}` - if it exists, it will be replaced with the conversation ID.
- `callbackUrl` - after process is completed, on this url we will send you the verification result or information that process has failed.
- `strategy` - information on how Authologic should perform the verification. This field is *optional*. If not specified, the system will use the default value. In our case, we used the `public:sandbox` strategy, which does not perform real verification, but allows you to select the result, which is convenient for implementation and integration tests.
- `query` - it is the query definition that contains the set of information we want to receive.
- `ageVerification` - is the name of the product we want to ask for. Age Verification specifies age confirmation.
- `over` - the minimum age threshold to verify (e.g., 18, 21, or any custom age requirement).
> **Note:** We set the default strategy together when setting up an account. If you need to change it, please contact us.
> **Note:** A list of the available strategies assigned to your account can be found on the main page of the customer portal.
> **Note:** The example given is for a test environment. If you perform these operations on the production environment
> that was provided to you then the `public:sandbox` strategy is not available. You can omit the `strategy` field to
> use the default strategy or use another one that we gave you the name of when determining your needs. As a result,
> nothing bad will happen, but remember that the production environment requires real data. The collected data will
> also be real.
The response should look something like this:
```json
{
"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": {
"ageVerification": {
"status": "IN_PROGRESS",
"over": 18,
"result": null
}
}
}
```
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 their age.
- `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 verification result, so there appears, within the product for which we asked the status: `IN_PROGRESS`, the age threshold (`over`), and `null` for the result.
> **Note:** In the response there may be other fields, e.g. `info`. These fields are described separately, and we shouldn't worry about them now.
## Age Verification Check
The user age is verified by sending the user to the address returned in the `url` field.
So now open your browser and go to the page you got in this parameter. You should see the first screen of
the age verification process. For our sample strategy, it will be a screen where we can simulate the
verification result.
After going through the process, you should be redirected to the `returnUrl` page that you entered when creating the conversation.
## Getting Conversation Result
Now let's check the conversation status. You should get request on url that was provided in `callbackUrl` field during
creating conversation.
```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": {
"ageVerification": {
"status": "FINISHED",
"over": 18,
"result": true
}
}
}
}
}
```
> #### 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.
This time the `status` has changed to `FINISHED`, which means the process is complete. At the same time, the `result`
structure also contains the `FINISHED` state, which means that the verification was successfully completed. The `result`
field contains a boolean value:
- `true` - the user is over the specified age threshold
- `false` - the user is not over the specified age threshold
> **Tip:** That's it. You managed to use API and verify user age.
## What's Next
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
- [WebSDK](https://developer.authologic.com/docs/websdk/overview): Embedding the verification process within your website.
> **Note:** Embedding the verification process within your website is completely optional. Using redirection in your process if
> sufficient and more than enough to start working with Authologic. You can consider it when you would like the process
> to be a part of the web application.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Age Verification [BETA]
Source: https://developer.authologic.com/docs/products/age-verification
Title: Age Verification [BETA]
> **⚠️ BETA Product**: This product is currently in beta. Features and integrations are under active development.
> The API may be subject to changes. Please contact Authologic support for more information about production readiness.
Our Age Verification product is a comprehensive solution designed to verify that users meet specific age requirements
without necessarily revealing their full identity. This product is particularly valuable for businesses operating in
age-restricted industries such as gambling, alcohol sales, tobacco products, adult content, and other regulated sectors
where age compliance is legally mandated.
While using Authologic's Age Verification product, businesses can quickly and accurately confirm whether a user is above
a specified age threshold (e.g., 18, 21, or any custom age requirement). The verification process leverages various
trusted identity providers and verification methods, ensuring both security and user privacy. Our solution supports
multiple verification providers, giving businesses the flexibility to choose the services that best suit their needs
and regional requirements.
The Age Verification product is designed with privacy in mind - it can verify age requirements without necessarily
collecting or storing full personal identity information, making it an ideal solution for scenarios where only age
confirmation is needed. This approach helps businesses maintain compliance while respecting user privacy and minimizing
data collection to only what is necessary.
## Integration
> **Note:** Now that you are familiar with the product you can start the integration process. Chose the integration option by following the
> **API Integration Guide** or the **Java SDK Integration Guide** depending on your use case. You can find the appropriate links
> at the bottom of the page.
Learn how to integrate with Authologic Age Verification product.
- [API Integration Guide](https://developer.authologic.com/docs/products/age-verification/api-integration): Learn how to integrate Authologic Age Verification working directly with the API.
- [Java SDK Integration Guide](https://developer.authologic.com/docs/products/age-verification/java-sdk): Learn how to integrate Authologic Age Verification working with the Java API.
# Age Verification - 5 Minutes Tutorial - Java SDK [BETA]
Source: https://developer.authologic.com/docs/products/age-verification/java-sdk
Title: Java SDK Integration
> **⚠️ BETA Product**: This product is currently in beta. Features and integrations are under active development.
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to verify a user's age. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the age verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies their age
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification
One API for multiple online age verification methods written in Java.
## Installation
The installation of the library is as simple as including it as one of the projects dependencies.
We encourage to use the newest version of the library as we are constantly expanding our product
offering and the underlying functionalities.
### Maven
Include the following dependency in your `pom.xml` file to use Authologic Java SDK:
```xml
com.authologic.client
authologic-client
0.2.48
```
### Gradle
Include the following dependency in your `build.gradle` file to use Authologic Java SDK:
```java
implementation("com.authologic.client:authologic-client:0.2.48")
```
## Usage
The following example demonstrates how you can use the Java SDK to interact with the Authologic APIs for age verification.
### Creating Conversation
To start a new conversation process for age verification, which is the main entry point for the age verification product, the
following example can be used:
```java
import com.authologic.client.api.*;
public class Main {
public static void main(String[] args) {
Client client = ClientBuilder.builder("username", "password").sandbox().build();
Conversation conversation = client.execute(
Requests.
createConversation(
"7dfb9ded-c38f-49ae-95e2-307283a0b1f6",
"https://system.acme.test/return/{conversationId}").
callbackUrl("some_callback_url").
strategy("public:sandbox").
addProduct(ProductQueries.ageVerification(18))
).get();
System.out.println(conversation.getUrl());
}
}
```
#### Creating the Client Instance
We start by creating the Client instance:
```java
Client client = ClientBuilder.builder("username", "password").sandbox().build();
```
API credentials can be generated via OmniPanel.
Because the API is secured you need the provided credentials to be able to interact with it.
Once initialized the `Client` instance may be used to interact with the Authologic API.
#### Creating the Conversation
Next we can create the conversation and request age verification for a specific age threshold. For that purpose we use the `Requests.createConversation()`
using the following code snippet:
```java
Requests.
createConversation().
callbackUrl("some_callback_url").
strategy("public:sandbox").
addProduct(ProductQueries.ageVerification(18))
```
We set:
- the user key
- the return URL
- the callback URL
- the strategy
- the product that we want to use
The **user key** is the field which you can use to provide your own user identification information. Authologic returns this field in the conversation results, but doesn't use the value of the field.
The **return URL** is the address to which the user will be redirected by Authologic after verifying the age. It may contain the fragment: `{conversationId}` - if it exists, it will be replaced with the conversation ID.
The **callback URL** is the URL that Authologic will call when the process, in our example case
the age verification process, will be completed. You should set it to match return to your application or
use a service like [Webhook Site](https://webhook.site/) if you plan on testing the SDK.
The **strategy** is the information that tells Authologic how to perform the operation.
The field is optional, but you can explicitly provide the information to choose the strategy that
you want to use. In the above example we used the `public:sandbox`, a strategy which doesn't perform a
real verification, but allows to test the whole flow.
The product that we want to use is the **Age Verification** product, which allows us to verify if the user meets a specific age requirement. We use `ProductQueries.ageVerification(18)` to verify if the user is over 18 years old:
```java
ProductQueries.ageVerification(18)
```
You can specify any age threshold (e.g., 18, 21, or any custom age requirement).
As the final step we print the URL of the created conversation to the standard output to be able to continue
the process. If you are trying out the SDK head to the returned link to go through the age verification process.
### Fetching Age Verification Results
After the user completes the age verification process, you can retrieve the results using the conversation ID.
The result will contain the status of the verification and whether the user meets the specified age threshold.
```java
import com.authologic.client.api.*;
public class Main {
public static void main(String[] args) {
Client client = ClientBuilder.builder("username", "password").sandbox().build();
String conversationId = "e0c0b3cc-8238-414f-9940-9f14bd1b8693";
Conversation conversation = client.execute(
Requests.getConversation(conversationId)
).get();
ConversationAgeVerificationResult ageVerificationResult =
conversation.getResult().getAgeVerification();
System.out.println("Status: " + ageVerificationResult.getStatus());
System.out.println("Age threshold: " + ageVerificationResult.getOver());
System.out.println("Verification result: " + ageVerificationResult.getResult());
}
}
```
The `ConversationAgeVerificationResult` object contains:
- **status**: The status of the age verification process (`IN_PROGRESS`, `FINISHED`, or `FAILED`)
- **over**: The age threshold that was verified (e.g., 18, 21)
- **result**: A boolean value indicating whether the user meets the age requirement (`true` if the user is over the specified age, `false` otherwise, or `null` if verification is not yet complete)
## What's Next
- [Handling Callbacks](https://developer.authologic.com/docs/integration/callbacks): Handling callbacks using Java SDK.
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Database Verification - 5 Minutes Tutorial - API Integration
Source: https://developer.authologic.com/docs/products/database-verification/api-integration
Title: API Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
> **Note:** We use the `curl` tool to show the API operation.
> If you have not dealt with it, you can find a short guide on it [here](https://www.baeldung.com/curl-rest).
> Of course, there is nothing to prevent you from using the swagger tool directly, which you will find at the
> link: [here](https://developer.authologic.com/api),
> or any other tool, such as Postman or Insomnia.
## Creating a Conversation
To use the Database Verification (DBV) product, create a conversation with the `databaseVerification` query section.
The `databaseVerification` object is optional in its entirety; if provided, it instructs Authologic to run DBV checks on
the
user's identity data collected during the conversation.
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
```shell
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",
"query": {
"identity": {
"requireOneOf": [
["PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]
]
},
"databaseVerification": {
"user": {
"name": {
"firstName": "Jan",
"middleName": "Stanisław",
"lastName": "Kowalski",
"fullName": "Jan Stanisław Kowalski"
},
"ids": {
"nationalId": "12345678901",
"idCard": {
"id": "ABC12343",
"issueDate": "2020-01-15",
"expiryDate": "2030-01-15"
},
"driverLicence": {
"id": "DEF56789",
"issueDate": "2019-03-10",
"expiryDate": "2029-03-10"
},
"passport": {
"id": "GHI98765",
"issueDate": "2021-06-20",
"expiryDate": "2031-06-20"
}
},
"info": {
"gender": "MALE",
"birthDate": "1973-12-12",
"birthPlace": "Gdansk"
},
"address": {
"street": "Cherry Street",
"houseNumber": "133",
"apartmentNumber": "20",
"city": "Warsaw",
"postalCode": "00-950",
"district": "Praga-Polnoc",
"state": "Masovian",
"countryCode": "PL"
},
"contact": {
"email": "test@email.com",
"phone": "123456789",
"landlineNumber": "987654321"
}
}
}
}
}'
```
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).
For `my_callback_url_here` you could use 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*.
- `query.databaseVerification` - enables Database Verification. Source selection is configured per customer account.
Contact us to configure which sources are checked for your account.
- `query.databaseVerification.user`- optional user data to verify against the configured sources. All fields are
optional; provide only the attributes you want to check:
- `name` - `firstName`, `lastName`, `middleName`, `fullName`
- `ids` - `nationalId` and documents (`idCard`, `driverLicence`, `passport`), each document containing
`id`, `issueDate`, `expiryDate` (dates in `YYYY-MM-DD` format)
- `info` - `gender` (`MALE`, `FEMALE`, `OTHER`), `birthDate` (`YYYY-MM-DD`), `birthPlace`
- `address` - `street`, `houseNumber`, `apartmentNumber`, `city`, `postalCode`, `district`, `state`, `countryCode`
- `contact` - `email`, `phone`, `landlineNumber`
If the `user` object is omitted (`"databaseVerification": {}`), the checks run on the identity data collected during
the conversation.
The response to creating a conversation includes a `databaseVerification` status field:
```json
{
"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": {}
},
"databaseVerification": {
"status": "IN_PROGRESS"
}
}
}
```
## Getting the conversation result
After the conversation finishes, the callback or a status poll returns the top-level database verification status.
A detailed report can be obtained by using the dedicated API method described in the next section.
```json
{
"id": "c12c1adc-3ff0-4d32-b95c-c593135c903e",
"status": "FINISHED",
"result": {
"identity": {
"status": "FINISHED",
"user": {
"person": {
"name": {
"firstName": "Jan",
"lastName": "Kowalski"
}
}
}
},
"databaseVerification": {
"status": "FINISHED"
}
}
}
```
`status` values for `databaseVerification`: `IN_PROGRESS`, `FINISHED`, `PARTIAL`, `FAILED`.
## Downloading Database Verification results
Once the conversation has `FINISHED`, retrieve the full per-source match data:
```shell
curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e/databaseVerification/info" \
-H "Accept: application/vnd.authologic.v1.1+json"
```
The response contains one entry per checked source:
```json
{
"source": [
{
"name": "MATCHING",
"status": "FINISHED",
"sourceName": "Australia Residential",
"sourceType": "MARKETING",
"sourceMatchResult": "PARTIAL_MATCH",
"sourceMatchedScores": {
"firstName": 0.95,
"lastName": 0.98
},
"sourceMatchedAttributes": {
"name": {
"firstName": true,
"lastName": true,
"middleName": false,
"fullName": true
},
"ids": {
"nationalId": true,
"taxNumber": true,
"idCard": {
"id": true,
"issueDate": false,
"expiryDate": true,
"additionalId": false,
"version": true,
"canceled": false
}
},
"info": {
"gender": false,
"birthDate": true
},
"address": {
"street": false,
"postalCode": true,
"city": true,
"country": true
},
"contact": {
"email": true,
"phone": false,
"landlineNumber": false
}
},
"errors": []
},
{
"name": "ENRICHMENT",
"status": "FINISHED",
"sourceName": "Poland Registry",
"sourceType": "GOVERNMENT",
"additionalData": {
"name": {
"firstName": "Jan",
"lastName": "Kowalski"
},
"ids": {
"nationalId": "12345678901",
"idCard": {
"isValid": true,
"isCancelled": false
}
},
"info": {
"gender": "MALE",
"birthDate": "1985-01-01"
},
"address": {
"addressLine": "Ul. Przykładowa 1",
"city": "Warszawa",
"postalCode": "00-000",
"state": "Mazowieckie",
"district": "Warszawa",
"country": "PL"
}
}
}
]
}
```
Key fields:
- `name` - use-case type: `MATCHING` (identity matching) or `ENRICHMENT` (data enrichment).
- `status` - source processing result: `FINISHED` or `FAILED`.
- `sourceName` - name of the external database/provider used.
- `sourceType` - category of the source (e.g. `MARKETING`, `GOVERNMENT`).
- `sourceMatchResult` - overall match verdict: `FULL_MATCH`, `PARTIAL_MATCH`, or `NO_MATCH`.
- `sourceMatchedScores` - per-attribute numeric match scores, keyed by attribute name.
- `sourceMatchedAttributes` - per-attribute boolean match results, grouped in sections: `name` (`firstName`,
`lastName`, `middleName`, `fullName`), `ids` (`nationalId`, `taxNumber`, and documents `idCard`/`driverLicence`/
`passport`
with `id`, `issueDate`, `expiryDate`, `additionalId`, `version`, `canceled`), `info` (`gender`, `birthDate`),
`address` (`text`, `addressLine`, `street`, `building`, `flat`, `postalCode`, `city`, `country`, `state`, `district`),
`contact` (`email`, `phone`, `landlineNumber`).
- `additionalData` - additional data returned by enrichment sources (present when `name` is `ENRICHMENT`),
containing sections `name`, `ids` (with `nationalId` and `idCard.isValid`/`idCard.isCancelled`), `info` and `address`.
- `errors` - information about the causes of errors. The content depends on the specific verification source.
Only the attributes actually checked or returned by a given source are present in the response; all of the above
fields are optional.
> **Tip:** You have successfully requested Database Verification and retrieved per-source match results.
## What's Next
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
- [WebSDK](https://developer.authologic.com/docs/websdk/overview): Embedding the verification process within your website.
> **Note:** Embedding the verification process within your website is completely optional. Using redirection in your process if
> sufficient and more than enough to start working with Authologic. You can consider it when you would like the process
> to be a part of the web application.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Database Verification
Source: https://developer.authologic.com/docs/products/database-verification
Title: Database Verification
Description: Our Database Verification (DBV) product supplements Authologic's product offering by verifying user identity data against numerous external databases and data providers.
Our Database Verification (DBV) product supplements Authologic's product offering by verifying user identity data
against numerous external databases and data providers.
## Integration
> **Note:** Now that you are familiar with the product you can start the integration process. Chose the integration option by
> following the **API Integration Guide** or the **Java SDK Integration Guide** depending on your use case. You can find
> the appropriate links
> at the bottom of the page.
Learn how to integrate with Authologic database verification product.
- [API Integration Guide](https://developer.authologic.com/docs/products/database-verification/api-integration): Learn how to integrate Authologic data verification while working directly with the API.
- [Java SDK Integration Guide](https://developer.authologic.com/docs/products/database-verification/java-sdk): Learn how to integrate Authologic data verification while working directly with Java API.
# Database Verification - 5 Minutes Tutorial - Java SDK
Source: https://developer.authologic.com/docs/products/database-verification/java-sdk
Title: Java SDK Integration
## Prerequisites
The following information is required to be able to integrate with Authologic:
- Developer portal credentials,
- API Keys.
### Developer Portal Credentials
The developer portal address and credentials were provided during onboarding.
### Passwords And API Keys
During the onboarding you have received the API keys:
- API key allowing communication with Authologic.
- The key used to verify the data sent by Authologic by the callback mechanism.
## Integration Overview
> **Note:** Authologic provides a simple and effective way to verify a user’s identity. The API process
> involves three key steps: initiating the verification through an external system, redirecting
> the user to the appropriate page, and receiving the verification results.
The entire process is called **conversation**. The following diagram represents the process logical flow:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies himself
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification
One API for multiple online identity verification methods written in Java.
## Installation
The installation of the library is as simple as including it as one of the projects dependencies.
We encourage to use the newest version of the library as we are constantly expanding our product
offering and the underlying functionalities.
### Maven
Include the following dependency in your `pom.xml` file to use Authologic Java SDK:
```xml
com.authologic.client
authologic-client
0.2.48
```
### Gradle
Include the following dependency in your `build.gradle` file to use Authologic Java SDK:
```java
implementation("com.authologic.client:authologic-client:0.2.48")
```
## Usage
The following example demonstrate an example on how you can use the Java SDK to interact with the Authologic APIs.
### Creating Conversation
To start a new conversation process, which is the main entry point for the identity checking product the
following example can be used:
```java
import com.authologic.client.api.*;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
Client client = ClientBuilder.builder("username", "password").sandbox().build();
DatabaseVerificationUserInfo dbvUser =
DatabaseVerificationUserInfo.builder()
.name(
DatabaseVerificationName.builder()
.firstName("Jan")
.lastName("Kowalski")
.build())
.info(
DatabaseVerificationInfo.builder()
.birthDate("1973-12-12")
.build())
.build();
Conversation conversation = client.execute(
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
)).
addProduct(
ProductQueries.databaseVerification(dbvUser)
)
).get();
System.out.println(conversation.getUrl());
}
}
```
> **Note:** The `DatabaseVerificationUserInfo` object can contain more fields than shown in the example - besides `name`
> and `info` it supports `ids` (`nationalId` and `idCard`/`driverLicence`/`passport` documents), `address` and
> `contact` sections. A full example is given below in the [Creating the Conversation](https://developer.authologic.com/#creating-the-conversation)
> section. All fields are optional.
#### Creating the Client Instance
We start by creating the Client instance:
```java
Client client = ClientBuilder.builder("username", "password").sandbox().build();
```
API credentials can be generated via OmniPanel.
Because the API is secured you need the provided credentials to be able to interact with it.
Once initialized the `Client` instance may be used to interact with the Authologic API.
#### Creating the Conversation
Next we can create the conversation and request the first and last name of the person we are
requesting the identification for. For that purpose we use the `Requests.createConversation()`
using the following code snippet:
```java
Requests.
createConversation().
strategy("public:sandbox").
callbackUrl("some_callback_url").
addProduct(
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
)
).
addProduct(
ProductQueries.databaseVerification(
DatabaseVerificationUserInfo.builder()
.name(
DatabaseVerificationName.builder()
.firstName("Jan")
.middleName("Stanisław")
.lastName("Kowalski")
.fullName("Jan Stanisław Kowalski")
.build())
.ids(
DatabaseVerificationIds.builder()
.nationalId("12345678901")
.idCard(
DatabaseVerificationDocument.builder()
.id("ABC12343")
.issueDate("2020-01-15")
.expiryDate("2030-01-15")
.build())
.build())
.info(
DatabaseVerificationInfo.builder()
.gender(DatabaseVerificationGender.MALE)
.birthDate("1973-12-12")
.birthPlace("Gdansk")
.build())
.address(
DatabaseVerificationAddress.builder()
.street("Cherry Street")
.houseNumber("133")
.city("Warsaw")
.postalCode("00-950")
.countryCode("PL")
.build())
.contact(
DatabaseVerificationContact.builder()
.email("test@email.com")
.phone("123456789")
.build())
.build())
)
```
We set:
- the strategy
- the callback URL
- the products that we want to use.
The **strategy** is the information that tells Authologic how to perform the operation.
The field is optional, but you can explicitly provide the information to choose the strategy that
you want to use. In the above example we used the `public:sandbox`, a strategy which doesn't perform a
real verification, but allows to test the whole flow.
The **callback URL** is the URL that Authologic will send the user when the process, in our example case
the identification process, will be completed. You should set it to match return to your application or
use a service like [Webhook Site](https://webhook.site/) if you plan on testing the SDK.
The products that we want to use in this example are the [identity](https://developer.authologic.com/docs/products/identity) product
and the [database verification](https://developer.authologic.com/docs/products/database-verification) product.
For the `identity` product we use the `IdentityProductQueryBuilder` class and provide the list of
fields to retrieve:
```java
new IdentityProductQueryBuilder(
Arrays.asList(
IdentityQueryField.PERSON_NAME_FIRSTNAME,
IdentityQueryField.PERSON_NAME_LASTNAME
)
))
```
For the `databaseVerification` product we use the `ProductQueries.databaseVerification()` method.
Calling it without arguments creates a product that runs checks on the identity data collected during
the conversation. You can also pass a `DatabaseVerificationUserInfo` object to verify the provided
user data against the configured sources - all fields are optional:
```java
addProduct(
ProductQueries.databaseVerification(
DatabaseVerificationUserInfo.builder()
.name(
DatabaseVerificationName.builder()
.firstName("Jan")
.lastName("Kowalski")
.build())
.ids(
DatabaseVerificationIds.builder()
.nationalId("12345678901")
.build())
.info(
DatabaseVerificationInfo.builder()
.birthDate("1973-12-12")
.build())
.address(
DatabaseVerificationAddress.builder()
.city("Warsaw")
.countryCode("PL")
.build())
.contact(
DatabaseVerificationContact.builder()
.email("test@email.com")
.build())
.build())
)
```
As the final step we print the URL of the created conversation to the standard output to be able to continue
the process. If you are trying out the SDK head to the returned link to fill out the data that will be
returned as test data for your identity verification test.
## What's Next
- [Handling Callbacks](https://developer.authologic.com/docs/integration/callbacks): Handling callbacks using Java SDK.
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products): Combining multiple products together in a single request.
- [Testing](https://developer.authologic.com/docs/integration/testing): Learn how to test your integration.
- [Productionize](https://developer.authologic.com/docs/integration/going-live): What to do before going to production.
## Troubleshooting
- [Callbacks](https://developer.authologic.com/docs/integration/use-cases#not-able-to-receive-callbacks): Not being able to receive callbacks.
- [Errors](https://developer.authologic.com/docs/technical/errors): Verification failure reasons.
- [Statuses](https://developer.authologic.com/docs/technical/conversation-statuses): Handling various conversation statuses.
- [FAQ](https://developer.authologic.com/docs/integration/faq): Frequently asked questions.
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations): Deprecated features and options list.
# Products
Source: https://developer.authologic.com/docs/products
Title: Products
- [5 Minutes Tutorial](https://developer.authologic.com/docs/products/5-minutes-tutorial)
- [Identity](https://developer.authologic.com/docs/products/identity)
- [AML](https://developer.authologic.com/docs/products/aml)
- [User Authentication](https://developer.authologic.com/docs/products/user-authentication)
- [Bank Transactions](https://developer.authologic.com/docs/products/bank-transactions)
- [Data Verification](https://developer.authologic.com/docs/products/data-verification)
- [Enquiry](https://developer.authologic.com/docs/products/enquiry)
- [Affordability](https://developer.authologic.com/docs/products/affordability)
- [Age Verification](https://developer.authologic.com/docs/products/age-verification)
- [Database Verification](https://developer.authologic.com/docs/products/database-verification)
# Integration Overview
Source: https://developer.authologic.com/docs/integration/overview
Title: Overview
> **Note:** Authologic allows you to execute a simple and effective verification of the user's identity.
> The use of the API consists of initiating the process by an external system, redirecting the
> user to the appropriate page, and then receiving the verification results.
The entire verification process comes down to three steps:
- Sending to Authologic notification what data you want to get and what products you will use
- Redirecting the user to a unique address returned by Authologic
- Receiving user information via a callback mechanism.
We have called the entire process 'conversation'. In the picture, the process looks like this:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about the address to which the user should be redirected
3. Your system redirects the user's browser to the above URL
4. The user verifies himself
5. Authologic redirects the user's browser to a predefined page of your system
6. Your server displays the return page
7. Authologic calls a callback on your server's side with the result of the verification
> **Tip:** Sometimes Authologic is able to send the verification information before the user is redirected to the
> return page. However, many types of verification require additional time. When creating your system, it
> should be taken into account in the process that the verification result will be available to the user only
> after some time.
There are also products that do not require user interaction. An example may be checking the user in AML
databases based on the data provided by you. In this case, there is no need to redirect the user to the
Authologic website and the process is as follows:
[Diagram: Sequence diagram]
1. Start of the identity verification process. Your server calls the API method called: *POST /api/conversations*
2. The response returns information about conversation identifier and status
3. Authologic calls a callback on your server's side with the result of the verification
# Combining Products
Source: https://developer.authologic.com/docs/integration/combining-products
Title: Combining Products
Description: Authologic API allows you to combine multiple products together. That means that you can start with a single product and expand your integration later without the need of rebuilding everything from scratch.
Authologic API allows you to combine multiple products together. That means that you can start with a single product and
expand your
integration later without the need of rebuilding everything from scratch.
Let's have a look on how we can combine multiple products together, by starting with the simple example of identity
checking, so from
using Authologic identity product ([learn more](https://developer.authologic.com/docs/products/identity)). By now you already know that we should
start by
creating a conversation. We can do that by using the following API call:
> **Note:** The Authologic API uses the `Basic Auth` based authentication described, among others, at
> [here](https://en.wikipedia.org/wiki/Basic_access_authentication). Username and *API key* should be used as data.
> By using the `curl` tool we use the `-u` option which is responsible for the use of `Basic Auth`.
```shell
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": "your_callback_url_here",
"query": {
"identity": {
"requireOneOf": [
[ "PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]
]
}
}
}'
```
In the highlighted lines of the above command you can see that we are using the `identity` product that Authologic
provides. We
can now add the second product, for example the AML one ([learn more](https://developer.authologic.com/docs/products/aml)). We do it by including
additional
section in the `query` part of the above command, for example:
```shell
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": "your_callback_url_here",
"query": {
"identity": {
"requireOneOf": [
[ "PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]
]
},
"aml": {
"checks": ["PEP", "SANCTIONS", "ADVERSE_MEDIA", "SIP", "OTHER"]
}
}
}'
```
You can now see that in addition to the `identity` product we've included the `aml` product. Each of them is configured
separately.
## Description of Sent Data
Currently, the `affordability` product cannot be combined with any existing products in a single conversation.
Each of them must be called in the separate conversations.
# Callbacks
Source: https://developer.authologic.com/docs/integration/callbacks
Title: Callbacks
> **Note:** The purpose of the document is to provide information about the mechanism of informing about events in the system
> in the context of the verification performed. They can also be used to receive other information.
In the basic API, it is possible to query the current conversation status using
the `GET /api/conversations/{conversationId}` method. In practice, the time after which the conversation status will
change
is not strictly defined and depends on the selected verification method and user actions.
Sometimes the verification is immediate, sometimes it takes several minutes and sometimes several days. It can also be
abandoned by the user. Asking for a conversation every specified period of time is not very convenient, if only because
of the
problem with the right choice of this time, which is why Authologic provides a change notification mechanism, the
so-called `callback`.
## Callback Address Declaration
The declaration of the use of this mechanism is simple. When creating a conversation
add the address to which we want to receive notifications via the `callbackUrl` property, e.g .:
```shell
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": "https://authologic.com/tests/callback/?conversation={conversationId}&target={target}&event={event}",
"query": {
"identity": {
"requireOneOf": [
[ "PERSON_NAME_FIRSTNAME", "PERSON_NAME_LASTNAME"]
]
}
}
}'
```
> **Note:** For testing purposes, to check the `callback` request, you can use online tools that accept and present the requests
> that are sent. One such tool is, for example, [Webhook](https://webhook.site/). When creating a conversation,
> it is enough to provide the url generated by Webhook in the `callbackUrl` parameter.
## Description of Sent Data
The server must respond with one of the HTTP statuses: `200`, `201`, `202` or `204`. Otherwise, the notification will
be considered unsuccessful and the system will attempt to resend the information. Such attempts will take place several
times in the increasing time intervals. The first attempt is made immediately after a failed delivery. The number of
attempts depends on various factors and is adjusted automatically, but it is guaranteed that at least 20 attempts will
be made and that the final attempt will occur no sooner than after 4 days.
Thanks to this, in the event of a temporary unavailability, data has a chance to be delivered.
The content of the request is as follows:
```json
{
"id": "02eb1705-fe8f-4d3d-b768-f48b06d26a7e",
"created": "2020-09-17T11:18:21.999Z",
"target": "...",
"event": "...",
"payload": {
"...": {}
}
}
```
Description of individual fields:
| Parameter | Example | Description |
| --------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | 02eb1705-fe8f-4d3d-b768-f48b06d26a7e | Unique identifier for the event. If the event is sent multiple times, the identifier is the same. The receiving system should make a possible omission of duplicates. |
| created | 2020-09-17T11:18:21.999Z | Date when the event occurred. |
| target | CONVERSATION | The object that generated the event. |
| event | FINISHED | The type of the event. |
| payload | | Any objects that describe current specific event. For each type of event `payload` may have a different structure. |
Authologic also sets the following HTTP headers:
| Header | Value |
| --------------------- | ------------------------------ |
| Content-Type | application/json;charset=UTF-8 |
| X-Signature | |
| X-Signature-Timestamp | |
The `X-Signature` and `X-Signature-Timestamp` headers are used to verify the sender of a message and are described later
in this document.
## Event types
The following events are currently available:
| Target | Event | Data available | Description |
| ------------ | --------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CONVERSATION | FINISHED | conversation | Information about the end of the conversation and the verification status. In this case, the `payload` field contains the `conversation` object with details of the completed conversation. |
| CONVERSATION | EXPIRED | conversation | Information about expiration of the conversation. In this case, the `payload` field contains the `conversation` object with details of the completed conversation. |
| SUBSCRIPTION | NEW\_DATA | conversation | Information about new data related to the subscription associated with the conversation. In this case, the `payload` field contains the `conversation` object with updated information about the found AML lists. |
## An Example of a Callback About a Finished Conversation
As soon as the conversation is finished (regardless of the result), Authologic will send information about the status of
the conversation to the specified address using the `POST` method. An example of the call content for the case when the
conversation succeeded in obtaining user data is as follows:
```json
{
"id": "02eb1705-fe8f-4d3d-b768-f48b06d26a7e",
"created": "2020-09-17T11:18:21.999Z",
"target": "CONVERSATION",
"event": "FINISHED",
"payload": {
"conversation": {
"id": "e0c0b3cc-8238-414f-9940-9f14bd1b8693",
"userKey": "d5dbb8e0-192e-4bc6-972c-f7948409d10c",
"url": "https://sandbox.authologic.com/c/c12c1adc-3ff0-4d32-b95c-c593135c903e",
"status": "FINISHED",
"result": {
"identity": {
"status": "FINISHED",
"user": {
"person": {
"name": {
"firstName": "Jan",
"lastName": "Testowy"
}
}
}
}
}
}
}
}
```
> **Note:** As a best practice, we recommend implementing your system to handle callback payloads that may include
> additional fields not known during development. You may choose to ignore these extra fields, but we strongly
> advise against overly strict parsing of the callback payload body.
The content of the `payload.conversation` field is analogous to the response with conversation details.
> **Warning:** The server must respond with one of the HTTP statuses: `200`, `201`, `202` or `204`. Otherwise,
> the notification will be considered unsuccessful and will attempt to resend the information.
> Such attempts will take place several times in the growing recesses of time. Thanks to this,
> in the event of a temporary unavailability, data has a chance to be delivered.
> **Note:** If it gets different values of `target` and `event`, the system should accept a callback,
> responding with HTTP status `200`, `201`, `202` or `204` and then ignore it. Thanks to this, the system will
> be resistant to possible events implemented in the future.
> **Note:** In some cases, Authologic will be able to send an update after acquiring some data. For example,
> a conversation in which you asked for user verification and for downloading of user's banking
> transactions. Authologic may then send one notification: after finishing the conversation, it can
> also send two: one after getting user data and the other after preparing the transaction data. It's
> up to you to decide whether to process both information independently or to wait on the second, final call,
> where the `status` field is` FINISHED`.
> #### 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.
The use in the address `{conversationId}`, `{target}` and `{event}` is optional and, if present, will be
replaced with the conversation ID, the name of the event generating object and the event type, respectively.
## Verification of the Message Sender
When receiving a callback, you should make sure that its content is from Authologic and has not been tampered with by
anyone.
For this purpose, we provide a sender verification mechanism. The sender should be verified using the contents of the
HTTP
headers named `X-Signature` and` X-Signature-Timestamp` and the signature key provided by Authologic.
The verification algorithm is as follows:
1. Check that the timestamp given in the HTTP header `X-Signature-Timestamp` does not differ from the current one by
more than 5 minutes. Timestamp is presented as a number of milliseconds since UNIX epoch (January 1, 1970 00:00:00
UTC)
2. Execution of the cryptographic hash function `HMAC_SHA_256` on the string built according to the scheme:
`:`. The signature key provided by Authologic must be used as the key.
3. Compare `X-Signature` with the result
### Example
The following example may be useful to test the signing algorithm:
- Signature key: `dey6TaePhiogi7ohgiek0pho`
- Timestamp: `1641046369772`
- Query content (note the whitespaces): `{ "test": true }`
- SHA256 is calculated with the inscription: `1641046369772:{ "test": true }`
- Generated signature: `fb96c41afe39c6b1cb9377a63405f9f072c1ccf2f04b85fcaeda2c081dcabba6`
### Potential Problems with the Signature
In case of problems, make sure that:
- You are using a specially designed key signature verification and not e.g. API key.
- Make sure that the content of the query is not changed by the framework you are using: e.g. JSON is not formatted.
- Check that the content of the query is treated by you as UTF-8.
## Callback forward compatibility testing
In order to test the forward compatibility of the callback, you should:
1. Make sure callback processing mechanism is prepared to receive a callback with a payload that contains additional
fields not described in the current version of the API.
2. Make sure all unknown fields in the callback payload are ignored.
> **Warning:** The integration verification procedure involves simulating a callback notification with random fields in the payload.
> The presence of random fields should not cause any issues with receiving the callback notification.
# Use Cases
Source: https://developer.authologic.com/docs/integration/use-cases
Title: Use Cases
Description: The following page contains common question and use cases description.
The following page contains common question and use cases description.
## Not Able to Receive Callbacks
By default, when creating conversation you can provide the `callbackUrl`, which is the URL that will be used to send you the
result of conversation. We know that receiving traffic from the outside world is not always possible and that's why we provide
the option to manually check the conversation status.
> **Caution:** Though possible we strongly advice against periodic manual status check of the conversation status. Depending on the
> product that you are using the time between the conversation creation and the results being available may be long - for
> example when your conversation depend on manual verification by the provider. You need to keep that in mind.
>
> We try to help our users as much as we can, but in extreme cases of the API abuse we may cut off the access to the
> discussed API.
Regardless of that, if you need to check conversation status (for example during test, for debug purposes) you can
ask about its condition at any time, using the method below.
Remember to adapt the conversation id in the address to your case:
```shell
curl -u my_login "https://sandbox.authologic.com/api/conversations/c12c1adc-3ff0-4d32-b95c-c593135c903e" \
-H "Accept: application/vnd.authologic.v1.1+json" \
-H "Content-Type: application/vnd.authologic.v1.1+json"
```
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).
Assuming that you have finished the process, you should expect following response:
```json
{
"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"
}
}
}
}
}
}
```
# Frequently Asked Questions
Source: https://developer.authologic.com/docs/integration/faq
Title: Frequently Asked Questions
### FAQ: Frequently Asked Questions
The common question asked by our users that can help with your integration process.
#### Identity Verification Process Translation
Language of the pages of the identity verification process is based on the user's preferences defined by browser
language. It is possible to force a different language by modifying the URL to which the user is redirected after
creating the conversation. The change consists in adding the `lang` parameter.
```html
https://id.sandbox.authologic.com/c/00c11274-607b-408a-ad8e-de95b88bb5fa?lang=en
```
#### What Is the Purpose of the Various Integration Keys I Received
During the onboarding process you may have received various keys that have different purpose:
- **API Key** - Authologic APIs are protected, you received the API key to be able to access the APIs and integrate with Authologic.
- **Sign Key** - The key used by Authologic to sign the communication received via webhooks when the [callback](https://developer.authologic.com/docs/integration/callbacks) is sent.
- **Widget ID** - The value of the widget used for integration using the [WebSDK](https://developer.authologic.com/docs/websdk/overview)
#### Converting Conversation URL to QR Code
You can convert the conversation URL into a QR code for easy mobile access. Users can then scan the code with their
mobile device to start the verification process.
When creating a conversation, you'll receive a conversation URL that can be converted to a QR code and displayed to
users. Use the QRCode JS library to generate the QR code. For example, if your conversation identifier
is `aeb17bfe-9bbe-4e63-ab6a-902a12bd3b71`, you could create a page like this:
```html
Simple QR Generator
```
#### Additional Resources
- [Mandatory and Optional Fields](https://developer.authologic.com/docs/technical/mandatory-and-optional-queries): When to use query.requireOneOf and query.optional options when creating the conversation.
- [Changing Appearance](https://developer.authologic.com/docs/additional/custom-layout): Options available for customizing the user interface such as logos and colors.
- [Checking Conversation Status](https://developer.authologic.com/docs/technical/conversation-statuses): The conversation statuses description, their life cycle along with the examples.
- [Media Types](https://developer.authologic.com/docs/integration/media-types-per-provider): Potential media types returned by different providers depending on the verification process documents.
# Strategy Testing Information
Source: https://developer.authologic.com/docs/integration/testing
Title: Testing
Description: Authologic provides many integrations of different types and features. How these integrations are tested depends on the capabilities provided by each vendor.
Authologic provides many integrations of different types and features. How these integrations are tested depends on the
capabilities provided by each vendor.
Usually during development, the best practice is to use `public:sandbox`. It allows you to conveniently determine the
results of a given verification, which facilitates integration and testing of individual cases.
However, sometimes it is necessary to see what the full process will look like. If the provider includes such a
possibility, it is also made available by Authologic.
However, some suppliers do not allow testing or such testing is difficult or limited. Below is a list of such cases:
| Vendor | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| eDO App | Access to this functionality is closed due to technical limitations. Verification requires a test application and a test document in the form of a plastic card. |
| Contacts | Verification of the phone number and email address in the test version does not send SMS/email and the code is fixed. |
| MojeID | Access to this functionality is closed due to technical limitations. The provider only provides a low-level simulator requiring knowledge of the communication protocol. In practice, this provides a subset of the capabilities of the `public:sandbox` strategy. |
When testing PSD2 based strategies, some providers offer test accounts, see the following table:
| Vendor | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Kontomatik | Select 'Konto Bank' and check [Test accounts](https://developer.kontomatik.com/coverage?resource=test-accounts) . |
# Production Launch
Source: https://developer.authologic.com/docs/integration/going-live
Title: Going Live
Description: The best place to safely test the Authologic system capabilities and integrate with your system is the test environment https://sandbox.authologic.com/.
The best place to safely test the Authologic system capabilities and integrate with your system is the test
environment .
At some point, you will want to provide a system to our target users. Contact us, we will copy
your configuration to the production environment. The only things you will need to change are:
- API address: changes to the one provided to you.
- API key
- The signature verification key used by the `callback mechanism`
> **Note:** The test environment will stay still available for further tests or changes to your integration.
# Unsupported and Deprecated Functions
Source: https://developer.authologic.com/docs/integration/deprecations
Title: Deprecations
Description: Information about functionalities that will be removed and may require updating your system.
Information about functionalities that will be removed and may require updating your system.
## Currently, we do not have any upcoming changes requiring implementation in your system.
## Recently removed features
Discontinued necessity of using `identity` product with aml verification without KYC
## Support has ended
1. Conversation creation with an AML product without KYC no longer requires the `query.identity` section.
2. Discontinued using `accounts.iban` attribute in API
3. Removed parameter `person.ids.accounts.iban` in conversation result data set. Account identifier should be obtained from `person.ids.accounts.accountId`.
4. Discontinued functionality to provide an account `accounts.iban` identifier for data verification product. The account identifier should be provided by `verify.user.ids.accounts.accountId` attribute.
# Media Types per Provider
Source: https://developer.authologic.com/docs/integration/media-types-per-provider
Title: Media Types per Provider
Description: Authologic uses various providers to ensure stability, flexibility and wide variety of features to our customers. However, various providers support different media types when providing the verification functionalities. The following document provides information what kind of media types you may expect depending on the provider being used.
Authologic uses various providers to ensure stability, flexibility and wide variety of features
to our customers. However, various providers support different media types when providing the
verification functionalities. The following document provides information what kind of media types
you may expect depending on the provider being used.
Currently, the following providers are mentioned:
- [Onfido](https://developer.authologic.com/#onfido)
- [Idenfy](https://developer.authologic.com/#idenfy)
- [SumSub](https://developer.authologic.com/#sumsub)
- [IdWIse](https://developer.authologic.com/#idwise)
## Onfido
The following media types are expected to be present when working with Onfido provider:
- `application/pdf` - expected when working with ID card, passport, residence permit.
- `image/jpg` - expected when working with ID card, passport, residence permit.
- `image/jpeg` - expected when working with ID card, passport, residence permit.
- `image/png` - expected when working with ID card, passport, residence permit or liveness check.
- `video/mp4` - expected when working with liveness check.
- `video/webm` - expected when working with liveness check.
## Idenfy
The following media types are expected to be present when working with Idenfy provider:
- `image/png` - expected when working with ID card, passport, driving license, residence permit or liveness check.
- `video/mp4` - expected when working with ID card, passport, driving license, residence permit or liveness check.
## SumSub
The following media types are expected to be present when working with SumSub provider:
- `image/jpeg` - expected when working with ID card, passport, residence permit or liveness check.
- `image/png` - expected when working with ID card, passport, residence permit or liveness check.
- `video/mp4` - expected when working with liveness check.
## IdWIse
The following media types are expected to be present when working with IdWIse provider:
- `image/jpeg` - expected when working with ID card, passport, driving license, residence permit, POA or liveness check.
# Callbacks
Source: https://developer.authologic.com/docs/integration/callbacks-java
Title: Callbacks
> **Note:** The purpose of the document is to provide information about the mechanism of informing about events in the system
> in the context of the verification performed. They can also be used to receive other information, which you can learn
> about [here](https://developer.authologic.com/docs/integration/callbacks).
### Working with Callbacks
> **Note:** Please remember that when working with callbacks you not only need the `authologic-client` library,
> but also `authologic-client-json` and one of the JSON parsing modules, for example the
> `authologic-client-module-jackson`.
The Java SDK can also be used to parse the information sent to your callback URL. It is as simple as initializing one
of the JSON parsing engines, deserializing the body of the request received in the callback and using the result data.
For example this is how the code could look like:
```java
JsonEngine jsonEngine = (new JacksonJsonEngineProvider()).createJsonEngine();
Callback callback = jsonEngine.deserialize(callbackBody, Callback.class);
if (callback.isConversationFinished()) {
Conversation conversation = callback.asConversationFinished().getConversation();
PersonName personName = conversation.getResult().getIdentity().getUser().getPerson().getName();
System.out.println("Person: " + personName.getFirstName() + ", " + personName.getLastName());
}
```
Let's discuss the above example.
#### Initializing JSON Parser
We start by initializing the JSON parser, so we can easily parse the response.
We do it only once as the parser is thread-safe and can be reused later when needed:
```java
JsonEngine jsonEngine = (new JacksonJsonEngineProvider()).createJsonEngine();
```
#### Deserializing the Results
We assume that we got the callback body and stored in the `callbackBody` variable. Once we have it
we can easily deserialize it to the `CallbackResult` class using the initialized JSON parser:
```java
Callback callbackResult = jsonEngine.deserialize(ctx.body(), Callback.class);
```
The abstract Callback class provides two methods to identify the type of the result:
- the `isConversationFinished` returning `true` if the result is of type `Conversation` representing conversation
- the `isUnknownCallback` returning `true` if the result is of type `UnknownCallback` representing unknown callback
In the example code we expect the `FinishedConversationCallback`, so we check for it:
```java
if (callback.isConversationFinished()) {
```
After we verified that we got the class we were expecting we can retrieve the conversation from the
deserialized object and print out the identified person first and second name:
```java
Conversation conversation = callback.asConversationFinished().getConversation();
PersonName personName = conversation.getResult().getIdentity().getUser().getPerson().getName();
System.out.println("Person: " + personName.getFirstName() + ", " + personName.getLastName());
```
> **Warning:** Please remember that your code that handles the callback should return code 200 in response to the request
> coming from Authologic, otherwise the callback will be repeated.
#### Full Result using Javelin
A full, working example using [Javalin](https://javalin.io/), a simple web framework for Java and Kotlin
looks as follows:
```java
import com.authologic.client.api.*;
import com.authologic.client.json.JacksonJsonEngineProvider;
import io.javalin.Javalin;
import java.util.Arrays;
public class Main {
public static void main(String[] args) {
JacksonJsonEngine jsonEngine = (new JacksonJsonEngineProvider()).createJsonEngine();
Javalin app = Javalin.create()
.post("/", ctx -> {
Callback callback = jsonEngine.deserialize(ctx.body(), Callback.class);
if (callback.isConversationFinished()) {
Conversation conversation = callback.asConversationFinished().getConversation();
PersonName personName = conversation.getResult().getIdentity().getUser().getPerson().getName();
System.out.println("Person: " + personName.getFirstName() + ", " + personName.getLastName());
}
ctx.status(HttpStatus.OK);
})
.start(8080);
}
}
```
# Custom Integration
Source: https://developer.authologic.com/docs/integration/custom-integration-support
Title: Custom Integration
Description: The following page contains description of integration where UI is generated and supported on your side.
The following page contains description of integration where UI is generated and supported on your side.
> **Caution:** This type of integration should be considered only if you are unable to use UI provided by Authologic.
> Only specific verification flows are supported. Access to this type of integration requires specific configuration on
> our side,
> so the entire process must be discussed, guided and reviewed by our team.
>
> We strongly recommend to use our main solution.
Regardless, if you want to directly connect the verification process to your existing user interface,
we have prepared additional API endpoints to help you do so.
**All previous information regarding the integration process as login, callbacks, etc. remains in effect.**
**It is also necessary to set the header `X-User-IP` with the IP address of the user to whom the page will be shown. Of
course, the `Accept`, `Content-Type` and `Authorization` headers should also be set in the same way as for other API
methods.**
### Current Step
The first endpoint informs about the current step in the verification process and describes what to do next.
```shell
curl -u my_login "https://sandbox.authologic.com/api/conversations/{conversationId}/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"
```
In response, Authologic returns information in the following format:
```json
{
"component": "currentComponent",
"next": "nextStepIdentifier",
"args": {
"argName": "argValue"
}
}
```
Detailed description of the returned attributes:
| Parameter | Example | Description |
| --------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| component | SMART\_ID/SHOW\_CODE | Name of method related with current step and expected action related to UI in verification process. |
| next | fd78cf43-12a7... | Id of the page to which the user information should be submitted. Information is sent via the method `POST /api/conversations/{conversationId}/headless/{next}`. |
| args | parameter name list | List of parameters that should be displayed to the user. |
### Collecting Data And Calling The Next Step
The second endpoint is designed to trigger actions in the process based on the provided information.
```shell
curl -X POST -u my_login "https://sandbox.authologic.com/api/conversations/{conversationId}/headless/{next}" \
-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":{...}}"
```
Expected payload contains only attributes required in next verification step and is very simple:
```json
{
"args": {
"argName1": "arg1Value",
"argName2": "arg2Value"
}
}
```
**Parameters required in this call are dependent on a specific verification process.
List of parameters will be included in separate description for a given process.**
In response, Authologic returns information in the following format:
1. In case request contains errors:
```json
{
"component": "currentComponent",
"next": "nextStepIdentifier",
"args": {
"argName": "argValue"
},
"errors": [
{
"field": "argName1",
"code": "errorCode"
}
]
}
```
2. In case interaction with process is finished:
```json
{
"component": "GLOBAL/ACCEPTED"
}
```
Detailed description of the returned attributes:
| Parameter | Example | Description |
| ------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| component | GLOBAL/ACCEPTED | Name of method related with current step and expected action related to UI in verification process. |
| next | fd78cf43-12a7... | Id of the page to which the user information should be submitted. Information is sent via the method `POST /api/conversations/{conversationId}/headless/{next}`. |
| args | parameter name list | List of parameters that should be displayed to the user. |
| errors | map with field name and error description | A map specifying incorrectly entered form fields and a description of the associated error. |
| errors.field | parameter name sent in `body` attribute, validated and marked as incorrect | Value specifying incorrectly entered form field. |
| errors.code | error code related to the field described in `errors.field` attribute | Value describing the error associated to the form field. |
**Individual endpoint calls may require sending specific values to the process in the form of an attribute map sent in
the request payload.**
Assuming that you have finished interaction with the process, you should expect following response:
```json
{
"component": "GLOBAL/ACCEPTED"
}
```
> **Tip:** Be careful each verification process and each step is different.
>
> A clear description of the subsequent service calls will be provided once the entire process has been agreed with the
> Authologic team.
# Integrations
Source: https://developer.authologic.com/docs/integration
Title: Integrations
- [Overview](https://developer.authologic.com/docs/integration/overview)
- [Combining Products](https://developer.authologic.com/docs/integration/combining-products)
- [Callbacks](https://developer.authologic.com/docs/integration/callbacks)
- [Use Cases](https://developer.authologic.com/docs/integration/use-cases)
- [Faq](https://developer.authologic.com/docs/integration/faq)
- [Testing](https://developer.authologic.com/docs/integration/testing)
- [Going Live](https://developer.authologic.com/docs/integration/going-live)
- [Deprecations](https://developer.authologic.com/docs/integration/deprecations)
- [Media Types Per Provider](https://developer.authologic.com/docs/integration/media-types-per-provider)
- [Callbacks Java](https://developer.authologic.com/docs/integration/callbacks-java)
- [Custom Integration Support](https://developer.authologic.com/docs/integration/custom-integration-support)
- [User Info Fields](https://developer.authologic.com/docs/integration/user-info-fields)
# Available User Information
Source: https://developer.authologic.com/docs/integration/user-info-fields
Title: Available User Information
Description: Authologic currently supports the following user data:
Authologic currently supports the following user data:
> **Note:** The returned data depends on the verification method selected by the user in the process. The list of available fields
> can be found in the OmniPanel developer section.
- `PERSON_NAME_FIRSTNAME` - user's first name
- `PERSON_NAME_LASTNAME` - user's last name
- `PERSON_NAME_MIDDLE_INITIAL` - middle name initial
- `PERSON_NAME_MIDDLENAME` - middle name
- `PERSON_NAME_FULLNAME` - full name of the user (available for specific verification methods, in which the user's first
and last names are possible to be retrieved)
- `PERSON_NAME_MOTHER_NAME` - mother's name
- `PERSON_NAME_FATHER_NAME` - father's name
- `PERSON_NAME_SPELLING` - full name (alias, alternative notation, translation, transliteration)
- `PERSON_IDS_NATIONAL_ID` - Social security number (in Poland: PESEL)
- `PERSON_IDS_IDCARD_ID` - identity card number
- `PERSON_IDS_IDCARD_ISSUE_DATE` - date of issue of identity card
- `PERSON_IDS_IDCARD_EXPIRY_DATE` - the expiry date of the identity card
- `PERSON_IDS_IDCARD_PHOTO` - picture ID card
- `PERSON_IDS_IDCARD_ISSUE_COUNTRY` - the country issuing the ID card
- `PERSON_IDS_IDCARD_ISSUER` - authority issuing the ID card
- `PERSON_IDS_PASSPORT_ID` - passport number
- `PERSON_IDS_PASSPORT_ISSUE_DATE` - date passport issue
- `PERSON_IDS_PASSPORT_EXPIRY_DATE` - passport expiry date
- `PERSON_IDS_PASSPORT_PHOTO` - passport photo
- `PERSON_IDS_PASSPORT_ISSUE_COUNTRY` - passport issue country
- `PERSON_IDS_PASSPORT_ISSUER` - authority issuing the passport
- `PERSON_IDS_DRIVER_LICENCE_ID` - Driving license number
- `PERSON_IDS_DRIVER_LICENCE_ISSUE_DATE` - the date of issue of the license
- `PERSON_IDS_DRIVER_LICENCE_EXPIRY_DATE` - the date of expiry of the license
- `PERSON_IDS_DRIVER_LICENCE_ISSUE_COUNTRY` - the country of issue of the license
- `PERSON_IDS_DRIVER_LICENCE_ISSUER` - authority issuing the license
- `PERSON_IDS_DRIVER_LICENCE_ISSUE_STATE` - the state/province of issue of the license
- `PERSON_IDS_DRIVER_LICENCE_ADDITIONAL_ID` - additional identifier used for driving licenses
- `PERSON_IDS_DRIVER_LICENCE_LIMITATIONS` - list of driving limitations
- `PERSON_IDS_DRIVER_LICENCE_DOCUMENT_STATUS` - driving license document status
- `PERSON_IDS_DRIVER_LICENCE_CATEGORIES` - information about all categories that user has with additional information,
such as category name, the date of issue of the category, the date of expiry of the category, limitation/restrictions
related to a given category, status of the category
- `PERSON_IDS_RESIDENCE_PERMIT_ID` - card number stay
- `PERSON_IDS_RESIDENCE_PERMIT_ISSUE_DATE` - the date of issue of the stay
- `PERSON_IDS_RESIDENCE_PERMIT_EXPIRY_DATE` - expiry date of the residence card
- `PERSON_IDS_RESIDENCE_PERMIT_ISSUE_COUNTRY` - the country issuing the residence card
- `PERSON_IDS_RESIDENCE_PERMIT_ISSUER` - authority issuing the residence card
- `PERSON_IDS_OTHER_DOCUMENT_ID` - number of the document (available for specific methods of verification)
- `PERSON_IDS_OTHER_DOCUMENT_DESCRIPTION` - description of the type of document (available for specific verification
methods)
- `PERSON_IDS_OTHER_DOCUMENT_ISSUE_DATE` - the date of issue of the document (available for specific methods of
verification)
- `PERSON_IDS_OTHER_DOCUMENT_EXPIRY_DATE` - document expiry date (available for specific verification methods)
- `PERSON_IDS_OTHER_DOCUMENT_ISSUE_COUNTRY` - the country issuing the document (available for specific methods of
verification)
- `PERSON_IDS_OTHER_DOCUMENT_ISSUER` - authority issuing the document
- `PERSON_IDS_OTHER_DOCUMENT_PHOTO` - photo from the document
- `PERSON_IDS_ACCOUNTS` - bank account information User
- `PERSON_INFO_GENDER` - gender of the user
- `PERSON_INFO_NATIONALITY` - nationality
- `PERSON_INFO_BIRTHDATE` - date of birth
- `PERSON_INFO_BIRTH_CITY` - place of birth
- `PERSON_INFO_BIRTH_COUNTRY` - country of birth
- `PERSON_INFO_FOREIGNER_STATUS` - foreigner status
- `PERSON_INFO_AGE` - age
- `PERSON_ADDRESS` - address of the user
- `PERSON_CONTACT_EMAIL` - user's email
- `PERSON_CONTACT_PHONE` - user's phone
- `COMPANY_NAME_NAME` - company name
- `COMPANY_IDS_TAX_ID` - tax ID (in Poland: NIP)
- `COMPANY_ADDRESS` - company address
- `COMPANY_CONTACT_EMAIL` - company email
- `COMPANY_CONTACT_PHONE` - company phone
- `COMPANY_IDS_ADDITIONAL_ID` - alternative company identifier (e.g. in Poland: REGON)
# Advanced Integration: Embed the Process Into Your Own Pages
Source: https://developer.authologic.com/docs/omni-websdk/overview
Title: Overview
Description: The basic version of integration involves redirecting the user to the address returned by the conversation creation API. This solution is simple, effective, and does not require additional integration work beyond defining the page to which the user will be redirected after the process is completed.
The basic version of integration involves redirecting the user to the address returned by the conversation creation API.
This solution is simple, effective, and does not require additional integration work beyond defining the page to which
the user will be redirected after the process is completed.
Authologic also provides the option to embed the verification process within your website. Unlike simple redirection,
this solution requires you to take into account the following:
- this type of integration requires additional work,
- including the process within your website may require rebuilding the navigation,
- it should be taken into account that some verification methods require opening their own window,
- the webSDK code should be systematically updated
> **Warning:** Sites using WebSDK must be registered with Authologic. After providing Authologic with the website address,
> you will receive the widget ID (`widgetId`) necessary to run the integration. An invalid **widget ID** will result
> in a browser [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) error. For testing purposes you can
> use `development_only` as the value of the `widgetId`. It will disable security and will only work in
> the **sandbox environment**.
> **Warning:** Conversation creation should also set the `layoutUrl` field pointing to the page where the webSDK is embedded.
> Sometimes, there is a need to move process to another site and after the process is completed, Authologic must know
> where to redirect the user.
Unlike old WebSDK, OmniID WebSDK is a single, framework-agnostic package: the same integration works whether
your frontend is plain JavaScript, React, Vue, or Angular, so there is no separate integration guide per technology.
## Install
```bash
# npm
npm install @authologic/omni-websdk
# yarn
yarn add @authologic/omni-websdk
# pnpm
pnpm add @authologic/omni-websdk
# bun
bun add @authologic/omni-websdk
```
## Quick Start
```html
```
```ts
import { init } from "@authologic/omni-websdk";
init({
widgetId: "your-widget-id",
conversationId: "conversation-id-from-your-backend",
environment: "sandbox",
});
```
The widget mounts into `#authologic` and opens in a modal.
For the full API reference — configuration options, lifecycle hooks, appearance theming, and error handling — see
the package page on npm: [`@authologic/omni-websdk`](https://www.npmjs.com/package/@authologic/omni-websdk).
# Advanced Integration: Embed the Process Into Your Own Pages
Source: https://developer.authologic.com/docs/websdk/overview
Title: Overview
> **Warning:** This WebSDK will become unavailable on December 31, 2027. To ensure uninterrupted
> service, you must move all checks from this WebSDK to OmniID WebSDK. If you need
> help, reach out to us or contact the Authologic Team.
>
> See [OmniID WebSDK](https://developer.authologic.com/docs/omni-websdk/overview) for the current integration.
The basic version of integration involves redirecting the user to the address returned by the conversation creation API.
This solution is simple, effective, and does not require additional integration work beyond defining the page to which
the user will be redirected after the process is completed.
Authologic also provides the option to embed the verification process within your website. Unlike simple redirection,
this solution requires you to take into account the following:
- this type of integration requires additional work,
- including the process within your website may require rebuilding the navigation,
- it should be taken into account that some verification methods require opening their own window,
- the webSDK code should be systematically updated
> **Warning:** Sites using WebSDK must be registered with Authologic. After providing Authologic with the website address,
> you will receive the widget ID (`widgetId`) necessary to run the integration. An invalid **widget ID** will result
> in a browser [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) error. For testing purposes you can
> use `development_only` as the value of the `widgetId`. It will disable security and will only work in
> the **sandbox environment**.
> **Warning:** Conversation creation should also set the `layoutUrl` field pointing to the page where the webSDK is embedded.
> Sometimes, there is a need to move process to another site and after the process is completed, Authologic must know
> where to redirect the user.
Integration may look slightly different depending on the technologies you use:
- [Javascript](https://developer.authologic.com/docs/websdk/js): Integration directly into JavaScript.
- [React](https://developer.authologic.com/docs/websdk/react): Integration within React applications.
- [Vue.js](https://developer.authologic.com/docs/websdk/vuejs): Integration within the VueJS application.
- [Angular](https://developer.authologic.com/docs/websdk/angular): Integration within the Angular application.
# JavaScript Integration
Source: https://developer.authologic.com/docs/websdk/js
Title: JavaScript
> **Warning:** This WebSDK will become unavailable on December 31, 2027. To ensure uninterrupted
> service, you must move all checks from this WebSDK to OmniID WebSDK. If you need
> help, reach out to us or contact the Authologic Team.
>
> See [OmniID WebSDK](https://developer.authologic.com/docs/omni-websdk/overview) for the current integration.
In case you are not using any build mechanism, you can attach the script directly to the HTML page:
```html
```
Within the page, you need to define the place where the process should be displayed:
```html
```
At the end of the page, before the end of the `` tag, a script call should be placed in the `