# Database Verification - 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.

<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](/api),
or any other tool, such as Postman or Insomnia.

</note>

## 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`.

</note>

```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": {}
    }
}'
```

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*.

- `query.databaseVerification` ? enables Database Verification. The object is currently empty; source selection is configured
per customer account. Contact us to configure which sources are checked for your account.

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": "FULL_MATCH",
      "errors": []
    }
  ]
}
```

Key fields:

- `name` ? use-case type: `MATCHING` (identity matching).
- `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`.

<tip>

You have successfully requested Database Verification and retrieved per-source match results.

</tip>

## What's Next

<card-group>
<card title="Combining Products" to="/docs/integration/combining-products">

Combining multiple products together in a single request.

</card>

<card title="Testing" to="/docs/integration/testing">

Learn how to test your integration.

</card>

<card title="Productionize" to="/docs/integration/going-live">

What to do before going to production.

</card>

<card title="WebSDK" to="/docs/websdk/overview">

Embedding the verification process within your website.

</card>
</card-group>

<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.

</note>

## Troubleshooting

<card-group>
<card title="Callbacks" to="/docs/integration/use-cases#not-able-to-receive-callbacks">

Not being able to receive callbacks.

</card>

<card title="Errors" to="/docs/technical/errors">

Verification failure reasons.

</card>

<card title="Statuses" to="/docs/technical/conversation-statuses">

Handling various conversation statuses.

</card>

<card title="FAQ" to="/docs/integration/faq">

Frequently asked questions.

</card>

<card title="Deprecations" to="/docs/integration/deprecations">

Deprecated features and options list.

</card>
</card-group>

<note>

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)

</note>