Setup

App Drop-in

Web SDK

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

Module	Configuration
Documents	Supported 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
Biometrics	For App Drop-in, Components, and Web SDK integration, real-time feedback
	Selfie Audio included or not
Location	Supported 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 data	Italian market data included or not
	Spanish market data included or not
AML Screening	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
Platform	Operating model: • Fourthline operated • Fourthline powered
	Deployment model: • Shared deployment • Dedicated deployment
	QA service included or not
	Fourthline Dashboard included or not
Client	Fourthline 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):

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.

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

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:

User guide

Identity files

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:

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

Diacritic	Transliteration
Å	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):

Support

For any questions, contact your implementation manager.

Top of page