Fourthline ID Scan

API

The Fourthline API is an offering of Rabo Identity Services to identify users based on an identity document. Fourthline has a broad geographical coverage supporting over 3.500 different identity document types from 185 different countries.

This API offers extensive capabilities to identify users, verify the authenticity of the document, and reduce the risk of identity fraud.

To gain more certainty about the user's identity, the identity verification can be expanded with several options such as biometric, liveness, and/or location.

Facial recognition compares the photo on the ID with a selfie or live video taken by your customer, this is used to match the user identity with the provided document. Digital proof of address compares the geolocation of the user’s device with the location data provided. This can be used to determine if the address is valid, genuine, and uncompromised.

Attribute Overview

The final result of a successful verification contains multiple attributes, which reflect the outcome of the verification. The following attributes are derived from the identity document (if present on the document) and are returned as part of the user verification.

• First name
• Last name
• Date of expiry
• Issuing authority
• Issuing country
• Gender
• Document number
• Date of birth
• Personal number
• Date of issue
• Document type
• Nationality

Using the API

After your account set up is complete, subscribe the Fourthline API to your application. Through the Fourthline identity verification flow, users can identify themselves online based on their own legal identity document and biometrics. For each verification, a workflow must be created through the API, as explained in this page.

Webhook Setup

The verification process is asynchronous. So in order for your application to retrieve the final status of these verifications, a webhook notification can be setup. This configuration should be made and tested during the setup of your account.

Step 1 - Create a workflow

Initiate a new workflow on the Fourthline API. An example request is provided below, where:

• The providerClientId is a unique value for the verification of a specific user. This value must be unique per providerClientId and the obtained document number of the identity document. In case a different providerClientId is provided while using the same identity document, the user experiences an error in the flow, resulting in a 1036 error code (ID document number already used).
• The identityData object can be populated with data that you have already obtained from the user. If this object is populated, the user does not need to add it in the UI. However, if left empty, the user needs to provide this information in the UI.

Request

The API supports the possibility to associate your own unique identifier to the dossier in order to link it to your own session.

POST https://api.rabobank.nl/openapi/ris/fourthline/workflows

{
  "workflow": {
    "workflowName": "IDV",
    "providerClientId": "7b6a9e91-1701-b24d-9476-efb5b24ee47e"
  },
  "session": {
    "target": "web"
  },
  "identityData": {
    "address": {
      "street": "Croeselaan",
      "streetNumber": 11,
      "postalCode": "3521CB",
      "city": "Utrecht",
      "country": "NLD"
    },
    "emailAndPhone": {
      "email": "[email protected]",
      "mobile": "+316123456789"
    }
  }
}

Response

After the workflow is successfully initiated, a session is created for that specific verification. The session is uniquely defined by the workflowId, which later can be used to fetch the case status and the CDD report. The response below is intended to be used to start the Web SDK session in the browser. Each session has:

• A validationCode; this unique validation code must be used to start the Web SDK session. This links the workflow to the SDK session.
• An expiryDateTime; after this time the validation code is no longer valid and a new workflow needs to be initiated.

{
    "workflowId": "f5d02f64-d053-4ab2-af5f-9b4be4281f19",
    "clientId": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "session": {
        "validationCode": "99992DFD",
        "expiryDateTime": "2024-08-06T20:42:02.4093721+00:00"
    }
}

Step 2 - Complete the steps in the Web SDK

As mentioned above, when creating the workflow. The ValidationCode must be used to start the SDK session in the browser. Handling is further explained in the SDK section below.

Step 3 - Get the status of the verification

When the user has completed all the required steps in the flow, it's possible to retrieve the status of the request. A request and response example of a completed verifications is given below. This response contains the information on the status of the request and, when available, information about the verification itself.

📘

When the webhook setup has been configured on your account, you receive incoming webhook notifications about the status of these requests.

Request

GET https://api.rabobank.nl/openapi/ris/fourthline/workflows/{{workflowId}}

Response

{
  "verificationId": "f5d02f64-d053-4ab2-af5f-9b4be4281f19",
  "verificationStatus": "new",
  "hash": "8f15a543ab4eff7d75629d680c9489b1",
  "data": {
    "modifiedDateTime": "2019-01-17T07:24:30Z",
    "clientNumberProvider": "ad45008c-222f-4783-80af-768abfd2a5b1",
    "riskCategory": "ACCEPTED",
    "analyst": "SNCA00001",
    "userData": {
      "document": {
        "device": {
          "deviceMetaData": {
            "ipAddress": "000.000.00.000"
          }
        },
        "person": {
          "name": "WILLEKE LISELOTTE DE BRUIJN",
          "type": "Natural Person",
          "gender": "Female",
          "initials": "WLB",
          "lastName": "DE BRUIJN",
          "birthDate": "1965-03-10",
          "firstName": "WILLEKE LISELOTTE",
          "middleName": "LISELOTTE",
          "nationality": "NLD",
          "placeOfBirth": "Utrecht",
          "countryOfBirth": "NLD"
        },
        "address": {
          "city": "Utrecht",
          "region": "Utrecht",
          "street": "Croeselaan",
          "country": "NLD",
          "postalCode": "3521CB",
          "streetNumber": 18,
          "secondAddressLine": "Croeselaan",
          "streetNumberPrefix": "A",
          "streetNumberSuffix": "A"
        },
        "documents": [
          {
            "files": [
              {
                "id": "bd96fb78-387c-4664-938a-949855362096",
                "side": "Front",
                "fileType": "MP4",
                "fileLocation": "documentvideo_front_normal.mp4"
              }
            ],
            "issueDate": "",
            "documentType": "Document Video",
            "documentNumber": "",
            "documentIssuingCountry": "",
            "expirationDate": ""
          },
          {
            "files": [
              {
                "id": "99493ac2-3749-4c5a-8178-c4c7c576c7d6",
                "side": "Front",
                "fileType": "JPEG",
                "fileLocation": "passport_front_normal.jpeg"
              },
              {
                "id": "12ebaa7e-a0f0-442f-992b-165612dbfd74",
                "side": "Front",
                "fileType": "JPEG",
                "fileLocation": "passport_front_tilted.jpeg"
              }
            ],
            "issueDate": "2021-08-30",
            "documentType": "Passport",
            "documentNumber": "SPECI2021",
            "documentIssuingCountry": "",
            "expirationDate": "2031-08-30"
          },
          {
            "files": [
              {
                "id": "99d3f5cb-5483-4bf4-b138-c83a39ea643b",
                "side": "Front",
                "fileType": "JPEG",
                "fileLocation": "selfie_secondary.jpeg"
              }
            ],
            "issueDate": "",
            "documentType": "Selfie",
            "documentNumber": "",
            "documentIssuingCountry": "",
            "expirationDate": ""
          },
          {
            "files": [
              {
                "id": "1a063850-9807-4c6a-8078-93c1fcfe9c13",
                "side": "Front",
                "fileType": "MP4",
                "fileLocation": "selfievideo_secondary.mp4"
              }
            ],
            "issueDate": "",
            "documentType": "Selfie Video",
            "documentNumber": "",
            "documentIssuingCountry": "",
            "expirationDate": ""
          }
        ],
        "emailAndPhone": {
          "email": "[email protected]",
          "mobile": "+316123456789"
        }
      }
    },
    "messages": []
  },
  "processType": "NaturalPersons",
  "dataValidationError": {},
  "riskInfo": {
    "statusCode": 200,
    "description": "Low"
  }
}

Step 4 - Retrieve the final CDD report

After the verification is completed successfully, you can retrieve the CDD report. The request below illustrates how the CDD report can be retrieved:

GET https://api.rabobank.nl/openapi/ris/fourthline/workflows/{{workflowId}}/pdf

In the (pre)production environments, message level encryption is applied to this specific response, due to the nature of processing sensitive PII data. For more information, read Message level encryption

🚧

• Each response contains a X-Trace-Id header which can be used for troubleshooting failed transactions* Certain fields may not be available in the response body, this depends on the availability in the source and the type of request. Read the response schema object to understand which fields can be part of the response body.

All responses are signed by Rabobank, to validate the response read Validate signed responses

SDK

Fourthline's Web SDK smoothly redirects clients from your website using a QR code or SMS to a new browser window on their mobile device. The product workflow on the device is hosted by Fourthline on a secure, private subdomain. Alternatively, you can embed the SDK in your mobile site.

The SDK takes care of the user journey and orchestrates modules with a streamlined API flow. You can also easily level up from single products to multi-product solutions with no additional API requests.

All required images and data are captured in our best-practices UI and automatically uploaded to Fourthline for processing. You don't have to handle sensitive personal data yourself.

Web SDK Setup

The following sections explain how to set up the Web SDK and the input needed to configure the SDK to your requirements.

SDK Configuration

Provide your implementation manager with the following configuration specifications:

Required URLs

The redirect flow is typically embedded in your website and hosted by you, so you must provide us the URL for both sandbox and production, e.g. www.mysite.com.

The product flow is hosted by Fourthline and can be served using either:

Redirect Options

Specify which redirect option you want to use: QR code and/or SMS.

For SMS redirect:

• Specify the languages you want to support.
• Specify a default language.
• Provide the SMS message copy per language.
• Provide the SMS originator (indicates to the client who the SMS is from) as a string of 3-11 characters.

Web SDK Integration

You can set up your Web SDK by embedding in the browser.

To embed the Web SDK:

Import JavaScript

Import the following scripts. You can put them in the header or inline in the HTML:

<!DOCTYPE html>
<html lang="en">
<head>
   
  ...
   
  <script type="module" src="https://sandbox.v.fourthline.com/v1/build/web-sdk-v2.esm.js"></script>
  <script nomodule src="https://sandbox.v.fourthline.com/v1/build/web-sdk-v2.js"></script>
</head>

🚧

• If using a custom domain or customized Fourthline domain for the workflow, replace sandbox.v.fourthline.com with the URL of your test or live environment, as agreed with your implementation manager.* The sandbox environment is for implementation only. When you migrate to the production environment, remove sandbox from the URL.

Add Flow Tag

Add the custom flow tag to the HTML or in the template of the relevant component.

The tag is only rendered after the source for it is loaded.

<!DOCTYPE html>
<html lang="en">
<head>
   
  ...
   
  <script type="module" src="https://sandbox.v.fourthline.com/{version, e.g.v1}/build/web-sdk-v2.esm.js"></script>
  <script nomodule src="https://sandbox.v.fourthline.com/{version, e.g. v1}/build/web-sdk-v2.js"></script>
</head>
<body>
   
  /* Somewhere in the page */
   
  <div class="container">
    <fl-flow-onboarding></fl-flow-onboarding>
  </div>
 
</body>
</html>

Localize the UI

To configure the UI language and level of formality, pass the following attributes to the fl-flow-onboarding component.

Supported languages and formality:

<fl-flow-onboarding
  locale="nl"
  formality="formal"
></fl-flow-onboarding>

Fallback flow

If you choose not to set the locale attribute, we check if the browser settings locale is:

• Supported: We set the browser settings as the SDK locale.
• Not supported: We check the lang attribute in the html tag.

If the lang attribute is:

• Supported: We set it as the SDK locale.
• Not supported: The SDK locale defaults to en (English).

Dynamic Localization (JavaScript)

You can set the locale and formality dynamically.

The fl-flow-onboarding component exposes a setLocale JavaScript method, which accepts new supported locale and formality as arguments.

If not supported, the fallback flow is triggered.

const elem = document.getElementsByTagName("fl-flow-onboarding")[0];
elem.setLocale("fr"); // Setting French
elem.setLocale("fr", "formal"); // Setting French (formal)

🚧

The mobile device flow locale is set when the redirect flow (fl-flow-onboarding) is rendered for the first time. If you set the locale dynamically afterwards, it isn't updated for the mobile device flow. This can create a less optimal user experience, so we recommend setting the redirect flow locale using HTML before loading the SDK.

Link to the Workflow

To link the redirect flow (fl-flow-onboarding) to the workflow, pass the validationCode returned in the Create SDK session response to the component.

Either set the validationCode as an HTML attribute:

const elem = document.getElementsByTagName("fl-flow-onboarding")[0];
elem.setLocale("fr"); // Setting French
elem.setLocale("fr", "formal"); // Setting French (formal)

Or, set the token in JavaScript:

const flow = document.getElementById('onboarding-flow');

flow.setToken('TOKEN_OF_THE_VERIFICATION');

🚧

The validationCode is single use. If you use server-side rendering, you must ensure the code is consumed after it reaches the client.

Handle Continue to Mobile event

When redirecting the client to the workflow from their mobile browser, the SDK emits an fl-flow-onboarding event (mobile/desktop).

If we detect the client's mobile device, we display a Continue button on mobile device screen.

When the client taps Continue, the SDK emits an flContinueMobileRequest event.

🚧

For the client to start the workflow, you must handle the flContinueMobileRequest event in your backend. If you don't handle it, the flow doesn't start and it appears to the client that the Continue button does not work.

The flContinueMobileRequest event contains a redirectHandler function in the event.detail payload. This function specifies what the SDK should do when the client completes the workflow.

If you provide URLs to your Success and Failure page, the SDK redirects the client there. If you don't provide them, we display a message telling the client that they have completed the flow and should return to your website.

New browser Tab

To start the workflow in a new browser tab, call the redirectHandler function without providing success or failure page URLs.

document.addEventListener('flContinueMobileRequest', (e) => {
  const redirectHandler = e.detail;
  redirectHandler();
});

Same browser Tab

To start the workflow in the same browser tab, call the redirectHandler function and provide the URLs to your:

• Success page by setting the redirect property
• Failure page by setting the redirectFailure property

The URLs must be valid and include the schema.

📘

Starting the workflow in the same browser tab overwrites the state of that page, which should be considered/handled first.

document.addEventListener('flContinueMobileRequest', (e) => {
  const redirectHandler = e.detail;
  redirectHandler({
    redirect: 'https://yoursuccesspage.com/onboarding?done=true',
    redirectFailure: 'https://yourfailurepage.com/onboarding?done=false'
  });
});

Handle Status Events

At each step of the workflow, the SDK emits an flOnboardingStatus event (desktop) that you can subscribe to.

You can use the status to trigger any required actions on your side, e.g. when you receive OnboardingStarted status and before receiving Loaded status, you can choose to display a ghost placeholder image.

The flOnboardingStatus event emits the following statuses:

To listen to this event, add the following JavaScript snippet to your website HTML. For each event status, define and implement the required behaviour on your side.

document.addEventListener('flOnboardingStatus', (event) => {
  const { detail: status } = event;
  if (status === 'Loaded') {
    // Put your code here
  }
  if (status === 'OnboardingCompleted') {
    // Put your code here
    // e.g. Remove the fl-flow-onboarding element from the DOM and render your success page
  }
  if (status === 'OnboardingCompletedError') {
    // Put your code here
  }
});

Handle Restart Event

If the client requests to restart the redirect flow, the SDK emits an flOnboardingRestartRequest event (desktop) that you can subscribe to and handle. It is triggered from the error screen when the client taps Try again and the flow has encountered a non-recoverable error.

This event doesn't emit any values.

To handle this event:

1. Listen to it.
2. Create a new workflow.
3. Create a new SDK session.
4. To set the new validation code, either:
   • Invoke the setToken(newValidationCode) method, or
   • Replace the existing HTML tag with a new tag containing the updated <fl-onboarding token="newValidationCode"></fl-onboarding> token.

document.addEventListener('flOnboardingRestartRequest', () => {
  const onboardingTag = document.getElementBy('fl-onboarding');
   
  // Generate a new validation and validation code
   
  onboardingTag.setToken(newValidationCode);
});