Video identification

This guide describes the integration process of the video KYC method via IDnow as a stand-alone solution, including key concepts, the mandatory information you must collect from your customers, and the necessary endpoints and webhooks you must integrate into your solution.

Introduction

Product overview

Video identification is the most common KYC method to identify and onboard your customers in an AML-compliant manner. Our external service provider IDnow carries out the identification process. The process involves identifying the customer in a remote video call with an IDnow identification agent.

During the identification session, IDnow verifies the customer's personal data and identity against the identification document they provided, such as passport or national ID card. The identification session can be conducted in German or English.

Additionally, you can combine video identification with a Qualified Electronic Signature (QES) to allow your customers to digitally sign contracts or agreements compliantly.

Eligibility

Video identification is suitable for any of Solarisbank's products, including high-risk banking products, such as a full bank account. It's available only for customers who reside in Germany and it can be completed either in a web browser or through IDnow's mobile app.

Additionally, video identification with IDnow is restricted to customers from countries with the supported documents list.

If your customer does not have an identification document from the supported list, refer to other available KYC methods here.

User journey

Identifying your customer with video identification with IDnow involves the following steps:

1. The customer provides the minimum required data points and their consent to Solarisbank's Terms and Conditions and data processing terms in your sign-up flow.
2. You must send the customer their unique IDnow reference (for mobile app) and URL (for web browser) to complete the identification process. Additionally, share with the customer which documents they need to present during the identification session.
3. During the identification session, the customer provides the following:
4. An identification document, such as passport or national ID card.
5. A proof of address document if their identification document does not include an address.
6. A mobile number
7. During the video session, the identification agent will verify the customer's data against their identification and collect any missing information.
8. The customer's mobile number will also be verified during the session via an SMS one-time password.

System prerequisites

Before starting the video identification process, you must implement the following requirements:

1. Technical setup:

Set up your environment and get your authentication keys. For step-by-step instructions, check the Technical setup guide.

2. Legal and compliance screens:

Build the necessary legal and compliance screens in your sign-up flow to collect your customers' consent to the necessary legal and compliance requirements. The Legal and compliance screens guide contains step-by-step instructions on how to create these screens and what they must contain.

Record the customer's consent on each screen as a UTC timestamp (e.g., 2019-01-01T00:00:00Z). Afterward, you must pass each timestamp in its respective field to Solarisbank.

• Collect the customer's consent to Solarisbank's Terms and Conditions and store the timestamp in the terms_conditions_signed_at field.
• Collect the customer's consent to data processing and store the timestamp in the data_terms_signed_at field.

Webhooks

Solarisbank recommends subscribing to the following webhook events to better automate your processes. For detailed instructions on implementing Solarisbank webhooks, check the webhooks documentation.

• IDENTIFICATION
• PERSON_CHANGED
• PERSON_DELETED
• PERSONMOBILENUMBER_CREATED
• PERSONMOBILENUMBER_DELETED

Integration flow

The following sequence diagram gives an overview of the integration flow for the video identification solution:

Integration steps

Integrate video identification by completing the following steps:

User registration

1. Collect the mandatory customer data and consent to the legal and regulatory requirements in your sign-up flow, and create a person resource for your customer by completing Step 1.

Customer identification

1. Create an identification resource for the customer by using POST Create identification.
2. Trigger the identification flow by using PATCH Request an identification.
3. Redirect your customer to the URL returned in the response of the previous call to complete the identification process.

You can find detailed descriptions of these steps and their related endpoints in the following sections.

Step 1: Collect customer data and create person resource

In this step, you must collect the mandatory data points from the customer in your sign-up flow, including all the timestamps of the customer's consent to the legal and compliance screens. Afterward, pass all the data points to Solarisbank by creating a person resource.

What is a person resource?

The person resource represents the customer's personal and financial data at Solaris. It contains all mandatory customer data, as well as links to other resources created for the customer (e.g., accounts, tax identifications). Creating a person resource is typically the first step to integrating any of Solaris's products.

Note about branching

Solaris may restrict the residency countries that are allowed for customers onboarding to a specific branch. If you attempt to create a customer with a residency country that is not allowed for the given branch, the API will return a 400 error and provide a list of allowed residency countries.

Example:

{
    "errors": [
        {
            "id": "24b0e02a-341d-40bc-9e52-0d9f8cc8c6eb",
            "status": 400,
            "code": "invalid_model",
            "title": "Invalid Model",
            "detail": "country Residency Country is not allowed for this branch,allowed residency country values for branch \"null\" are [\"DE\", \"FR\"]",
            "source": {
                "field": "country",
                "message": "Residency Country is not allowed for this branch,allowed residency country values for branch \"null\" are [\"DE\", \"FR\"]"
            }
        }
    ]
} 

Please contact your Partner Manager for information about which residency countries are allowed for your branch(es).

API reference

Visit the following link to find all the endpoints related to the person resource, including related properties and examples.

• Person resource API reference:

  • POST Create person
  • GET Retrieve a person
  • PATCH Update person

Related webhook events

• PERSON_CHANGED
• PERSON_DELETED

POST Create person

This endpoint creates a person resource for your customer. You must collect the mandatory data points from your customer in the sign-up flow and pass them to Solaris in the request body of this endpoint.

• salutation
• first_name (including all middle names as printed on the ID document)
• last_name (including all name parts as printed on the ID document)
• birth_date
• nationality ISO 3166-1 alpha-2 codes
• address (Street, Number, City, Post Code, Country, State)
• mobile_number
• data_terms_signed_at (UTC timestamp)
• terms_conditions_signed_at (UTC timestamp)

Request URL

POST /v1/persons
{
  "salutation": "MS",
  "first_name": "Jane",
  "last_name": "Doe",
  "address": {
    "line_1": "Amrumerstrasse",
    "line_2": "14",
    "postal_code": "13353",
    "city": "Berlin",
    "country": "DE"
    },
  "mobile_number": "+49301234567",
  "birth_date": "1992-12-11",
  "nationality": "DE",
  "terms_conditions_signed_at": "2022-01-01T00:00:00.000Z",
  "data_terms_signed_at": "2022-01-01T00:00:00.000Z"
}

Response example

The API returns a person object with a unique ID for the person (i.e., the person_id). You will need this id to append the person resource with additional information in the remaining steps of this guide.

200 Created
{
    "id": "7cf09c3c5547b974a664201f24b454eecper",
    "salutation": "MS",
    "title": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "address": {
        "line_1": "Amrumerstrasse",
        "line_2": "14",
        "postal_code": "13353",
        "city": "Berlin",
        "country": "DE",
        "state": null
    },
    "contact_address": {
        "line_1": null,
        "line_2": null,
        "postal_code": null,
        "city": null,
        "country": null,
        "state": null
    },
    "email": null,
    "mobile_number": "+49301234567",
    "birth_name": null,
    "birth_date": "1992-12-11",
    "birth_city": null,
    "birth_country": null,
    "nationality": "DE",
    "employment_status": null,
    "job_title": null,
    "tax_information": {
        "tax_assessment": null,
        "marital_status": "UNKNOWN"
    },
    "fatca_relevant": null,
    "fatca_crs_confirmed_at": null,
    "business_purpose": null,
    "industry": null,
    "industry_key": null,
    "terms_conditions_signed_at": "2022-01-01T00:00:00.000Z",
    "own_economic_interest_signed_at": null,
    "aml_follow_up_date": "2029-01-22",
    "aml_confirmed_on": "2022-07-22",
    "flagged_by_compliance": false,
    "expected_monthly_revenue_cents": null,
    "vat_number": null,
    "website_social_media": null,
    "business_trading_name": null,
    "nace_code": null,
    "business_address_line_1": null,
    "business_address_line_2": null,
    "business_postal_code": null,
    "business_city": null,
    "business_country": null,
    "business_state": null,
    "screening_progress": "NOT_SCREENED",
    "risk_classification_status": "NOT_SCORED",
    "customer_vetting_status": "NOT_VETTED",
    "annual_income_range": null,
    "data_terms_signed_at": "2022-01-01T00:00:00.000Z",
    "branch": null,
    "birth_province": null,
    "birth_post_code": null,
    "socioprofessional_category": null,
    "purpose_of_account_opening": null,
    "main_income_source": null,
    "work_country": null,
    "work_province": null,
    "self_declared_as_pep": null,
    "international_operativity_expectation": [],
    "registration_number": null,
    "legitimation_valid_until": null
}

Click here to view the full API reference

PATCH Update person

This endpoint updates one or more properties on a person resource. You can only update the following properties using this endpoint:

• title
• salutation
• address (line_1, line_2, postal_code, city, state, country)
• contact_address (line_1, line_2, postal_code, city, state, country)
• employment_status
• job_title
• email
• tax_information (tax_assessment, marital_status)
• fatca_relevant
• fatca_crs_confirmed_at
• business_purpose
• industry
• industry_key
• own_economic_interest_signed_at
• aml_confirmed_on (only with today or tomorrow's date)
• expected_monthly_revenue_cents
• vat_number
• website_social_media
• business_trading_name
• nace_code
• business_address_line_1
• business_address_line_2
• business_postal_code
• business_city
• business_country
• annual_income_range
• data_terms_signed_at
• branch
• birth_province
• birth_post_code
• socioprofessional_category
• purpose_of_account_opening
• main_income_source
• work_country
• work_province
• self_declared_as_pep
• international_operativity_expectation
• registration_number

Request URL

PATCH /v1/persons/{id}

Click here to view the full API reference

Step 2: Create the identification resource for the customer

In this step, you must create an identification resource for your customer to initiate the KYC process.

API reference

Visit the following link to find all the endpoints related to the different methods of customer identification (KYC), including related properties and examples.

• Customer identification (KYC) API reference

Related webhook events

• IDENTIFICATION

POST Check identification eligibility (Optional)

As an initial verification step, you can check whether the relevant customer is eligible for the given identification method or not based on their data, such as nationality, place of residence, or identification document.

This endpoint validates whether the person specified in the request URL is eligible to complete a given identification method. You must add the identification method for which you want to check the customer's eligibility in the request body.

Request example

POST /v1/persons/{person_id}/identification_eligibility_checks
{
  "method": "idnow"
}

Response example

The API call returns a response as to whether the person is eligible for identifying with a particular method or not. In case of failure, a reason is provided in the field failure_reason.

{
    "method": "idnow",
    "eligible": true,
    "failure_reason": "null"
}

Click here to view the full API reference

GET List supported documents for a person identification

Prior to redirecting your customer to complete the identification process, you can fetch the supported documents to share it with the customer beforehand.

This endpoint returns an array of document types that a customer may use to identify themselves along with a list of allowed issuing countries. The issuing_countries are provided as ISO country codes (ISO-3166-1 alpha 2). If the customer does not provide a supported document type in the identification process, then their identification will eventually fail.

Request URL

GET /v1/persons/{person_id}/identifications/{id}/supported_documents

Click here to view the full API reference

POST Create identification

This endpoint creates an identification resource for the person specified in the request URL. You must add the following properties in the request body:

• method: The identification method, select idnow.
• language: The customer's preferred language for the identification process. Possible values are EN and DE.
• proof_of_address_type: The type of document submitted by the customer as a proof of address. This field is mandatory if the customer's identification document does not include their address.
• proof_of_address_issued_at: The date when the proof of address document was issued. This field is mandatory if the customer's identification document does not include their address. It must NOT be older than 6 months.

Request example

POST /v1/persons/{person_id}/identifications
{
  "method": "idnow",
  "language": "DE",
  "proof_of_address_type": "GAS_BILL",
  "proof_of_address_issued_at": "2022-03-03"
}

Response example

The API call returns an identification object with a unique id, the identification_id, as well as the identification status, set initially to created.

{
    "id": "6dc54352d6793a892e0702850d07b831cidt",
    "reference": null,
    "url": null,
    "status": "created",
    "completed_at": null,
    "method": "idnow",
    "proof_of_address_type": "GAS_BILL",
    "proof_of_address_issued_at": "2022-03-03",
    "language": "DE",
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null
}

Click here to view the full API reference.

PATCH Request person identification

This endpoint triggers the identification flow with IDnow for the specific customer. The status of the identification will change to pending after calling this endpoint.

Request URL

PATCH /v1/persons/{person_id}/identifications/{id}/request

Response example

The API call returns the identification object with the status pending. The status remains pending until the customer completes the identification. Additionally, the payload includes the url (valid for 14 days), which the customer can use to identify via the web browser, and the reference, which is the identification token (format: ABCDEFGH ), an internal IDnow identifier the customer can use to video-identify through IDnow's mobile application (available on iOS and Android).

{
    "id": "6dc54352d6793a892e0702850d07b831cidt",
    "reference": "TST-KCCEY",
    "url": "https://go.test.idnow.de/solarisbankvideoidentsandbox/identifications/6dc54352d6793a892e0702850d07b831cidt",
    "status": "pending",
    "completed_at": null,
    "method": "idnow",
    "proof_of_address_type": "GAS_BILL",
    "proof_of_address_issued_at": "2022-03-03",
    "language": "DE",
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null,
    "estimated_waiting_time": 60
}

Click here to view the full API reference.

Redirect the customer to IDnow to complete the identification process. You can also share with the customer the supported documents that they must present during the session.

IDnow Video-identification process

• Before being put in touch with a video identification agent, your customer is redirected to an IDnow-branded landing page, where they are asked to give their consent to IDnow's Terms & Conditions and confirm that they have a valid ID document at hand. This ID document will be shown via webcam to the agent during the video identification.
• Additionally, your customer must also provide their valid mobile number during their identification. IDnow agent will verify this mobile number by sending an SMS OTP, which the customer will need to provide during the call. Solarisbank will re-use the verified mobile number of a successful IDnow video identification as the customer's verified mobile number.
• Once connected with an IDnow agent, your customer is greeted on behalf of Solarisbank ( « You are identifying for a service of Solarisbank » ) or on your behalf ( « You are identifying for a service of /Your Brand Name/, empowered by Solarisbank » ), depending on the setup you have agreed upon with Solarisbank.
• The call takes place either in English or in German. The agent goes on to verify the customer's mobile number and the customer's data, such as first_name and last_name. In addition, the agent populates specific additional attributes of the person resource during the call.

GET Retrieve person identification

This endpoint returns a completed person identification (i.e., the person identification process was successful). If you use the include_documents filter, this method will also return the documents submitted by the customer during the identification process.

To download any of the documents submitted during the identification process, you can use the document unique id and download the files using the Document resource endpoints.

Request URL

GET /v1/persons/{person_id}/identifications/{id}

Response example

{
  "id": "6dc54352d6793a892e0702850d07b831cidt",
  "reference": "TST-KCCEY",
  "url": "https://go.test.idnow.de/solarisbankvideoidentsandbox/identifications/6dc54352d6793a892e0702850d07b831cidt",
  "status": "successful",
  "completed_at": "2022-07-14T18:18:28.000Z",
  "method": "idnow",
  "proof_of_address_type": "GAS_BILL",
  "proof_of_address_issued_at": "2022-03-03",
  "language": "DE",
  "person_id": "7cf09c3c5547b974a664201f24b454eecper",
  "address": {
    "line_1": "Amrumerstrasse",
    "line_2": "14",
    "postal_code": "13353",
    "city": "Berlin",
    "country": "DE"
  },
  "documents": [
    {
      "id": "448b75fa1c57eecda41d91c66c22faa6cdoc",
      "name": "file1.pdf",
      "content_type": "application/json",
      "document_type": "KYC_REPORT",
      "size": 803580
    },
    {
      "id": "94eb22a9311be9a1fbb698c448b0b337cdoc",
      "name": "file2.jpg",
      "content_type": "image/jpeg",
      "document_type": "SIGNATURE",
      "size": 25349
    }
  ]
}

Click here to view the full API reference.

Other identification endpoints

• GET Index identifications for a person
• POST Upload documents for a person identification
• GET List the IDnow attempts of a person identification
• GET List IDnow legitimation data.

After the customer successfully complete the video identification process, you can download the documents submitted during the identification session using our document-related endpoints here.

Testing

Idnow offers different test scenarios to simulate different outcomes for the identification process. To trigger a test scenario, you can create a person resource and set the first_name or last_name to one of the following prefixes and the name of the relevant test case.

Test scenarios

The available test scenarios are as follows:

Happy path test tutorial

Complete the following steps to simulate a successful identification workflow with IDnow on Sandbox.

1. Create a person

Create a person resource using the following endpoint and set the value of the first_name field to X-MANUALTEST-HAPPYPATHto trigger the HAPPYPATH scenario and any value for the last_name in the request body.

Request

POST /v1/persons
{
   "first_name": "X-MANUALTEST-HAPPYPATH",
   "last_name": "{{random_name}}"
}

Response

{
    "id": "f281052483ee30c274bdb7cdc9e8f348cper",
    "salutation": null,
    "title": null,
    "first_name": "X-MANUALTEST-HAPPYPATH",
    "last_name": "{{random_name}}",
    "address": {
        "line_1": null,
        "line_2": null,
        "postal_code": null,
        "city": null,
        "country": null,
        "state": null
    },
    "contact_address": {
        "line_1": null,
        "line_2": null,
        "postal_code": null,
        "city": null,
        "country": null,
        "state": null
    },
    "email": null,
    "mobile_number": null,
    "birth_name": null,
    "birth_date": null,
    "birth_city": null,
    "birth_country": null,
    "nationality": null,
    "employment_status": null,
    "job_title": null,
    "tax_information": {
        "tax_assessment": null,
        "marital_status": null
    },
    "fatca_relevant": null,
    "fatca_crs_confirmed_at": null,
    "business_purpose": null,
    "industry": null,
    "industry_key": null,
    "terms_conditions_signed_at": null,
    "own_economic_interest_signed_at": null,
    "aml_follow_up_date": "2029-01-22",
    "aml_confirmed_on": "2022-07-22",
    "flagged_by_compliance": false,
    "expected_monthly_revenue_cents": null,
    "vat_number": null,
    "website_social_media": null,
    "business_trading_name": null,
    "nace_code": null,
    "business_address_line_1": null,
    "business_address_line_2": null,
    "business_postal_code": null,
    "business_city": null,
    "business_country": null,
    "business_state": null,
    "screening_progress": "NOT_SCREENED",
    "risk_classification_status": "NOT_SCORED",
    "customer_vetting_status": "NOT_VETTED",
    "annual_income_range": null,
    "data_terms_signed_at": null,
    "branch": null,
    "birth_province": null,
    "birth_post_code": null,
    "socioprofessional_category": null,
    "purpose_of_account_opening": null,
    "main_income_source": null,
    "work_country": null,
    "work_province": null,
    "self_declared_as_pep": null,
    "international_operativity_expectation": [],
    "registration_number": null,
    "legitimation_valid_until": null
}

2. Create an identification resource

Create an identification resource and specify the identification method as idnow in the request body of the following endpoint. Add the person_id returned from the previous API call to the request URL.

Request example

POST /v1/persons/{person_id}/identifications
{
   "method": "idnow"
}

Response

{
    "id": "b80ea8c7f76909749763e77f3efc2c87cidt",
    "reference": null,
    "url": null,
    "status": "created",
    "completed_at": null,
    "method": "idnow",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "language": null,
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null
}

3. Trigger the identification

To trigger the identification flow, call the following endpoint and add the person_id and the identification id returned from the previous API calls to the request URL.

Request example

PATCH /v1/persons/{person_id}/identifications/{id}/request

Response example

The API call will return the details of a test video identification session, including url (for web browser) and reference (for mobile app).

{
    "id": "b80ea8c7f76909749763e77f3efc2c87cidt",
    "reference": "TST-CHMUV",
    "url": "https://go.test.idnow.de/solarisbankvideoidentsandbox/identifications/b80ea8c7f76909749763e77f3efc2c87cidt",
    "status": "pending",
    "completed_at": null,
    "method": "idnow",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "language": null,
    "iban": null,
    "terms_and_conditions_signed_at": null,
    "authorization_expires_at": null,
    "confirmation_expires_at": null,
    "estimated_waiting_time": 60
}

4. Complete the identification flow

Depending on whether you want to test the identification on the web browser or IDnow mobile application, you can click on the URl to go to the web browser session or enter the reference in the mobile app.

Afterwards, you'll be directed to the video identification flow where you have to:

1. Enter any mobile number that starts with 0 or you can use the static value: +15550101, check all boxes and click on Start identification.

2. The flow will start and you'll start seeing different pop-ups with instructions, simulating what would happen in a real video identification session.
3. The flow goes to the successful stage and you have to confirm the identification by entering the following static Ident code: 123456.

4. The successful identification screen will appear.

5. Afterward, you can call the following endpoint, which will show the identification status as successful. Additionally, the webhook event IDENTIFICATION will be triggered as well after a successful identification.

Request

GET /v1/persons/{person_id}/identifications

Response

[
    {
        "id": "b80ea8c7f76909749763e77f3efc2c87cidt",
        "reference": "TST-CHMUV",
        "url": "https://go.test.idnow.de/solarisbankvideoidentsandbox/identifications/b80ea8c7f76909749763e77f3efc2c87cidt",
        "status": "successful",
        "completed_at": "2022-07-22T09:28:13.000Z",
        "method": "idnow",
        "proof_of_address_type": null,
        "proof_of_address_issued_at": null,
        "language": null,
        "iban": null,
        "terms_and_conditions_signed_at": null,
        "authorization_expires_at": null,
        "confirmation_expires_at": null
    }
]

What's next?

Congratulations! You've successfully integrated video identification.

Check the following appendix section for additional information on enums and testing data.

For an overview of other KYC methods, check the identity products overview page.

Useful resources

Check the following links for additional related guides and API reference documentation:

• Customer identification (KYC) API reference
• Person Documents API reference

Appendix I: Enums

Document types

The following table includes the possible values for the field document_type and their descriptions.

Idnow status

The following table includes the possible values for the field status for the video identification process carried out by IDnow and the related description of each status.

IDnow provides a reason for the canceled and aborted status. No reason can be disclosed for the final failed status.

IDnow failure codes

The following table includes the possible failure or cancellation reasons for IDnow video identification.

Identification documents

1. List of the accepted passports for videoIdent: here
2. List of accepted passports for postIdent: here
3. Search for a identification document: here

List of passports with address

The following table shows the list of documents, that has the address included in the identification document, and allows you to perform identification without the proof of address document.