Additional Functions

Checking sign-me User Status

This method is only applicable if you wish to create an eSign order for sign-me (D-Trust). Before creating the order, you can check the user status in the sign-me system to find out if the given user already has a sign-me account and if he or she is able to sign with a qualified electronic signature (QES). Both elements in the response need to be true in order to create a plain signature Order (Add = 16 in putOrder). Otherwise, the account needs to be created and verified (Add = 0 or 8 in putOrder -- The Add value 0 represents the default setting with creation/verification of the account plus PDF document(s) that need(s) to be signed -- with the Add value 8 it is the same except for the PDF and signature part).

Requirements

Your account must be configured for eSign using sign-me.

Method and URL

[POST] https://customer.identity.tm/api/2.10/checkSignmeUser

JSON Request Body

Element	Parent	Type	Len	Req	Description
Email	[ROOT]	String		Y	The sign-me username (e-mail)
signatureType	[ROOT]	String	3	N	Optionally check if the user is able to sign with a specific signature type. Possible values: QES QES ADV AES BAS Basic electronic signature/BES

Response Data

Element	Parent	Type	Len	Occ	Description
UserExists	[ROOT]	B		Y	The sign-me account exists
UserIsAbleToSign	[ROOT]	B		Y	The sign-me account is qualified and able to sign

HTTP Codes

200 OK, JSON document in body

400 Bad request, error description in body

401 Authentication failed, please check username and password

Example Request

[POST] https://customer.identity.tm/api/2.10/checkSignmeUser

{
  "Email": "e.mustermann@example.com"
}

Example Response

{
  "UserExists": false,
  "UserIsAbleToSign": false
}

Changing the Customer API Password Programmatically

It is possible to request a password change programmatically. To be able to do so, you need to provide a secure mobile phone number to IDnow's Service Desk first to enable that functionality.

The password change process consists of two steps, requesting a password change and confirming it. The pre-defined mobile number needs to be provided in the first step as an additional secret.

A TAN number will be sent via SMS to the mobile phone. This TAN needs to be included in the confirmation request.

Request Password Change

Method and URL

[POST] https://customer.identity.tm/api/2.10/requestNewPassword

JSON Request Body

Element	Parent	Type	Len	Req	Description
mobile	[ROOT]	PN	64	Y	Mobile phone number to send confirmation TAN to

HTTP Codes

200 OK, TAN is sent to the mobile number

400 Bad request, error description in body

401 Authentication failed, please check username, password and mobile number

Example Request

[POST] https://customer.identity.tm/api/2.10/requestNewPassword

{
  "mobile": "+49171123456"
}

Confirm password change

By executing this method, a new password will be set. The new password will be part of the response. If you provide the wrong TAN number, no new password will be set, and a password change needs to be requested again.

Method and URL

[POST] https://customer.identity.tm/api/2.10/confirmNewPassword

JSON Request Body

Element	Parent	Type	Len	Req	Description
tan	[ROOT]	S	6	Y	Confirmation TAN

Response Data

Element	Parent	Type	Len	Occ	Description
password	[ROOT]	S		Y	The new password

HTTP Codes

200 OK, password has been changed, new password in body

400 Bad request, error description in body

401 Authentication failed, please check username, password, and TAN

Example Request

[POST] https://customer.identity.tm/api/2.10/confirmNewPassword

{
  "tan": "123456"
}

Example Response

{
  "password": "XXXXXXXXXXX"
}

Deep Linking into apps

The native identity.TM video/eID apps support deep linking.

If your users open such a link on a mobile device they will be redirected to the according app store (Google Play on Android devices and App Store on iOS devices). In case they open such a link on an unsupported mobile or a desktop device the usual identity.TM landing page will be shown. The prime advantage for the user is that he or she no longer needs to find the right app manually and enter his or her credentials into it.

To receive such a deep link, which is a simple URL after all, you need to set the flag getDeepLink to true when executing the putOrder request. It is up to you to either redirect the user directly using the received deep link URL, putting it into an e-mail or presenting the link to the user as a QR code.

Optional content encryption

Several API calls that deal with verified identification data or recorded data support an optional content encryption scheme for additional security. To get the data in an encrypted form, you only need to append /crypt to the URL.

Keep in mind, that you need to share an AES-256 encryption key with us to use this function. This key will be used to encrypt the data.

Trying to call an API function with the /crypt argument without having your account properly set up will result in an error code.

The data format will be:

Initialization vector, 23 bytes long
Encrypted data
GCM Tag

The content type header will remain unaltered.

If necessary, we can provide you with a code snippet, showing how to decrypt the encrypted data.

Testrobot

To activate this feature, set a specific value to the Autotest or to the Ref (deprecated) element during order creation. However, if Autotest is set, the Ref value will not affect this feature.

The following values are supported for the Autotest element:

POSITIVE

NEGATIVE

FRAUD

SIGN

In case when you use the deprecated way to activate this feature via Ref element then the following values are supported:

X-AUTOTEST-POSITIVE

X-AUTOTEST-NEGATIVE

X-AUTOTEST-FRAUD

X-AUTOTEST-SIGN

*The difference between the values of the two elements has no functional impact, and the outcome is the same.

As a result, a respective testrobot flow will be triggered. The order will be automatically marked as completed approximately 20 seconds after creation, and the corresponding status codes based on the value set in the **Autotest(**or Ref) element will be assigned to the order. The provided IdentData upon order creation will be available for retrieval via the getIdentData endpoint once the order is completed (after 20 seconds). The returned result will match the previously provided IdentData, with the single exception that the ID card images are set to our sample images, which are also included in the getIdentData response.

For eSignPos orders (Add 4194304), and only for them, you can use SIGN as flow.

For eID test cases, the eidRestrictedIdentifier is generated randomly unless you specify IdentData->IDCard->CardNo. If this is the case, it is generated on the basis of the CardNo specified.

This feature is available for integration accounts only.

Example of order creation:

Request

[POST] https://customer.identity.tm/api/2.10/putOrder

{
  "Ref": "Test order",
  "Autotest": "POSITIVE",
  "Product": 19,
  "IdentData": {
    "Email": "mustermann@idnow.io",
    "Gender": "male",
    "Firstname": "Hans",
    "Surname": "Mustermann",
    "Street": "Musterstr 10",
    "ZipCode": "40231",
    "City": "Düssledorf",
    "Country": "DE",
    "Birthdate": "1980-01-01",
    "Birthplace": "Düssledorf",
    "Nationality": "DE",
    "CollectedBy": "Mustermann",
    "IDCard": {
      "CardNo": "f8b2931c-46b0-477f-bad5-23649a9bb948",
      "PlaceOfIssue": "Düssledorf",
      "DateOfIssue": "2010-12-12",
      "ValidUntil": "2030-12-12",
      "Type": "IDCard",
      "CountryOfIssue": "DE"
    }
  }
}

Response

{
  "OrderID": "9992403897831D",
  "Ref": "Test order"
}

Example of retrieving IdentData:

Request

[GET] https://customer.identity.tm/api/2.10/getIdentData/9992403897831D

Response

{
  "Identitfied": "2025-05-15T15:25:31+02:00",
  "OcrStatus": 0,
  "eIdUsed": false,
  "SecurityCheckFailed": false,
  "IdentData": {
    "0": {
      "Type": 1,
      "Firstname": "Hans",
      "Surname": "Mustermann",
      "Street": "Musterstr 10",
      "ZipCode": "40231",
      "City": "Düssledorf",
      "Country": "DE",
      "Birthdate": "1980-01-01",
      "Birthplace": "Düssledorf",
      "Birthname": null,
      "Nationality": "DE",
      "Gender": "male",
      "Email": "mustermann@idnow.io",
      "IDCard": {
        "CardNo": "f8b2931c-46b0-477f-bad5-23649a9bb948",
        "PlaceOfIssue": "Düssledorf",
        "DateOfIssue": "2010-12-12",
        "ValidUntil": "2030-12-12",
        "Type": "IDCard",
        "CountryOfIssue": "DE"
      }
    },
    "Images": [
      {
        "Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wC...",
        "Filename": "front_20250516-085942-865344415.jpg"
      },
      {
        "Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wC...",
        "Filename": "back_20250516-085942-558834056.jpg"
      },
      {
        "Image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wC...",
        "Filename": "face_20250516-085942-657504955.jpg"
      }
    ]
  }
}

Checking sign-me User Status​

Requirements​

Method and URL​

JSON Request Body​

Response Data​

HTTP Codes​

Example Request​

Example Response​

Changing the Customer API Password Programmatically​

Request Password Change​

Method and URL​

JSON Request Body​

HTTP Codes​

Example Request​

Confirm password change​

Method and URL​

JSON Request Body​

Response Data​

HTTP Codes​

Example Request​

Example Response​

Deep Linking into apps​

Optional content encryption​

Testrobot​

Checking sign-me User Status

Requirements

Method and URL

JSON Request Body

Response Data

HTTP Codes

Example Request

Example Response

Changing the Customer API Password Programmatically

Request Password Change

Method and URL

JSON Request Body

HTTP Codes

Example Request

Confirm password change

Method and URL

JSON Request Body

Response Data

HTTP Codes

Example Request

Example Response

Deep Linking into apps

Optional content encryption

Testrobot