Identify API Ver. 1.0.2

Last updated: March 5th, 2024

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.

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", "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", "language" : "de", "mobile_phone" : "01511111111", "international_code" : "DE", "birthday" : "1981-09-05", "birth_place" : "BERLIN", "nationality" : "DE", "type_of_id" : "Personalausweis", "id_number" : "LJFE8J32NDM", "id_country" : "DE", "id_issue_date" : "2021-05-10", "id_end_date" : "2031-05-09", "issuing_authority" : "Stadt Nürnberg", "pdf_url" : "https://xxxxxxxxxx.pdf", "pdf_content" : "data:@file/pdf;base64,xxxxxxxxxxxxxxxxx" }

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", "birthday" : "1981-09-05", "birth_place" : "BERLIN", "email" : "johndoe@identify24.de", "gender" : "MALE", "person_title" : "Optional", "person_first_name" : "John", "person_last_name" : "Doe", "person_position" : "Optional", "mobile_phone" : "01511111111", "nationality" : "DE", "international_code" : "DE", "street" : "Markgrafenstr.", "house_no" : "23", "zip_code" : "94670", "city" : "Nürnberg", "country" : "DE", "language" : "de", "type_of_id" : "Personalausweis", "id_number" : "LJFE8J32NDM", "id_country" : "DE", "id_issue_date" : "2021-05-10", "id_end_date" : "2031-05-09", "issuing_authority" : "Stadt Nürnberg", "pdf_content" : "data:@file/pdf;base64,xxxxxxxxxxxxxxxxx" }'

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-
birthdayYesISO 8601 format: YYYY-MM-DD
birth_placeNoThe user's birthplace. All uppercase.
emailYesE-mail address of the user.
genderNoThe 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.
streetYesThe user's street. Will be provided in sub-object named address. All uppercase.
house_noYes-
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.
languageNoThe user's language for identification. Either of 'de', 'en', 'pl', 'cs'. 'sk'. Defaults to 'de' if unset or invalid.
type_of_idNoThe type of ID document which is used by the user. Possible values are: "Personalausweis" for ID card or "Reisepass" for passport.
id_numberNoThe ID number of valid ID document.
id_countryNoThe issuing country of the ID document. Uppercase two letter cod as defined in ISO 3166.
id_issue_dateNoThe date when the ID document was issued in ISO 8601 format: YYYY-MM-DD
id_end_dateNoThe date until the ID document is valid in ISO 8601 format: YYYY-MM-DD
issuing_authorityNoThe government agency who issued the ID document.
pdf_urlNoURL of PDF file to be signed which should be fetched by identify.
pdf_contentNoContent of Base64 encoded PDF file to be signed.

ident/get

GET GET IDENTITY

https://api.identify24.de/ident/get/{ident_id}

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

SAMPLE CURL REQUEST

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

SAMPLE RESPONSE

{ "result": true, "messages": [], "data": { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "project_id": "6", "person_first_name": "John", "person_last_name": "Doe", "status": "Unidentified", "created_at": "21-10-2019 09:57:51" "appointment_date": "2019-10-24 11:11" } }

ident/getIdentData

GET GET IDENTIFICATION DATA

https://api.identify24.de/ident/getIdentData/{ident_id}

Get all data from 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

SAMPLE CURL REQUEST

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

SAMPLE RESPONSE

{ "result": true, "messages": [], "data": { "ident": { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "project_id": "6", "person_first_name": "John", "person_last_name": "Doe", "status": "Unidentified", "created_at": "21-10-2019 09:57:51" "appointment_date": "2019-10-24 11:11" }, "signed_pdf": { "file_name": "signed.pdf", "download_url": "https://api.identify24.de/download/xxx/signed.pdf", "file_date": "21-02-2024 11:13:13", "file_size": "2.34 MB" }, "recordings": [ { "file_name": "65e5a013502a2.webm", "download_url": "https://api.identify24.de/download/xxx/65e5a013502a2.webm", "file_date": "04-03-2024 11:18:59", "file_size": "12.27 MB" } ], "screenshots": [] } }

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 }

webhook/getAll

GET GET ALL WEBHOOKS

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

Retrieves all partner webhooks


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/webhook/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, "response_status": 200, "messages": [], "data": [ { "id": "1", "status": "4", "url": "https://xxxxxx.xxx", "created_at": "2020-06-21 11:03:49", "updated_at": "2024-03-06 17:54:32" }, { "id": "2", "status": "4", "url": "https://yyyyyy.yyy", "created_at": "2020-06-21 11:03:49", "updated_at": "2024-03-06 17:54:32" } ] }

Webhook

What is a Webhook ?

A webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately. Unlike typical APIs where you would need to poll for data very frequently in order to get it real-time. This makes webhooks much more efficient for both provider and consumer. The only drawback to webhooks is the difficulty of initially setting them up.

Webhooks are sometimes referred to as “Reverse APIs,” as they give you what amounts to an API spec, and you must design an API for the webhook to use. The webhook will make an HTTP request to your app (typically a POST), and you will then be charged with interpreting it.

Before using webhook service you must define a webhook url from your partner portal.

On some situations, you will have to make some security adjustments on your server side reciever endpoint for acquiring these requests correctly. For further necessary support please contact with us.

How to define webhook URL ?

You can define a webhook reciever URL from the partner portal > merchant details section.

Sample Payload

Identify will send these payloads via POST method.

SAMPLE WEBHOOK PAYLOAD

{ "ident_id" : "xxxxx", "status_id" : "xxxxx", "status" : "xxxxx", "project_id" : "xxxxx", "custom_id" : "xxxxx", "company_name" : "xxxxx", "first_name" : "xxxxx", "last_name" : "xxxxx", "custom1" : "xxxxx", "custom2" : "xxxxx", "custom3" : "xxxxx", "custom4" : "xxxxx", "agent_notes" : "xxxxx", "reject_reason" : "xxxxx", "agent_name" : "xxxxx", "appointment_date": "YYYY-mm-dd H:i" }

Webhook Statuses

Identify uses different statuses to monitor the progress of webhooks.

1 - PENDING Webhook is pending to be processed.
2 - RUNNING Webhook is currently being processed.
3 - SUCCESS Webhook completed successfully.
4 - FAILED Webhook failed.