Introduction

IDnow exposes its identity verification services via a standardized programmatic interface to its clients. We offer a RESTful API that is based on HTTP requests and JSON responses. This documentation provides you with an overview of the API endpoints and information on implementing our services in your own IT infrastructure.

Postman

For getting to know the IDnow API endpoints and result data, we recommend using the Postman tool. It helps with running and debugging your API requests. IDnow provides its own Postman Collection of API requests which you can simply access by clicking Run in Postman above.

This collection is also the basis of this documentation and you will find every endpoint described here being readily available in our collection.

AutoIdent overview

IDnow AutoIdent offers a fully automated solution to identify a person.

The process automatically performs these steps:

Determines the kind of document used (e.g. passport, ID-card, driver license)
Determines the version of the document (e.g. German passport)
Retrieves the data from the document
Performs a biometric comparison
Executes a liveness detection
Verifies the genuineness of the document used during the process

IDnow offers mobile Apps for iOS and Android as well as mobile SDKs for integration into customer-specific apps to support the AutoIdent process.

Getting started

Before you can use the requests, a proper environment has to be set up. An environment holds parameters for setting your company name, API Key, login-token and the gateway host for your requests. The parameters in the API URL are placeholders. The applicable values for the placeholders are automatically used in your requests.

The structure of our API URL looks like this:

{{GATEWAYHOST}}/api/v1/{{CUSTOMER}}/

The following table shows those parameters with demo data. The IDnow collection holds global variables for authentication and provides two environments, one for testing and one for production calls. With our demo data and test environment you are able to make example requests from the start, without having to write any code or use your real data (except your API Key).

Parameter	Value
{{CUSTOMER}}	democompany
{{GATEWAYHOST}}	https://gateway.test.idnow.de
{{APIKEY}}	Your private API key.
{{LOGIN-TOKEN}}	The authentication token. Needs to be included in every request header.

Protocol and Port

To ensure that all parameters are encrypted, all requests to the IDnow server must be performed using HTTPS! HTTP is not allowed. The port for all requests is: 443.

Persistence

Item	Info
JWT	The authentication token has an idle time of 60 minutes after which it expires.
Ident	An Ident has a lifetime of 90 days if data retention policies do not dictate otherwise.

Ident Lifecycle

While it is possible to create an Ident with existing user data, it is not possible to retrieve an Ident which has not at least started the IDnow verification process and still is in status created. Once an Ident is in the verification process, it goes through various statuses depending on the actions of the user and the agent, who is verifying the identity of the user.

Linking a Transaction Number to an existing User

Let's assume there is an existing user with complete data in your database whose identity you need to verify. IDnow allows for adding a unique transactionnumber (recommended) of your choice to every Ident creation request. You can use this number to associate the Ident e.g. with the corresponding entity in your system. When retrieving an Ident, this number will be provided back to you as the transactionnumber in the JSON body.

Transaction Number

It is required that the ID generated by your system meets these requirements: - It is unique per Ident that you create. - It is not guessable. - It has a maximum length of 255 characters. A typical example is a UUID (version 4) as the value. - It may contain only the following characters: [a-z][A-Z][0-9][_-] to be compatible with the IDnow system.

The transaction number is case-insensitive and is being used in the API URL itself. In the following example, the transactionnumber has the value: demo-transactionxxnbr1.

Authentication

Before it is possible to send any request successfully, the value for the API Key has to be set in your environment. With the API Key set, the first request must be to authenticate and obtain a JWT. The JWT is necessary for accessing the API with any subsequent request.

Request: POST Company Login

Add this value to your global variable LOGIN-TOKEN. It will then be automatically used in the header as the value for the parameter: X-API-LOGIN-TOKEN for every following request you send.

The JWT will be invalidated on the server side if it has not been used for at least one hour. If you request our API with an expired token, your requests will get a 401 Unauthorized error and you have to authenticate again. Using a false Customer results also in an 401 Unauthorized error.

If the request was successful, you receive the response code: HTTP/1.1 200 OK. The response body contains a key / value pair for the JWT, with the key being: authToken.

curl -X POST \
  'http://{{GATEWAYHOST}}/api/v1/{{CUSTOMER}}/login' \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: e0fccb61-5e81-4ce2-b4ae-86644a65b225' \
  -H 'cache-control: no-cache' \
  -d '{
    "apiKey": "{{APIKEY}}"
}'

HTTP Request

POST {{GATEWAYHOST}}/api/v1/{{CUSTOMER}}/login

URL Parameters

None

URL Headers

Parameter	Value	Description
Content-Type	application/json	(REQUIRED) The media type

URL Responses

HTTP Response - 200 OK

{
"authToken": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJkZS5pZGYXRld2F5IiwiYXVkIjoiZGUuaWRub3cuYXBwbGljYXRpb24iLCJleHAiOjE1NTk4MDYyMDIsImp0aSI6Im9qOVJxZHpFaHJKdjI2d0tSWWR5vdy5nCJpYXQiOjE1NTk4MDI2MDIsIm5iZiI6MTU1OTgwMjQ4Miwic3ViIjoiZGVtb3NlY3VyaXR5ZmVhdHVyZXMi0eXBlIQ09NUEFOWSIsInBlcm1pc3Npb25zIjoiQUxMIn0.s0nI00Uz-E6Gk4crFuzFHZT9dNu7sspUzfbtvXRTzwnQ9DN3gntTwUkKAJBGlyILdocAwj30BoG7J7L0rWTOyg"
}

HTTP Response - 500 Error

{
    "errors": [
        {
            "cause": "INTERNAL_SERVER_ERROR",
            "errorType": null,
            "id": "61262858",
            "key": null,
            "message": "An internal server error has occured",
            "translationKey": null
        }
    ]
}

REST API Endpoints

AutoIdent REST API endpoints

Errors

The AutoIdent API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Mobile SDK

IDnow provides a native mobile SDK for iOS and Android platform. Using the SDK you can integrate IDnow technology seamlessly into your own mobile app. This will allow your users to identify themselves without leaving your app.

There are various possibilities to integrate our solutions in your application. You can adjust all colors, fonts and copies.

We support:

CocoaPods
Proguard and Multidex
Native and Hybrid (Cordova, React, Xamarin etc.) Apps
Objective-C, Swift and Royal Studio

Android SDK

Overview

The AutoIdent Android SDK supports the Android Studio integrated development environment.

Download

You can download the AutoIdent Android SDK from GitHub: Android SDK on GitHub

You can also download directly a zip file with the latest version of the Android SDK: Android SDK zip archive

Requirements

The following are the minimal requirements to be able to use the AutoIdent Android SDK:

Minimum Android SDK version: 18 (>= Android 4.3)
Recommended Android SDK version: 25 (>= Android 7.0 Nougat)
Internet connection, with communication open via standard SSL port 443

Android manifest files

The following permissions are required to be set:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.FLASHLIGHT" />

If VideoIdent will be used, the following Audio permissions are required as well:

<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />

For some audio devices, additional Bluetooth permissions might be required:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

When using an Android LibraryProject, all the Activities, Services and <uses-feature> from the LibraryProject (SDK) must be mentioned in your App Android Manifest. The simplest way to do this is just to copy the corresponding part of the IDnowSDK AndroidManifest.xml.

Android Studio support

How to use the .aar file:

Copy the idnow-android-.aar into the apps libs folder.
In your app.gradle add:

repositories {
    flatDir {
        dirs 'libs' // This way we can find the .aar file in libs folder
    }
}

In the dependencies part of your app.gradle add:

compile 'com.example.library:idnow-android-<version>@aar' (replace the 'com.example.library' with your packagename)

Additional dependencies to add in your app.gradle:

    compile 'de.idnow.sdk:idnow-android-<version>@aar'
    compile 'org.slf4j:slf4j-android:1.7.12'
    compile 'com.squareup.retrofit:retrofit:1.9.0'
    compile 'com.squareup.okhttp3:okhttp:3.12.1'
    compile 'com.googlecode.libphonenumber:libphonenumber:8.4.2'

App Bar

During the use of the SDK the app is NOT showing an App Bar since the ident follows exact predefined steps the user can't influence and because there is nothing to search for.

SDK size

By default the SDK has a size of roughly 17MB. This includes the necessary native code for WebRTC. If you need to lower the size of your delivered APK for some reason, we advice to use APK splitting.

You can do that by adding the following code to your project:

android {
    // Some other configuration here...
    splits {
        abi {
            enable true
            reset()
            include 'x86', 'armeabi', 'armeabi-v7a', 'mips'
            universalApk false
        }
    }
}

Multidex support

Your project might require the usage of multidex if it comes over 65k methods. Please see Android multidex for details.

Proguard support

A proguard file is supplied in the project SDK as well.

Initialize instance

Initialize IDnowSDK instance

IDnowSDK.getInstance().initialize(<Activity>, "<companyid>");

To create an instance of the IDnow SDK, perform the following call and provide the companyid, which was provided to you during setup, as well as an activity that receives callbacks. IDnowSDK is a singleton class, so whenever you need to call it just do so with IDnowSDK.getInstance().

Configure the instance

Configure IDnowSDK instance

IDnowSDK.setShowVideoOverviewCheck(<true/false>, <Context>);
IDnowSDK.setShowErrorSuccessScreen(<true/false>, <Context>);

Set the static parameters for the SDK usage. Context has to be passed, as parameters are persisted in Preferences. You can decide whether to let the user confirm legal agreements (setShowVideoOverviewCheck). You also can decide if after the identification the IDnow Error/Success screen is shown, or if the callback to your app is triggered right after identification is finished.

Start identification

Start identification process

IDnowSDK.getInstance().start(<Your transaction token>);

To start the identification you must pass your transaction token.

Example

try {
    // Initialize with your activity which will handle the SDK callback and pass the id of your company.
    //  IDnowSDK is a singleton class, so just call it with IDnowSDK.getInstance()
    IDnowSDK.getInstance().initialize(StartActivity.this, "ihreBank");

    // Set the transactionToken, for example from a TextField
    IDnowSDK.setTransactionToken(editTextToken.getText().toString(), context);

    // You can decide whether to let the user confirm the legal points.
    IDnowSDK.setShowVideoOverviewCheck(true, context);

    // Same goes to the success screen. If none is shown, the app sends the results right back.
    // The defaults for the both parameters are "true";
    IDnowSDK.setShowErrorSuccessScreen(true, context);

    // Optionally set against which environment the app has to test. Possibilities are DEV, TEST, LIVE, with LIVE being the default.
    IDnowSDK.setEnvironment( Server.TEST );

    // To actually start the identification process, pass the transactionToken.
    IDnowSDK.getInstance().start(IDnowSDK.getTransactionToken(context));
} catch (Exception e) {
    // The SDK checks the input parameters and throws an exception if they don't seem right.
    e.printStackTrace();
}

The SDK checks the input parameters and throws an Exception if something is deemed not right, to provide you with quick feedback. Handle it as desired.

Identification result

To handle the results of the identification, implement the standard onActivityResult function in your activity.

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data)
    {
        if (requestCode == IDnowSDK.REQUEST_ID_NOW_SDK)
        {
            if (resultCode == IDnowSDK.RESULT_CODE_SUCCESS)
            {
                if (data != null)
                {
                    String transactionToken = data.getStringExtra(IDnowSDK.RESULT_DATA_TRANSACTION_TOKEN);
                    Log.v(TAG, "success, transaction token: " + transactionToken);
                }
            }
            else if (resultCode == IDnowSDK.RESULT_CODE_CANCEL)
            {
                if (data != null)
                {
                    String transactionToken = data.getStringExtra(IDnowSDK.RESULT_DATA_TRANSACTION_TOKEN);
                    String errorMessage = data.getStringExtra(IDnowSDK.RESULT_DATA_ERROR);
                    Log.v(TAG, "canceled, transaction token: " + transactionToken + “, error: “ + errorMessage);
                }
            }
            else if (resultCode == IDnowSDK.RESULT_CODE_FAILED)
            {
                if (data != null)
                {
                    String transactionToken = data.getStringExtra(IDnowSDK.RESULT_DATA_TRANSACTION_TOKEN);
                    String errorMessage = data.getStringExtra(IDnowSDK.RESULT_DATA_ERROR);
                    Log.v(TAG, "failed, transaction token: " + transactionToken + “, error: “ + errorMessage);
                }
            }
            else
            {
                Log.v(TAG, "Result Code: " + resultCode);
            }
        }
    }

Additional settings

You can set the connection type to use: Either use websockets (default) or long polling.

IDnowSDK.setConnectionType(IDnowSDK.ConnectionType.LONG_POLLING, context);

You can force one of the environments to use. Default is to determine this by the token used.

IDnowSDK.setEnvironment(IDnowSDK.Server.TEST);

You can also disable logging of the SDK:

IDnowSDK.disableLogging();

You can set to use your own servers. When this setting is enabled, apiHost, webHost and websocketHost must also be set:

IDnowSDK.setEnvironment(IDnowSDK.Server.CUSTOM);
IDnowSDK.setApiHost("https://api.yourserver.com", context);
IDnowSDK.setWebHost("https://www.yourserver.com", context);
IDnowSDK.setWebsocketHost("https://websocket.yourserver.com", context);
IDnowSDK.setVideoHost("https://video.yourserver.com", context);
IDnowSDK.setStunHost("video.yourserver.com", context);
IDnowSDK.setStunPort(3478, context);

Using IDnow with other native libraries

For Videostreaming the Idnow SDK uses IceLink which come with native libs. If your app uses other 3rd party libs that come with their own native libs, it's possible that you get an UnsatisfiedLinkError. This means that the native lib folders shipped by your 3rd party lib don't match the native lib folders shipped by the Idnow SDK. Currently the Idnow SDK comes with the following folders: armeabi, armeabi-v7a, arm64-v8a and x86. If your 3rd party lib only supports some of the architectures but not others (e.g. armeabi, x86 but not armeabi-v7a), you have to exclude the other folders of the Idnow SDK in your build.gradle (in this example: armeabi-v7a) with the following command:

android {
    //...
    packagingOptions {
        exclude "lib/armeabi-v7a/"
    //...
}

If it's the other way round (your 3rd party lib ships more than armeabi, armeabi-v7a, arm64-v8a and x86, you have to exclude these folders, so the remaining folders match the IdNow SDK folders. For further reading please see ABI Management.

UI configuration

App icon and logo

A single icon is used as the app launcher icon and logo. You can overwrite it, if you provide assets, named "ic_launcher.png" in the drawable folders, in the following sizes:

mdpi: 48px * 48px
hdpi: 72px * 72px
xhdpi: 96px * 96px
xxhdpi: 144px * 144px
xxxhdpi: 192px * 192px

Colors

The IDnow SDK is designed with colors following the IDnow corporate design. You can use the SDK without making any adaptions to the colors at all. If, however you want the SDK screens to appear in different colors you can make the following changes:

text_default

Used as default color for display and editable texts Default: a nearly black color Recommendation: Should be some kind of a dark color that does not collide with white color.

primary

Optional color, that replaces the default brand color. Default: an orange color Used in headlines, checkboxes, links, alerts etc. Recommendation: Should be a color that does not collide with white color.

proceed_button_background

Background color for confirmation/continue button, which is usually placed at the bottom of a screen Default: the primary color (see above)

failure

Replaces the text color in the result screen, when an identification failed. Default: A red color

success

Replaces the text color in the result screen, when an identification was successful. Default: A green color

screenshots

Since pictures say more than words, here are some screenshots:

Overview check screen

Connecting to video identification

Succesful identification

Overwriting default colors

This is how the colors.xml can look like:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- Used by theme as default color for display and editable texts -->
    <color name="text_default">#4A4A4A</color>
    <!-- Primary color is used for headlines and links -->
    <color name="primary">#F95602</color>
    <!-- background color for confirmation/continue button, which is usually placed at the bottom of a screen -->
    <color name="proceed_button_background">@color/primary</color>
    <!-- "Wiederholen" button when a photo was taken in photo ident -->
    <color name="photo_ident_retake_button_background">@color/text_default</color>
    <!-- Colors of the result screen -->
    <color name="success">#A4AC49</color>
    <color name="failure">#E0727A</color>
</resources>

App theme

This is themes.xml of the SDK:

<resources>
    <style name="IdnowSdkTheme" parent="@android:style/Theme.Holo.Light">
        <item name="android:textColor">@color/text_default</item>
        <item name="android:editTextStyle">@style/IdnowSdkTheme.EditText</item>
    </style>
    <style name="IdnowSdkTheme.EditText" parent="android:Widget.EditText">
        <item name="android:textColor">@color/text_default</item>
    </style>
</resources>

As you can see, the theme is based on Holo Light. The only changes made here are applying color "text_default" to standard text elements and edit text fields.

You have these three options: * By not specifying a theme at all, the SDK's theme is used for the whole app. * Inheriting from the SDK's theme. Here is a usage example (themes.xml):

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <style name="MyAppTheme" parent="@style/IdnowSdkTheme">
    <!-- Your definitions here -->
    </style>
</resources>

Applying your own theme. In this case, it is your own responsibility to apply color "text_default" for standard and edit text elements.

Action bar

Here an example on how to set custom action bar colors when using Holo Light theme (themes.xml):

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <style name="MyAppTheme" parent="@style/IdnowSdkTheme">
        <!-- Applying custom actionbar style -->
        <item name="android:actionBarStyle">@style/MyAppTheme.ActionBar</item>
    </style>

    <style name="MyAppTheme.ActionBar" parent="@android:style/Widget.Holo.Light.ActionBar">
        <!-- Specify background color of actionbar -->
        <item name="android:background">@color/primary</item>
        <item name="android:titleTextStyle">@style/MyAppTheme.ActionBar.Title</item>
    </style>

    <style name="MyAppTheme.ActionBar.Title" parent="@android:style/TextAppearance.Holo.Widget.ActionBar.Title">
        <!-- Specify text color of actionbar -->
        <item name="android:textColor">@color/white</item>
    </style>
</resources>

Multilanguage support

The SDK supports English, German, French, Spanish and Italian texts.

Application samples

A sample application showing the use of the Android SDK can be downloaded here: Android demo application

iOS SDK

TODO

Glossary

In this section, we would like to introduce our wording used throughout this documentation for a better understanding of the data entities you will be handling when requesting our API services:

Term	Description
Company	Client of IDnow (e.g. a bank) who uses the services of IDnow to verify the identity of their users.
Customer	This value is a `string` that your company receives from IDnow during account setup. It is being used in the API URL of your requests. A synonym for this value is `shortname`, which is being used as a key in our API responses.
API Key	The API key is required for authenticating your application and accessing our REST services. You receive this value during IDnow account setup. Never share this value with anyone, not even with us!
Token	After successfully authenticating against our API you will get a JSON Web Token (JWT) as a response which is required for any following request.
User	The end customer whose identity shall be verified.
Ident	An Ident is what we call the entity that you create via our API to represent the user in the verification process. IDnow generates an internal IdentID that uniquely identifies an Ident.
IdentID	The IdentID is also being used by the user to start the verification process. The IdentID follows the syntax: `ABC-DEFGH`
Transaction Number (TA Nbr.)	The TA Nbr. is a value that you can define and attach to an Ident you create. We emphasize this value to be unique per Ident and not guessable. You can use it to associate your Idents with internal data sets of your users.