# API Reference

## Request Identity Verification

<mark style="color:blue;">`GET`</mark> `https://api.app.authenteq.com/web-idv/verification-url`

This endpoint returns a URL that leads to Authenteq Identity Server.\
\
This endpoint is authorized with Basic Auth. You should use your `Client ID` and `Client Secret` from the Customer Dashboard as the credentials.

#### Query Parameters

| Name                                          | Type   | Description                                                                 |
| --------------------------------------------- | ------ | --------------------------------------------------------------------------- |
| redirectUrl<mark style="color:red;">\*</mark> | string | One of your registered redirect URLs that will be used to receive the code. |

#### Headers

| Name                   | Type   | Description                                                                                                                                             |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization          | string | Your client credentials combined with a colon separator, base64-encoded and prefixed with "Basic ".                                                     |
| AQ-Multi-Document-Flow | string | The "On" value turns on use of the multi-document flow for the requested identity verification. By default, it's turned off for backward compatibility. |
| AQ-Flow-Slug           | string | The Flow ID of the verification flow that should be used for the verification. If not present the default flow will be used.                            |

{% tabs %}
{% tab title="200 The verification session requested successfully. Your user should follow the verification URL to begin the identity process." %}

```
{
  "verificationUrl": "https://web-idv.app.authenteq.com/verify?token=<token>"
}
```

{% endtab %}

{% tab title="400 The request contains an invalid data." %}
{% tabs %}
{% tab title="Missing Redirect URL" %}

```
{
  "errorCode": "MISSING_REQUEST_PARAMETER",
  "errorMessage": "Required 'redirectUrl' parameter is missing"
}
```

{% endtab %}

{% tab title="Redirect URL mismatch" %}

```
{
  "errorCode": "INVALID_REQUEST_PARAMETER",
  "errorMessage": "Parameter 'redirectUrl' does not match any registered one"
}
```

{% endtab %}

{% tab title="No redirect URLs" %}

```
{
  "errorCode": "NO_REDIRECT_URLS",
  "errorMessage": "No registered redirect URLs. Please specify at least one in Customer Dashboard"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401 Full authentication is required to get a verification URL." %}
{% tabs %}
{% tab title="Missing API Keys" %}

```
{
  "errorCode": "API_KEYS_MISSING",
  "errorMessage": "No API Keys in the Authorization header"
}
```

{% endtab %}

{% tab title="Invalid API Keys" %}

```
{
  "errorCode": "API_KEYS_INVALID",
  "errorMessage: "Invalid API Keys in the Authorization header"
}
```

{% endtab %}

{% tab title="Bad API Keys" %}

```
{
  "errorCode: "BAD_API_KEYS",
  "errorMessage: "Bad API Keys"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403 Your account is deactivated and you can't start the identity process." %}

```
{
  "errorCode": "ACCOUNT_DEACTIVATED",
  "errorMessage": "Account deactivated. Please contact your Authenteq Sales Representative in order to keep using this service"
}
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
This endpoint should be called by your backend system.

The client secret, as its name suggests, is a secret and should never be made publicly available. It **SHOULD NOT** be stored in the frontend code that is run in the user's browser.
{% endhint %}

## Get Verification Result Details

<mark style="color:blue;">`GET`</mark> `https://api.app.authenteq.com/web-idv/verification-result`

The endpoint returns the verification result details extracted from the user document during identification. The verification result details are paired with the granted code.\
\
This endpoint is authorized with Basic Auth. You should use your Client ID and Client Secret from the Customer Dashboard as the credentials.

#### Query Parameters

| Name        | Type   | Description                                                                         |
| ----------- | ------ | ----------------------------------------------------------------------------------- |
| redirectUrl | string | The redirect URL you used to request the verification session.                      |
| code        | string | The code you got on redirect and granted to access the verification result details. |

#### Headers

| Name          | Type   | Description                                                                                         |
| ------------- | ------ | --------------------------------------------------------------------------------------------------- |
| Authorization | string | Your client credentials combined with a colon separator, base64-encoded and prefixed with "Basic ". |

{% tabs %}
{% tab title="200 The details extracted from the user document." %}

```javascript
{
  "id": "3631324b-5bcc-48b0-b717-4f12f45e0a1d",
  "status": "PASSED",
  "platform": "WEB",
  "startTime": "2020-04-10T11:44:40Z",
  "endTime": "2020-04-10T11:47:23Z",
  "livenessFaceImage": {
    "contentType": "image/jpeg",
    "content": "bGl2ZW5lc3NGYWNlSW1hZ2UK"
  },
  "documentData": {
    "documentType": "DL",
    "documentNumber": "1234567890",
    "issuingCountry": "USA",
    "jurisdiction": "UT",
    "nationality": "USA",
    "surnameAndGivenNames": "DOE JOHN",
    "surname": "DOE",
    "givenNames": "JOHN",
    "nameSuffixes": "MR",
    "namePrefixes": "JR",
    "sex": "M",
    "dateOfBirth": "1964-12-30",
    "dateOfExpiry": "2022-12-30",
    "dateOfIssue": "2012-05-30",
    "address": "430-985 ELEIFEND^DULUTH WA 92611",
    "licenseClass": "B/C/D",
    "licenseClassDetails": {
      "B": {
        "from": "2019-01-30",
        "to": "2029-01-30",
        "notes": "Some valuable note"
      },
      "C": {
        "from": "2019-01-30",
        "to": "2029-01-30"
      },
      "D": {
        "from": "2019-01-30",
        "to": "2029-01-30"
      }
    },
    "croppedFrontImage": {
      "contentType": "image/jpeg",
      "content": "Y3JvcHBlZEZyb250SW1hZ2U="
    },
    "croppedBackImage": {
      "contentType": "image/jpeg",
      "content": "Y3JvcHBlZEJhY2tJbWFnZQ=="
    },
    "faceImage": {
       "contentType": "image/jpeg",
       "content": "ZmFjZUltYWdlCg=="
    }
  },
  "nfcVerified": false,
  "addressProofDocument": {
    "contentType": "application/pdf",
    "content": "YWRkcmVzc1Byb29mRG9jdW1lbnQK"
  }
}
```

{% endtab %}

{% tab title="400 The request contains an invalid data." %}
{% tabs %}
{% tab title="Missing code" %}

```
{
  "errorCode": "MISSING_REQUEST_PARAMETER",
  "errorMessage": "Required 'code' parameter is missing"
}
```

{% endtab %}

{% tab title="Missing redirect URL" %}

```
{
  "errorCode": "MISSING_REQUEST_PARAMETER",
  "errorMessage": "Required 'redirectUrl' parameter is missing"
}
```

{% endtab %}

{% tab title="Invalid code" %}

```
{
  "errorCode": "INVALID_REQUEST_PARAMETER",
  "errorMessage: "Parameter 'code' is invalid or expired"
}
```

{% endtab %}

{% tab title="Redirect URL mismatch" %}

```
{
  "errorCode": "INVALID_REQUEST_PARAMETER",
  "errorMessage: "Parameter 'redirectUrl' does not match the given authorization code"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401 Full authentication is required to get the verification result." %}
{% tabs %}
{% tab title="Missing API Keys" %}

```
{
  "errorCode": "API_KEYS_MISSING",
  "errorMessage": "No API Keys in the Authorization header"
}
```

{% endtab %}

{% tab title="Invalid API Keys" %}

```
{
  "errorCode": "API_KEYS_INVALID",
  "errorMessage": "Invalid API Keys in the Authorization header"
}
```

{% endtab %}

{% tab title="Bad API Keys" %}

```
{
  "errorCode": "API_KEYS_BAD",
  "errorMessage": "Bad API Keys"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

{% hint style="danger" %}
This endpoint should be called by your backend system.

The client secret, as its name suggests, is a secret and should never be made publicly available. It **SHOULD NOT** be stored in the frontend code that is run in the user's browser.
{% endhint %}

{% hint style="info" %}
The code can be used once only. On subsequent requests you will get an error that the code is invalid or expired.
{% endhint %}

The successful response on getting the verification result can hold the following properties:

<table data-header-hidden><thead><tr><th width="180.37834036568216">Property</th><th width="175.33027343716083">Description</th><th width="150">Mandatory</th><th>Example</th></tr></thead><tbody><tr><td>Property</td><td>Description</td><td>Mandatory</td><td>Example</td></tr><tr><td>id</td><td>The unique id of the identity verification.</td><td>Yes</td><td><code>"c72322ac-23fc-4667-b23b-f8a1a50653d4"</code></td></tr><tr><td>platform</td><td>The client platform on which the identity verirication was started. Actually it's always <code>WEB</code>.</td><td>Yes</td><td><code>"WEB"</code></td></tr><tr><td>startTime</td><td>The date-time when the identity verification was started.</td><td>Yes</td><td><code>"2020-04-10T11:44:40Z"</code></td></tr><tr><td>endTime</td><td>The date-time when the identity verification was finished.</td><td>Yes</td><td><code>"2020-04-10T11:47:23Z"</code></td></tr><tr><td>livenessFaceImage</td><td>The face image taken on the liveness check.</td><td>Yes</td><td><p><code>{</code></p><p>  <code>"contentType": "image/jpeg",</code></p><p>  <code>"content": "bGl2ZW5lc3NGYWNlSW1hZ2UK"</code></p><p><code>}</code></p></td></tr><tr><td>documentData</td><td>The document data extracted from the first scanned document.</td><td>Yes</td><td>Described below.</td></tr><tr><td>documentData2</td><td>The document data extracted from the second scanned document in case of the multi-document flow.</td><td>No</td><td>Described below.</td></tr><tr><td>documentData3</td><td>The document data extracted from the third scanned document in case of the multi-document flow.</td><td>No</td><td>Described below.</td></tr><tr><td>nfcVerified</td><td>Whether at least one of the scanned documents was verified via NFC.</td><td>Yes</td><td><code>true</code> or <code>false</code></td></tr><tr><td>addressProofDocument</td><td>The address proof document provided by the user.</td><td>No</td><td><p><code>{</code></p><p>  <code>"contentType": "application/pdf"</code><br><code>,</code></p><p>  <code>"content": "YWRkcmVzc1Byb29mRG9jdW1lbnQK"</code></p><p><code>}</code></p></td></tr></tbody></table>

Each document data field can hold the following properties:

<table data-header-hidden><thead><tr><th width="193.28571428571428">Property</th><th width="184.26849894291757">Description</th><th width="150">Mandatory</th><th>Example</th></tr></thead><tbody><tr><td>Property</td><td>Description</td><td>Mandatory</td><td>Example</td></tr><tr><td>documentType</td><td><p>The document type described by abbreviations:</p><ul><li><code>PP</code> - passport,</li><li><code>DL</code> - driver's license,</li><li><code>NID</code> - national ID.</li></ul></td><td>Yes</td><td><code>"PP", "DL", "NID"</code></td></tr><tr><td>documentNumber</td><td>The document number.</td><td>Yes</td><td><code>"FG617451", "8136431812"</code></td></tr><tr><td>issuingCountry</td><td>The three letter country code in <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3">ISO 3166-1 alpha-3 format</a> of the country which issued the document.</td><td>Yes</td><td><code>"DEU", "UKR", "USA"</code></td></tr><tr><td>jurisdiction</td><td>The state issued the document.</td><td>No</td><td><code>"FL"</code></td></tr><tr><td>nationality</td><td>The three letter country code in <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3">ISO 3166-1 alpha-3 format</a> of the user’s nationality.</td><td>No</td><td><code>"DEU", "UKR", "USA"</code></td></tr><tr><td>surnameAndGivenNames</td><td>The surname and given names, separated by whitespace.</td><td>Yes</td><td><code>"GARCIA DILS ANNA MARIA DE O", "GOZHENKO VITALII"</code></td></tr><tr><td>surname</td><td>The surname (family name).</td><td>No</td><td><code>"GARCIA DILS", "GOZHENKO"</code></td></tr><tr><td>givenNames</td><td>The given names, separated by whitespace.</td><td>No</td><td><code>"ANNA MARIA DE O", "VITALII"</code></td></tr><tr><td>nameSuffixes</td><td>The name suffixes, separated by whitespace.</td><td>No</td><td><code>"JR 3RD", "8TH"</code></td></tr><tr><td>namePrefixes</td><td>The name prefixes, separated by whitespace.</td><td>No</td><td><code>"DR MRS", "DR"</code></td></tr><tr><td>sex</td><td><p>The user's gender that contains one of values:</p><ul><li><code>F</code> - female,</li><li><code>M</code> - male,</li><li><code>X</code> - unspecified.</li></ul></td><td>No</td><td><code>"F", "M", "X"</code></td></tr><tr><td>dateOfBirth</td><td>The date of user's birth.</td><td>Yes</td><td><code>"1987-01-12"</code></td></tr><tr><td>dateOfExpiry</td><td>The date of document expiration.</td><td>No</td><td><code>"2017-01-30"</code></td></tr><tr><td>dateOfIssue</td><td>The date when the document was issued.</td><td>No</td><td><code>"2017-01-30"</code></td></tr><tr><td>address</td><td>The user's address.</td><td>No</td><td><code>"430-985 ELEIFEND^DULUTH WA 92611"</code></td></tr><tr><td>licenseClass</td><td>The type of Driving License detected.</td><td>No</td><td><code>"A","B","C"</code></td></tr><tr><td>licenseClassDetails</td><td>The details of Driver License detected.</td><td>No</td><td><p><code>{</code></p><p>  <code>"A" : {</code></p><p>    <code>"from": "2019-01-30",</code></p><p>    <code>"to": "2029-01-30",</code></p><p>    <code>"note": "Some valuable note"</code></p><p>  <code>}</code></p><p><code>}</code></p></td></tr></tbody></table>

{% hint style="info" %}
Not all documents contain surname and given names as separate fields. Quite often there is just a single field where surname and given names follow each other. So surname and givenNames fields exist in the retrieved document data only when they exist in the user document as separate ones.
{% endhint %}

{% hint style="info" %}
All binary data like content of images, attached documents and so on are returned in base64 format and will need to be decoded.
{% endhint %}