Identify API Ver. 1.0.1

Last updated: October 17th, 2019

Welcome to Identify VideoIdent API Documentation

Identify -> The Identity Verification Platform

NOTE: This documentation only applies to our products Identify VideoIdent.

Introduction

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

What is REST API ?

An API is an Application Programming Interface - in short, it’s a set of rules that lets programs talk to each other, exposing data and functionality across the internet in a consistent format.

REST stands for Representational State Transfer. This is an architectural pattern that describes how distributed systems can expose a consistent interface. When people use the term 'REST API', they are generally referring to an API accessed via HTTP protocol at a predefined set of URLs.

These URLs represent various resources - any information or content accessed at that location, which can be returned as JSON, HTML, audio files, or images. Often, resources have one or more methods that can be performed on them over HTTP, like GET, POST, PUT and DELETE.

What is videoident?

Videoident allows to verify the identity of a person along with a verification if the document used is genuine in a process guided by an Ident Specialist. The user and the Ident Specialist are interacting with each other during this process using a video-chat.

Identify Videoident can be used with a web browser by the user.

Target Audience

This document is targeted at developers of third party companies who want to integrate the Identify verification service into their own applications.

Terminology

We would like to introduce our terminalogy used throughout this documentation for a better understanding of the data entities you will be handling when requesting our API service:

Term Description
Partner Partner of Identify who uses the services of Identify to verify the identity of their customers.
API Key The API key is required for authenticating your application and accessing our REST services. You receive this value during Identify 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.
Customer The end user 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. Identify generates an internal IdentID that uniquely identifies an Ident.
IdentID The IdentID is also being used by the user to start the verification process.
Custom ID (custom_id) The Custom ID 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.

Getting Started

Before you can use the requests, a proper environment has to be set up. An environment holds parameters for setting your partner name, API Key, 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.

Identify API URL looks like this:

https://api.identify24.de/{method}

Content and Charset

Please make sure that all data is sent as UTF-8 encoded JSON. This is especially important because the encoding will influence the calculation of the security token. The expected JSON structure is flat.

Protocol and Port

To ensure that all parameters are encrypted, all requests to the Identify servers must be performed using HTTPS.

HTTP requests are not allowed.

The port for all requests is: 443.

API requests without authentication will also fail.

Lifetime
Item Description
JWT The authentication token has an idle time of 30 minutes after which it expires. (New token can be requested after expire)
Ident An Ident has a lifetime of 90 days if data retention policies do not dictate otherwise.
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.

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

Errors

Identify uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a request failed, etc.). Codes in the 5xx range indicate an error with server side.

200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
403 - Forbidden The API key doesn't have permissions to perform the request.
404 - Not Found The requested resource doesn't exist.
409 - Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on server side. (These are rare.)

METHODS

auth


POST PARTNER AUTHENTICATION


https://api.identify24.de/auth

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

HEADERS


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

BODY raw

{ "PARTNER": "{{PARTNER}}", "APIKEY": "{{APIKEY}}" }

SAMPLE CURL REQUEST

curl --location --request POST "https://api.identify24.de/auth" --header "Content-Type: application/json" --data "{ \"PARTNER\":\"YOUR PARTNER USERNAME\", \"APIKEY\":\"YOUR API KEY\" }"

SAMPLE RESPONSE

{ "result": true, "response_status": 200, "token": "xxx", "messages": [ "Successful.." ] }

ident/create

POST CREATE NEW IDENTITY VERIFICATION REQUEST


https://api.identify24.de/ident/create

Creates new identity verification request.Returns status code 200 if successful.

The body of this response also contains a JSON-formatted key/value pair: {"ident_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
containing Identify's internal IdentID of this Ident.

HEADERS


X-API-PARTNER
application/json
(REQUIRED) Partner User Name
X-API-TOKEN
application/json
(REQUIRED) Your private Auth Token
Content-Type
application/json
(REQUIRED) The media type

BODY raw

{ "project_id" : "xxx", "company_name" : "Optional", "store_name" : "Optional", "branche" : "Optional", "person_title" : "Optional", "gender" : "MALE", "person_first_name" : "John", "person_last_name" : "Doe", "person_position" : "Optional", "email" : "johndoe@identify24.de", "street" : "Markgrafenstr.", "house_no" : "23", "zip_code" : "94670", "city" : "Nürnberg", "country" : "DE", "mobile_phone" : "01511111111", "international_code" : "DE", "birthday" : "1981-09-05", "birth_place" : "BERLIN", "nationality" : "DE", "industry" : "Optional", "anbieter" : "Optional", "bank_name" : "Optional", "debitor" : "Optional", "steuer_id" : "Optional", "custom_id" : "Optional", "custom1" : "custom1", "custom2" : "custom2", "custom3" : "custom3", "custom4" : "custom4" }

SAMPLE CURL REQUEST

curl -X POST \ https://api.identify24.de/ident/create \ -H 'Accept: */*' \ -H 'Content-Type: application/json' \ -H 'X-API-PARTNER: 911-internet' \ -H 'X-API-TOKEN: xxx' \ -d '{ "project_id" : "6", "company_name" : "Optional", "store_name" : "Optional", "branche" : "Optional", "person_title" : "Optional", "gender" : "MALE", "person_first_name" : "John", "person_last_name" : "Doe", "person_position" : "Optional", "email" : "johndoe@identify24.de", "street" : "Markgrafenstr.", "house_no" : "23", "zip_code" : "94670", "city" : "Nürnberg", "country" : "DE", "mobile_phone" : "01511111111", "international_code" : "DE", "birthday" : "1981-09-05", "birth_place" : "BERLIN", "nationality" : "DE", "industry" : "Optional", "anbieter" : "Optional", "bank_name" : "Optional", "debitor" : "Optional", "steuer_id" : "Optional", "custom_id" : "Optional", "custom1" : "custom1", "custom2" : "custom2", "custom3" : "custom3", "custom4" : "custom4" }'

SAMPLE RESPONSE

{ "result": true, "messages": [], "ident_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "conference_url": "https://identify24.de/apply/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
Ident Attributes
Parameter Required Description
project_idYes-
company_nameNo-
store_nameNo-
brancheNo-
birthdayYesISO 8601 format: YYYY-MM-DD
birth_placeYesThe user’s birthplace. All uppercase.
emailYesE-mail address of the user.
genderYesThe user's gender. Either MALE or FEMALE.
person_titleNoAcademic title. This will only be used, if the title is part of the name and shown in ID documents.
person_first_nameYesThe user's first name(s). All uppercase.
person_last_nameYesThe user's last name. All uppercase.
person_positionNo-
mobile_phoneYesMobile phone number of the user. If no country code is provided, "0049" is assumed.
international_codeNo-
nationalityYesThe user’s nationality. Uppercase two-letter code as defied in ISO 3166.
streetNoThe user's street. Will be provided in sub-object named address. All uppercase.
house_noNo-
zip_codeYesThe user's zip code. Will be provided in sub-object named address.
cityYesThe user's city. Will be provided in sub-object named address. All uppercase.
countryYesThe user's country. Uppercase two-letter code as defied in ISO 3166. Will be provided in sub-object named address.
steuer_idNo-
debitorNo-
bank_nameNo-
anbieterNo-
industryNo-
custom_idNoCustom tracking field. Can be used to pass tracking information. You will get this information back in the identification results.
custom1NoCustom field that can be used for passing your own ids, tags etc.
custom2Nofree field for open use.
custom3Nofree field for open use.
custom4Nofree field for open use.

ident/get

GET GET IDENTITY

https://api.identify24.de/ident/get

Get an ident


HEADERS


X-API-PARTNER
application/json
(REQUIRED) Partner User Name
X-API-TOKEN
application/json
(REQUIRED) Your private Auth Token
Content-Type
application/json
(REQUIRED) The media type

BODY raw

{ "ident_id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }

SAMPLE CURL REQUEST

curl -X GET \ https://api.identify24.de/ident/get \ -H 'Accept: */*' \ -H 'Content-Type: application/json' \ -H 'X-API-PARTNER: 911-internet' \ -H 'X-API-TOKEN: xxx' \ -d '{ "ident_id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }'

SAMPLE RESPONSE

{ "result": true, "messages": [], "data": { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "project_id": "6", "person_first_name": "John", "person_last_name": "Doe", "custom_id": "Optional", "custom1": "custom1", "custom2": "custom2", "custom3": "custom3", "custom4": "custom4", "status": "Unidentified", "created_at": "21-10-2019 09:57:51" } }

project/getAll

GET GET ALL PROJECTS

https://api.identify24.de/project/getAll

Retrieves all projects


HEADERS


X-API-PARTNER
application/json
(REQUIRED) Partner User Name
X-API-TOKEN
application/json
(REQUIRED) Your private Auth Token
Content-Type
application/json
(REQUIRED) The media type

SAMPLE CURL REQUEST

curl -X GET \ https://api.identify24.de/project/getAll \ -H 'Accept: */*' \ -H 'Content-Type: application/json' \ -H 'X-API-PARTNER: 911-internet' \ -H 'X-API-TOKEN: xxx' \ -H 'cache-control: no-cache'

SAMPLE RESPONSE

{ "result": true, "messages": [], "data": [ { "id": "6", "title": "911 Internet GmbH", "status": "Active" } ], "response_status": 200 }

project/get

GET GET PROJECT

https://api.identify24.de/project/get

Retrieves an ident


HEADERS


X-API-PARTNER
application/json
(REQUIRED) Partner User Name
X-API-TOKEN
application/json
(REQUIRED) Your private Auth Token
Content-Type
application/json
(REQUIRED) The media type

BODY raw

{ "project_id" : xxx }

SAMPLE CURL REQUEST

curl -X GET \ https://api.identify24.de/project/get \ -H 'Accept: */*' \ -H 'Content-Type: application/json' \ -H 'X-API-PARTNER: 911-internet' \ -H 'X-API-TOKEN: xxx' \ -d '{ "project_id" : 6 }'

SAMPLE RESPONSE

{ "result": true, "messages": [], "data": { "id": "6", "title": "911 Internet GmbH", "status": "Active" }, "response_status": 200 }