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

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

For the Portuguese solution, follow the French solution integration guide.

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
DocumentsDocument types and nationalities per country

See also: Supported ID documents
Required 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
Address on the ID document included in the CDD Report and output XML file or not
Document issuing country included in the CDD Report and output XML file or not
Raw VIZ data including special characters with diacritics shared or not
BiometricsSelfie audio included or not
LocationSupported countries

See also: Prohibited countries
Physical Proof of Address included or not
Required geolocation data groups

See also: Upload identity data > deviceMetaData
AML ScreeningThe number 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
PlatformDeployment model:
• Shared deployment
• Dedicated deployment
Operating model:
• Fourthline operated
• Fourthline powered
Enhanced risk score for Italian clients required 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.

Data collection and upload

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

Integration optionDescription
App Drop-in
Web SDK
The SDK frontend can automatically collect all identity data and upload it to Fourthline.

Alternatively, you can agree with your implementation manager to upload some data points via the Upload identity data request. In this case, the SDK detects which data points you've provided and only collects any outstanding data.
API-only
Components
You always upload all relevant data points via the Upload identity data request.

Diacritics service

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 output XML file.

Example code

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

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


User guide

Identity files

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

The following files are required per document type:

ID documentDocument typeRequired files
Primary ID documentDocumentVideo1 x Front
Format: Less than 10 seconds long
• App Drop-in and API only: mp4
• Web SDK: webm
DrivingLicense2 x Front: Normal + Tilted
2 x Back: Normal + Tilted
EmbeddedFace1 x Front
NationalIDCard2 x Front: Normal + Tilted
2 x Back: Normal + Tilted
PaperId2 x InsideRight: Normal + Tilted
1 x InsideLeft: Normal
1 x Back: Normal
Passport2 x Front: Normal + Tilted
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 only: mp4
• Web SDK: webm
Second ID documentBusinessCard1 x front: Normal
1 x Back: Normal
HealthInsuranceCard1 x Front: Normal
1 x Back: Normal
StudentIDCard1 x Front: Normal
1 x Back: Normal
Other, e.g.:
• SSN reference document
TIN document
1 x Front: Normal
1 x Back: Normal
IBAN statement
Proof of address, e.g. utility bill
1 x Front: 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 output XML file include the transliterated data.

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

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