# Affordability assessment - 5 Minutes Tutorial - 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
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:
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
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](/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.
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 [https://webhook.site/](https://webhook.site/) 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.
We set the default strategy together when setting up an account. If you need to change it, please contact us.
A list of the available strategies assigned to your account can be found on the main page of the customer portal.
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`
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"
}
},
...
]
}
```
That's it. You managed to use API and get data.
## What's Next
Combining multiple products together in a single request.
Learn how to test your integration.
What to do before going to production.
Embedding the verification process within your website.
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
Detailed description of the affordability assessment data retrieval.
## Troubleshooting
Not being able to receive callbacks.
Verification failure reasons.
Handling various conversation statuses.
Frequently asked questions.
Deprecated features and options list.
Despite our sincere intentions, it is difficult to create perfect technical documentation.
If you have an idea on how to improve this documentation, or you have trouble understanding any section,
please email us at [tech-support@authologic.com](mailto:tech-support@authologic.com)