Identity Verification Integration

Integration guide

Setup

This page provides guidance on preparing to integrate European Identity Verification solution via the App Drop-in, Web SDK, or the API.

See also
See the integration guides for the:
French solution
German solution

For the Portuguese solution, follow the French solution guide, but ensure you configure the Tax number module instead of the Physical Proof of Address module.

Before you begin your integration, make sure you have the following in place:

Prerequisites

  • You need your Fourthline API key.
  • Agree with your implementation manager the identifiers of your product and market-specific workflows.
    For default options, see Create workflow.

Statuses

Set up handling for Identity Verification statuses.

Webhook

Set up a webhook and handling for the Identity Verification notifications.


Configuration

Discuss with your implementation manager the following configuration options:

ModuleConfiguration
DocumentsSupported ID document types and nationalities per country
ID document photos:
• Flat only
• Flat and titled to check security features
Document NFC included or not

See also: Supported ID documents
Second ID document module included or not

Required in Czech Republic and Luxembourg
Tax number module included or not

Required in Italy and Portugal
Identity data upload configuration
Address on the ID document included in the CDD Report and XML file or not
Document issuing country included in the CDD Report and output XML file or not
Client age:
• Specify your minimum required age
• For App Drop-in integration, dynamically configure age requirements and checks during workflow or not
Diacritics service included or not
Duplicated ID document check configured or not
BiometricsFor App Drop-in, Components, and Web SDK integration, real-time feedback
Selfie Audio included or not
LocationSupported countries
Physical Proof of Address included or not
Geolocation data groups

See also: Upload identity data > deviceMetaData
Client's IP address returned in the XML file and Get case status completed response or not
Market-specific dataItalian market data included or not
Spanish market data included or not
AML ScreeningNumber of hits that triggers your threshold for automatic rejection
Four-eyes review of confirmed hits by Fourthline human agents included or not
Your sensitivity list screened or not

See also: Sensitivity list
PlatformOperating model:
• Fourthline operated
• Fourthline powered
Deployment model:
• Shared deployment
• Dedicated deployment
QA service included or not
Fourthline Dashboard included or not
ClientFourthline usually supports a minimum age of 18 years, but for Web SDK integrations you can configure this to 16 years.

Identity data

Required

Determine how clients' identity data is collected and uploaded to Fourthline:

App Drop-in & Web SDK integration
Configurable

Option 1
The SDK frontend can automatically collect all identity data and upload it to Fourthline.

Option 2
Agree with your implementation manager to upload some data points yourself via the Upload identity data request.

In this case, the SDK detects which data points you've provided and only collects any outstanding data.

All objects in the request are optional, but if you do include an object, you must provide all required parameters within the object.
API-only & App Components integration
Required

You always upload all relevant data points via the Upload identity data request.

The following objects are required:
person
address
emailAndPhone

Tax number

Required in Italy and Portugal

If you need to provide the client's TIN:

  • App Drop-in and Web SDK: This data is captured and uploaded by the SDK.
  • API-only and App Components: In the Upload identity data request, the tax object is required.

Configurable
You can configure which TIN documents to accept. If a client provides a document that is outside your regulatory scope, we don't return the TIN to you.

Market-specific data

Italian market

Optional

For Italian clients, you can provide the following additional data points in the Upload identity data request (riskRequirements object):

Data pointDescription
Age of clientHow old the client is
Product typeWhat type of product the client makes, or the type of work they do
Sector of activityThe industry where the client works
Place of work activityWhere the client works
Main source of income /
Origin of funds
How the client earns their money, or where their funds came from
PEP status disclosed by clientWhether the client disclosed that they are a PEP of their own accord
Watchlist resultsWhether there are any AML hits for the client

Spanish market

Required

For Spanish clients, the following configuration is required:

  • Extended selfie video
  • Video geolocation
  • Sepblac consistency check

Diacritics service

Configurable

On request, Fourthline can share raw VIZ data with special characters with diacritics (on a best-effort basis) for ID documents issued by:

  • France
  • Germany
  • Netherlands
  • Poland
  • Portugal
  • Spain

The raw data is returned in the Get case status response as a RawVizReading JSON object.
This data isn't included in the CDD Report or XML file.

Example code

Example raw data with diacritics

The RawVizReading JSON object is structured as follows:

"RawVizReading":[
  {
    "FieldName":"FirstName",
    "FieldValue":"WILLEKÉ LISELÖTTE"
  },
  {
    "FieldName":"GivenNames",
    "FieldValue":"DÖ BRUIJN"
  },
  {
    "FieldName":"DateOfBirth",
    "FieldValue":"650310"
  },
  {
    "FieldName":"Gender",
    "FieldValue":"F"
  },
  {
    "FieldName":"PlaceOfBirth",
    "FieldValue":"SPECIMEN"
  },
  {
    "FieldName":"Nationality",
    "FieldValue":"NËDÉRLÁNDSE"
  },
  {
    "FieldName":"CountryCode",
    "FieldValue":"NÈD"
  },
  {
    "FieldName":"DocumentNumber",
    "FieldValue":"SPÉCI2014"
  },
  {
    "FieldName":"IssueDate",
    "FieldValue":"140309"
  },
  {
    "FieldName":"ExpiryDate",
    "FieldValue":"240309"
  },
  {
    "FieldName":"DocumentType",
    "FieldValue":"P"
  }
]

Our AI agent was trained on the following characters:

Supported characters

Supported characters

Supported characters
a á â ä A À Á Â Ä Ã Ă Ą
b B
c ć č ç C Ć Č Ç
d D
e è é ë E È É Ê Ë Ę
f F
g G Ğ
h H
i í î ï I Í Î Ï İ
j J
k K
l L Ł Ļ
m M
n N Ń Ň Ñ
o ó ô ö O Ò Ó Ô Ö Œ
p P
q Q
r R
s š S Ś Š Ş ẞ
t Ţ
u ú ü U Ù Ú Û Ü
v V
w W
x X
y Y
z ž Z Ź Ž Ż
' * ( ) , . - /
1 2 3 4 5 6 7 8 9 0

Important
Fourthline human agents don't check special characters fields during case processing.
The diacritics service doesn't affect case processing or data correction in any way.

Duplicated ID document check

Configurable

You can configure Fourthline to check if the ID document number provided has been used before. This can help prevent fraudsters from using stolen documents.

However, sometimes legitimate clients may need to re-use a document number, e.g. if they:

  • Want to open a new type of account with you
  • Delete the Fourthline app and can't sign back in
  • Need to re-submit a case that was sent back

In such cases, you need to clear the ID document data from the client's profile:

  • The status of the client's Identity Verification case must have changed from new to pending.
  • The status of the original case doesn't change when you reset the document.

Important
Resetting a document doesn't delete the client's personal data from their profile.
To remove personal data completely from our system, the client must make a formal deletion request under the GDPR.
For more information, contact your implementation manager.

Use the following requests as required:

RequestDescription
Reset document by clientIdReset a client's ID document using their clientId.
Reset document by verificationIdReset a document using the verificationId (same value as the workflowId).
Reset multiple documentsReset multiple clients' documents using a clientId array.


User guide

Identity files

API_Only API integration

When making an Upload identity files request, check the following guidance:

  • Always upload the client's primary ID document first, and then the second ID document (if required).
  • Make a separate request for each DocumentType, but you can include multiple identity files of the same type in one request.
  • Set all required parameters, or the identity file is ignored.
  • For a single clientId, every filename must be unique.
  • If an ID document contains an NFC chip, you must afterwards upload an EmbeddedFace file (the portrait on the NFC chip) in a separate request, including the ID document's DocumentNumber.
    Don't upload an EmbeddedFace file if the ID document doesn't contain an NFC chip, or you can't start case processing.
  • To add new or extra identity files for an already uploaded identity file, include the correct DocumentType and DocumentNumber (if relevant) in the request, or we will add it as a new identity file.
  • To modify the content or details of an already uploaded identity file, include the same DocumentType and DocumentNumber and fileName, or we will add it as a new identity file.
  • You can't update PDF documents.
  • For document and selfie videos, we support the following formats:
    • MP4
    • WEBM
    • WEBM;CODECS=VP8
    • MKV
    • x-MATROSKA
  • For photos and documents, we support the following formats:
    • JPEG
    • PDF
    • PNG

The following files are required per document type:

Document typeRequired files
BusinessCard1 x front: Normal
1 x Back: Normal
DocumentVideo1 x Front
Format: Less than 10 seconds long
• App Drop-in and API integration: mp4
• Web SDK: webm
DrivingLicense2 x Front: Normal + Tilted
2 x Back: Normal + Tilted
EmbeddedFace1 x Front
HealthInsuranceCard1 x Front: Normal
1 x Back: Normal
IbanStatement1 x Front: Normal
NationalIDCard2 x Front: Normal + Tilted
2 x Back: Normal + Tilted
Other1 x Front: Normal
1 x Back: Normal
PaperId2 x InsideRight: Normal + Tilted
1 x InsideLeft: Normal
1 x Back: Normal
Passport2 x Front: Normal + Tilted
ProofOfResidence1 x Front: Normal
ResidencePermit2 x Front: Normal + Tilted
2 x Back: Normal + Tilted
Selfie1 x Front: Normal
SelfieVideo1 x Front
Format: Less than 10 seconds long
• App Drop-in and API integration: mp4
• Web SDK: webm
SsnReferenceDocument1 x Front: Normal
1 x Back: Normal
StudentIDCard1 x Front: Normal
1 x Back: Normal
TinReferenceDocument1 x Front: Normal
1 x Back: Normal

Special characters

To standardize data entered by the client and extracted from the VIZ in line with the MRZ, Fourthline applies the International Civil Aviation Organization (ICAO) transliteration standard in Doc 9303: Machine Readable Travel Documents.

The CDD Report and XML file include the transliterated data.

Characters with diacritics are converted into simplified Latin characters as follows:

Diacritics transliteration

Diacritics transliteration

DiacriticTransliteration
ÅAA
ÆAE
À Á Â Ã Ā Ă ĄA
ÄAE
Austria, Belgium, Estonia, Finland, Germany, Sweden, Switzerland

A
Netherlands
SS
Ç Ć Ĉ Ċ ČC
Ď ÐD
È É Ê Ë Ē Ė Ę
Ĕ (0114)
Ě (011A)
E
Ĝ Ğ Ġ ĢG
Ĥ ĦH
Ì Í Î Ï Ĩ Ī Ĭ Į İ
I (0131)
I
ĴJ
ĶK
Ĺ Ļ Ľ Ŀ ŁL
Ń Ņ Ň ŊN
ÑN
Argentina, Bolivia, Latvia, Mexico, Philippines, Poland, Slovakia, Spain

NXX
Chile, Costa Rica, Dominican Republic, Ecuador, El Salvador, Guatemala, Paraguay, Peru, Uruguay
Fourthline then transliterates NXX to N
Ø ŒOE
Ò Ó Ô Õ Ō Ŏ ŐO
ÖOE
Austria, Belgium, Estonia, Finland, Germany, Hungary, Iceland, Norway, Sweden, Switzerland

O
Turkey, Netherlands
Ŕ Ŗ ŘR
Ś Ŝ Ş ŠS
Ţ Ť ŦT
Ù Ú Û Ũ Ū Ŭ Ů Ű ŲU
ÜUE
Austria, Belgium, Estonia, Germany, Hungary, Switzerland

U
Philippines, Turkey, Netherlands, Spain
ÞTH
ŴW
Ý Ŷ ŸY
Ź Ż ŽZ

Supported countries

We never onboard clients in Fourthline's list of prohibited countries and you can't configure this. The list may change over time, e.g. depending on European sanctions.

More information
For the complete list of supported countries and territories and all checks we perform, request our CDD Policy from your implementation manager.

Supported ID documents

To check which ID documents Fourthline supports in different countries and whether they contain an NFC chip, make a Get ID documents request.

More information
For the complete list of supported ID documents and all checks we perform, request our CDD Policy from your implementation manager.


Testing

Fourthline's platform is built to detect real faces and authentic ID documents with correctly matching personal data. This means, by the nature of our business, we can't provide dummy documents, photos, files, or data for testing.

To test your Identity Verification solution:

  1. Use official specimen documents, or the real ID documents and data of your colleagues, to create test cases in the sandbox environment.

  2. Use the Set test outcome endpoint to set the outcome for test cases when they reach a specific status.

  3. To safeguard the privacy of your colleagues and their data, when you have finished testing, contact your implementation manager to delete all testing data from the sandbox.

More information
For more information about how Fourthline protects data, see Security & Compliance.

Set test outcomes

In the sandbox environment, you can make a Set test outcome request to set the outcome for an Identity Verification case when it reaches a specific status.

How it works

  • When you make the Set test outcome request, the case status must be new.
  • You receive webhook notifications as normal.
  • To download the CDD Report for test cases, you must wait for the case status to change from pending to the final status.

The request flow per integration option is as follows:


Limitations

  • This endpoint works for Identity Verification workflows only, not for workflows that also include Qualified Electronic Signature and/or Bank Account Verification.
  • You can set 1 risk code or 1 or more status codes, but not both a risk code and status code(s) in 1 request.
  • ID document security features aren’t included in the CDD Report for test cases.
  • Data points that are extracted from the ID document in real cases, or corrected by Fourthline agents, aren't included in the CDD Report, output XML, or Get case status response.
  • The supported statuses and outcomes depend on your configuration, and some can't be tested with this endpoint.
  • You can’t further configure this endpoint, e.g. by adding or removing checks or data points.
  • The endpoint can return a fraud outcome even if the test case isn't fraudulent.

Supported statuses

You can apply outcomes when the case reaches the following statuses:

  • completed
  • inconsistent_data
  • pending

Supported outcomes

You can set the following outcomes when the case reaches the specified status using the relevant risk code or status code(s):

OutcomeRisk codeStatus codes
completed
acceptable risk
200
completed
unacceptable risk
4110 5100
inconsistent_data2001 2002 2003 3001 3002 3003 3005 3100 3101 3102 3103 3104 3105 3200 3201 3202 3203 3204 3205 3300 3304 3305 3306 3307 3400 3401 3402 3403 3404 3405 3406

Support
For any questions, contact your implementation manager.

Top of page

Accordion in HTML5