General Information
This document describes the usage of identity.TM's by IDNow customer-facing APIs. Intended audience are developers and system integrators.
Contact and Credentials for Service Integration
Throughout the technical implementation you will be assisted by IDnow.
itm-it-support@idnow.io is the contact for any kind of technical and
procedural questions. If you have not already received backend
credentials for the services in this document, please apply for some by
contacting IDnow.
Future development of this API
This API is under constant development. New versions with new features can appear at any point in time without further notice.
Adding new elements to responses or optional elements to requests is considered to be a compatible change and neither the major nor minor version of the API will change. Only this document will be updated and carry a new index letter.
Because of this policy, you must not assume, that responses will carry only the elements outlined in a specific version.
In case of incompatible changes, the new API will receive either a new minor or major version number, depending on the size of the changes.
Basic definitions
| Term | Definition |
|---|---|
| User | Natural person to be identified, also referred to as "signee" in eSign context |
| OrderID | identity.TM's internal unique reference to an order |
| UserID | identity.TM's internal unique identification number for a shop agent |
| UserToken | identity.TM's internal security token for agent sign-in purposes |
Datatype Codes
| Code | Meaning |
|---|---|
| O | Object |
| A | Array |
| DS | Date string, with format YYYY-MM-DD |
| DTS | Date time string according to ISO 8061 (e.g., 2013-07-15T18:00:00+02:00) |
| TS | Time string, 24-hour-based, format HH:MM |
| S | String |
| N | Number |
| B | Boolean |
| PN | International phone number without blanks (MSISDN) e.g., +491701234567 |
| CC | The ISO-Code of the country (ISO 3166) e.g., DE, AT, NL |
Abbreviations
| Abbreviation | Meaning |
|---|---|
| Len | Length |
| Type | Datatype, abbreviated |
| Req | Element is required |
| Occ | Element occurs |
| Y | Yes |
| N | No |
| Dep | Depends on parameters/conditions |
Typical Identification Flow
The identification of a natural person is started by creating an identification order. As a result, a URL will be returned. Typically, the user will now be redirected to that URL to choose between different identification methods (dubbed Verfahrensseite or landing page).
The user will then carry out the identification. In the meantime, you can lean back and wait for a result to come.
After the identification has been conducted, the user will typically be redirected to you (in the rare case that no redirect is desired, the user will be redirected to a friendly page on identity.TM side that thanks the user for conducting the identification).
Once a final judgment on the result of an identification has been made, you will be notified asynchronously via a webhook, that a result is now available. You would then make API calls to query the status of that specific identification order and query the identification data, if available. Identification data will be available in case the identification has been conducted positively or the identification is suspicious to fraud.
Once all data has been retrieved, you will then make an API call to delete the identification data.
In case the user does not finish an identification, a configurable time out will occur, that invalidates and deletes the order. A webhook will be triggered to indicate that condition.
Redirects
By default, the user will be redirected to the designated URL when the identification is finished from an end-user perspective. Keep in mind, that this moment will most probably not be the moment in which the order is finally processed, so no result data might be available. You must wait for the OnFinal webhook to be triggered, before retrieving results.
Alternatively, your account can be configured to keep the user on a spinner page on identity.TM side until the order is completed. In this case, data will be available when the redirect happens. Please contact itsupport@identity.tm if you would like to have such a spinner or more information on this topic.
Webhooks
Like the redirect URLs, the webhook URLs can also be set up within each putOrder request (WebhookURL element) that is being made. If these URLs do not change for each order, it is possible to configure them on a per account level.
The placeholders [Ref] and/or [OrderID] can be used to make the URL dynamic. [Ref] will be replaced by your internal reference number as specified when creating the order while [OrderID] will be replaced with identity.TM's unique OrderID of the order.
For OnStatusChange Webhook URL you can also use the placeholder [statusCode].
By default, Webhooks will be delivered via GET requests. This can be changed on a per account level to either POST or PUT if necessary.
Recommendations
Do not try to run longer operations in the code that receives the webhook. Webhooks will be executed synchronously, and further order processing will be blocked until a webhook call has been finished. The operation should not take longer than 5 seconds and the webhook call will be terminated after 10 seconds.
Retry scheme
In case a webhook is not replied with a HTTP status code 200 or 202, the system will try to deliver the webhook again. The first retry will be started after approximately 86,4 seconds after the first try.
| From | To | Interval |
|---|---|---|
| 86.4s | 864s | Once every minute |
| 864s | 12h | Once every hour |
| 12h | 6d | Once at night |
Example URLs
https://www.example.com/identity/callback/AfterVideo?orderID=[OrderID]&ref=[Ref]
https://www.example.com/identity/callback/OnFinal?orderID=[OrderID]&ref=[Ref]
Technical Data
| Service Kind | RESTful web service over HTTPS (HTTP 1.1 status codes) JSON Data in HTTP Body |
| Base URL | Customer Services: https://customer.identity.tm/api/2.10/ |
| Content-Type | application/json |
| Authentication | Customer Services: HTTP Basic Authentication |
| TLS | Version 1.2 |