API Overview

The IDnow DocIDV API is a RESTful HTTP API that accepts and returns UTF-8 encoded JSON. All requests must be made over HTTPS on port 443.

Base URLs

The base URL structure is:

{GATEWAY_HOST}/api/v1/{CUSTOMER}/

Where {CUSTOMER} is your company shortname as provided during account setup.

Environment	Region	Gateway Host
Production	DE (default)	https://gateway.idnow.de
Production	CH (Switzerland)	https://gateway.online-ident.ch
Test	DE (default)	https://gateway.test.idnow.de
Test	CH (Switzerland)	https://gateway.test.online-ident.ch

note

Use DE servers unless you are specifically operating in Switzerland (CH) or the UAE (AE).

Authentication

All API requests (except the login endpoint) require a session token in the request header:

X-API-LOGIN-TOKEN: <your-auth-token>
Content-Type: application/json

Obtain the token by calling the Login endpoint. The token expires after 60 minutes of inactivity.

tip

Your server must call the API — never expose your API key or authToken in client-side code.

Request Format

• All request bodies must be UTF-8 encoded JSON
• The JSON structure must be flat (no deeply nested objects in most endpoints)
• Use Content-Type: application/json on all requests with a body

Endpoints

Page	Endpoints
Authentication	POST /api/v1/{customer}/login
Identification Management	POST, GET, DELETE on /api/v1/{customer}/identifications/{transaction-number}
Webhooks	Webhook payload format, types, and retry behavior

HTTP Status Codes

Code	Meaning
200 OK	Request succeeded
201 Created	Resource created
400 Bad Request	Malformed request or validation failure
401 Unauthorized	Missing, expired, or invalid auth token; also returned for wrong Customer/Shortname
403 Forbidden	Authenticated but not permitted to perform this action
404 Not Found	Resource not found
409 Conflict	Resource already exists (e.g., duplicate transaction number)
422 Unprocessable Entity	Request is well-formed but contains semantic errors
500 Internal Server Error	IDnow server error

Error Response Format

{
  "error": "IDENTIFICATION_NOT_FOUND",
  "message": "Identification with transaction number '12345' not found",
  "timestamp": "2024-03-21T10:30:00Z"
}

Identification URLs

After creating an identification, you can direct your user to the verification flow using the web url, the mobile SDK or IDnow's application

Web (IdentID)

Environment	URL
Live DE	https://go.idnow.de/docidv?identToken={identId}
Live CH	https://go.online-ident.ch/docidv?identToken={identId}
Test DE	https://go.test.idnow.de/docidv?identToken={identId}
Test CH	https://go.test.online-ident.ch/docidv?identToken={identId}

The IdentID is returned in the id field of the Create Identification response. It follows the format ABC-DEFGH.