AutoIdent via IDnow

This guide describes how to implement AutoIdent via IDnow for completing the Re-Know Your Customer (Re-KYC) process in your solution

Introduction

User journey

Below are the steps involved in performing customer KYC using AutoIdent via IDnow:

1. You initiate the identification request with Solaris, and Solaris forwards the customer data to IDnow.
2. Customer will be redirected to IDnow to complete the identification process via the IDnow SDK. Note the list of accepted documents by IDnow here.
3. IDnow will prompt the customer to begin an AutoIdent session (either in English or in German). The customer must provide the government-issued identification document (e.g., Passport, ID-card, Driver's license)

4. During the AutoIdent session, the following steps will occur:

   • Customer will provide the necessary details to start the identification process.
   • Customer will scan the ID document and take a liveness check.
5. Once the process completes, the customer will be redirected to your frontend.

Eligibility

This identification method is available for customers residing in Germany. It cannot be used for first-time identification but is valid for re-KYC processes and specific authentication use cases, rather than full identification. For further details and guidance on its applicability, please consult your Partner Manager.

IDnow integration

In addition to the Solaris technical prerequisites, you must also integrate IDnow into your solution. You can achieve this either using IDnow's mobile SDKs (available for iOS and Android) or using their webview APIs (for desktop).

For instructions on how to set up IDnow in your solution, see the following IDnow documentation links:

• Mobile:

  • iOS SDK
  • Android SDK

• Mobile:

  • react-AutoIdent

• Desktop (Webview):

  • API documentation

Webhooks

You must subscribe to the following webhook events to ensure that your system receives notifications for crucial events in the identification process. For detailed instructions on implementing Solaris webhooks, see the webhooks documentation.

• IDENTIFICATION
• PERSON_CHANGED

Create the identification resource for the customer

Initiate the Re-KYC process by creating an identification resource for the customer. This resource sets various parameters for the identification process and stores the results returned by IDnow.

API reference

For a complete list of endpoints, properties, and examples related to customer identification (KYC), visit the following link:

• Customer identification (KYC) API reference

Related webhook events

• IDENTIFICATION

POST Create identification

Call this endpoint to create an identification resource for the person specified in the request URL, and add the following properties to the request body:

• method: The identification method to use. In this case, set the value to idnow_autoident.
• language: The customer's preferred language for the identification process. Possible values are EN and DE.

Request example

POST /v1/persons/{person_id}/identifications
{
  "method": "idnow_autoident",
  "language": "DE",
}

Response example

The API call will return an identification object with a unique id (i.e., identification_id) and an initial status of created.

{
    "id": "53e2e4c098045c12cd7249b2b9b2de51cidt",
    "reference": null,
    "url": null,
    "status": "created",
    "completed_at": null,
    "method": "idnow_autoident",
    "proof_of_address_type": "GAS_BILL",
    "proof_of_address_issued_at": "2022-09-21",
    "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

Call this endpoint to trigger the identification flow with IDnow for the specific customer.

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 will remain pending until the customer completes the identification. Additionally, the payload includes the following key properties:

• url The URL to complete the identification process in webview.
• reference: An internal IDnow identification token for the session (format: ABCDEFGH). Do not share this with the customer under any circumstances.

{
    "id": "53e2e4c098045c12cd7249b2b9b2de51cidt",
    "reference": "TS2-ADLSU",
    "url": "https://go.test.idnow.de/solarisbankautosandbox/identifications/53e2e4c098045c12cd7249b2b9b2de51cidt",
    "status": "pending",
    "completed_at": null,
    "method": "idnow_autoident",
    "proof_of_address_type": "GAS_BILL",
    "proof_of_address_issued_at": "2022-09-21",
    "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.

GET Retrieve person identification

Once the identification completes successfully, call this endpoint to retrieve the finalized person identification. If you use the include_documents filter, the API will also return the documents submitted by the customer during the process. To download any of these documents, use the document's unique id to call the document download endpoints.

Request URL

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

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 AutoIdent process, you can download the documents submitted during the identification session using our document-related endpoints here.

Testing

IDnow offers 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. The format is as follows:

{{Test scenario}}-{{Test case}}

Example:

X-MANUALTEST-HAPPYPATH

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

2. Create an identification resource

Create an identification resource and specify the identification method as idnow_autoident 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_autoident"
}

3. Trigger the identification

To trigger the identification flow, call the following endpoint, using the person_id and the identification id returned from the previous API call in 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 AutoIdent session, including url (for web browser) and reference (for mobile app).

{
    "id": "24e9967b0d14ac8b123e45efccbf8164cidt",
    "reference": "TS2-YDEKT",
    "url": "https://go.test.idnow.de/solarisbankautosandbox/identifications/24e9967b0d14ac8b123e45efccbf8164cidt",
    "status": "pending",
    "completed_at": null,
    "method": "idnow_autoident",
    "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 AutoIdent 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 AutoIdent session.
3. The flow goes to the successful stage and the verification data will be submitted.
4. 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 URL:

GET /v1/persons/{person_id}/identifications

What's next?

Congratulations! You have successfully completed the customer KYC process using IDnow AutoIdent

Check the following appendices for more information on enum values 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
• IDnow AutoIdent FAQs

Appendix I: Enums

Document types

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

IDow status values

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

IDnow provides a reason whenever the identification has a canceled or aborted status. No reason can be disclosed for the final failed status.

IDnow failure codes

The following table describes the possible failure or cancellation reasons for AutoIdent.

Identification documents

1. List of accepted ID documents for AutoIdent via IDnow: here

List of passports with address

The following table lists all ID types that include the bearer's address, which you can use to perform identification without having to provide a proof of address document.

Appendix II: IDnow status transitions

Only the following transitions can occur during an IDnow identification session:

Case 1: Happy path

created → pending → successful

Case 2: Suspicion of fraudulent behavior by IDnow that was not confirmed. Identification was marked as successful after review.

created → pending → canceled → successful

Case 3: Fraudulent behavior was detected during a review of an identification that was previously marked as successful.

created → pending → successful → canceled