Identity Verification Integration

API-only guide

This guide provides step-by-step instructions on how to integrate the European Identity Verification solution via our API.

Before you begin, make sure you have completed the following:

• Identity Verification Setup
• Let your Fourthline delivery manager know if you want the following parameters in the Upload identity data request to be required or optional:
  • person.name
  • person.placeOfBirth

Flow

Click to magnify.

1. Authenticate

Create an access token to authenticate in our API:

• You provide your Fourthline API credentials.
• You receive an access_token.

Important

For security, access tokens are valid for 1 hour only.

If your token expires, create a new access token by making another Create access token request.

2. Create workflow

Create a European Identity Verification workflow:

• You specify the workflowName and provide your unique identifier for the client.
• You receive a workflowId and a Fourthline clientId.

Status: The Identity Verification case status changes to new.

3. Upload identity data

Upload the client's identity data:

• You provide the verificationId (same value as the workflowId). The first request includes the person, address, and emailAndPhone objects.
• A successful response is empty.

Tip

To update previously uploaded data, send Upload identity data again with the same verificationId.

deviceMetaData

On that request, deviceMetaData is merged field by field. person, address, emailAndPhone, tax, profession, and riskRequirements replace the whole object. When you send one of those objects, include every field that should remain stored.

Geolocation

After the SDK or App Component has stored model, update coordinates by sending latitude and longitude only.

Important

Do not send model in that request. The SDK or App Component has already uploaded the device model. A value such as Chrome replaces the stored model. The Qualified Electronic Signature device-model check then returns selfie_required.

Stored after the SDK or App Component upload:

{
  "deviceMetaData": {
    "model": "iPhone15,2",
    "language": "nl",
    "latitude": "51.00",
    "longitude": "4.00"
  }
}

Your request that only updates geolocation:

{
  "deviceMetaData": {
    "latitude": "52.37",
    "longitude": "4.89"
  }
}

Stored after that request:

{
  "deviceMetaData": {
    "model": "iPhone15,2",
    "language": "nl",
    "latitude": "52.37",
    "longitude": "4.89"
  }
}

Coordinates are updated. model and language stay, because they were not in the request.

Status: The Identity Verification case status remains new.

4. Upload identity files

Upload the client's identity document and supporting identity files:

• You provide the verificationId (same value as the workflowId).
• A successful response is empty.

Important

For detailed instructions on how to use this request, see the user guide.

5. Start case processing

Request Fourthline to start case processing:

• You provide the verificationId.
• A successful response is empty.

Status: The case status changes to one of the following and we send the relevant webhook notification:

Final statuses:

6. Check case status

When you receive webhook notifications, we recommend also requesting the full case details:

• You provide the verificationId (same value as the workflowId).
• You receive all the data on the case.

7. Download CDD Report

When the case status is completed, download the CDD Report zipfile:

• You provide the workflowId.
• A successful response is empty and the report is downloaded.