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.
- Home
- Documentation
Identify API Ver. 1.0.1
Last updated: April 12th, 2022
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
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
(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
(REQUIRED) Partner User Name
X-API-TOKEN
application/json
(REQUIRED) Your private Auth Token
(REQUIRED) Your private Auth Token
Content-Type
application/json
(REQUIRED) The media type
(REQUIRED) The media type
BODY raw
{
"project_id" : "xxx",
"company_name" : "Optional",
"company_hrb_number" : "Optional",
"company_hrb_city" : "Optional",
"company_street" : "Optional",
"company_house_no" : "Optional",
"company_zip_code" : "Optional",
"company_city" : "Optional",
"company_country" : "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",
"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",
"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",
"company_hrb_number" : "Optional",
"company_hrb_city" : "Optional",
"company_street" : "Optional",
"company_house_no" : "Optional",
"company_zip_code" : "Optional",
"company_city" : "Optional",
"company_country" : "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",
"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",
"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_id | Yes | - |
| company_name | No | Company official Name (Required for ident type KYB) |
| company_hrb_number | No | Company registered HRB Number (Required for ident type KYB) |
| company_hrb_city | No | Company registered HRB City (Required for ident type KYB) |
| company_street | No | Company registered street name (Required for ident type KYB) |
| company_house_no | No | Company registered house number (Required for ident type KYB) |
| company_zip_code | No | Company registered Zip code (Required for ident type KYB) |
| company_city | No | Company registered city (Required for ident type KYB) |
| company_country | No | Uppercase two-letter code as defied in ISO 3166. (Required for ident type KYB) |
| store_name | No | - |
| branche | No | - |
| birthday | Yes | ISO 8601 format: YYYY-MM-DD |
| birth_place | Yes | The user’s birthplace. All uppercase. |
| Yes | E-mail address of the user. | |
| gender | Yes | The user's gender. Either MALE or FEMALE. |
| person_title | No | Academic title. This will only be used, if the title is part of the name and shown in ID documents. |
| person_first_name | Yes | The user's first name(s). All uppercase. |
| person_last_name | Yes | The user's last name. All uppercase. |
| person_position | No | - |
| mobile_phone | Yes | Mobile phone number of the user. If no country code is provided, "0049" is assumed. |
| international_code | No | - |
| nationality | Yes | The user’s nationality. Uppercase two-letter code as defied in ISO 3166. |
| street | No | The user's street. Will be provided in sub-object named address. All uppercase. |
| house_no | No | - |
| zip_code | Yes | The user's zip code. Will be provided in sub-object named address. |
| city | Yes | The user's city. Will be provided in sub-object named address. All uppercase. |
| country | Yes | The user's country. Uppercase two-letter code as defied in ISO 3166. Will be provided in sub-object named address. |
| type_of_id | No | The type of ID document which is used by the user. Possible values are: "Personalausweis" for ID card or "Reisepass" for passport. |
| id_number | No | The ID number of valid ID document. |
| id_country | No | The issuing country of the ID document. Uppercase two letter cod as defined in ISO 3166. |
| id_issue_date | No | The date when the ID document was issued in ISO 8601 format: YYYY-MM-DD |
| id_end_date | No | The date until the ID document is valid in ISO 8601 format: YYYY-MM-DD |
| issuing_authority | No | The government agency who issued the ID document. |
| pdf_url | No | URL of PDF file to be signed which should be fetched by identify. |
| pdf_content | No | Content of Base64 encoded PDF file to be signed. |
| custom_id | No | Custom tracking field. Can be used to pass tracking information. You will get this information back in the identification results. |
| custom1 | No | Custom field that can be used for passing your own ids, tags etc. |
| custom2 | No | free field for open use. |
| custom3 | No | free field for open use. |
| custom4 | No | free field for open use. |
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
(REQUIRED) Partner User Name
X-API-TOKEN
application/json
(REQUIRED) Your private Auth Token
(REQUIRED) Your private Auth Token
Content-Type
application/json
(REQUIRED) The media type
(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",
"custom_id": "Optional",
"custom1": "custom1",
"custom2": "custom2",
"custom3": "custom3",
"custom4": "custom4",
"status": "Unidentified",
"created_at": "21-10-2019 09:57:51"
"appointment_date": "2019-10-24 11:11"
}
}
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
(REQUIRED) Partner User Name
X-API-TOKEN
application/json
(REQUIRED) Your private Auth Token
(REQUIRED) Your private Auth Token
Content-Type
application/json
(REQUIRED) The media type
(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
(REQUIRED) Partner User Name
X-API-TOKEN
application/json
(REQUIRED) Your private Auth Token
(REQUIRED) Your private Auth Token
Content-Type
application/json
(REQUIRED) The media type
(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
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"
}