Document Data
Creating an identification for a QES/eSign flow follows the same process as a regular identification request, with additional required fields that must be included in the Create Identification request.
Required fields for QES/eSign
The following fields are mandatory when creating an identification for a Contract Signing flow:
| Field | Type | Required for | Description |
|---|---|---|---|
firstname | string | All QES/eSign flows | User's first name |
lastname | string | All QES/eSign flows | User's last name |
mobilephone | string | Namirial TSP only | User's mobile number including country code |
preferredLang | string | Namirial TSP only | Language code required by the Namirial TSP |
Name field restrictions
The firstname and lastname fields only accept the following characters: A–Z, a–z, -. Commas, accented characters, and all other special characters are not allowed.
Namirial TSP requirements
When using Namirial as the Trust Service Provider (TSP), two additional fields are required in the Create Identification request that are not needed for IDnow Trust Services.
mobilephone must be specified with the country code prefix in the format +<country-code><number>, for example +49175310960.
preferredLang has no effect on the display language of the AutoIdent app or SDK. It is solely used by the Namirial TSP and is not required for standard AutoIdent flows or when using IDnow Trust Services.
mobilephone — The user's mobile phone number in international format (+<country-code><number>). Used by Namirial to send OTP verification codes during the signing process.
preferredLang — A language code passed to Namirial for the QES/eSign flow. This parameter controls the language of Namirial's signing interface and communications.
PDF accessibility requirements
PDF documents uploaded for signing must be accessible. This means the document must be a text-based PDF (not a scanned image), include structural tags so assistive technologies can interpret the reading order, provide alternative text for any images or non-text content, and have the document language set in the PDF metadata. It is the integrator's responsibility to validate that uploaded documents meet these requirements before uploading them. See the PDF accessibility guidelines for more information.
Upload a Document
Uploads a document for a specific identification transaction. Use this for documents that differ per user — for example, a contract that contains the user's name must be uploaded individually for each IdentID.
Endpoint
POST /api/v1/{customer}/identifications/{transaction-number}/documents/{identifier}/data
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customer | string | Yes | Your company identifier |
transaction-number | string | Yes | Transaction identifier |
identifier | string | Yes | Document definition identifier. Allowed characters: a–z, -, _, 0–9. Example: doc763 |
Request
Headers
| Header | Type | Required | Description |
|---|---|---|---|
X-API-LOGIN-TOKEN | string | Yes | Auth token for authentication |
Request Parameters
{
"data": "<base64-encoded-pdf-content>",
"fileName": "contract.pdf",
"mimeType": "application/pdf"
}
Response
{
"documentId": "doc-12345",
"identifier": "contract_template_v1",
"fileName": "contract.pdf",
"uploadedAt": "2024-03-21T10:30:00Z",
"status": "UPLOADED"
}
The maximum number of documents per identification is 25. The combined file size of all documents in a single identification must not exceed 50 MB.
Get a single document information to be signed.
This request allows viewing the contract document that was uploaded for an identification/document signing process.
Endpoint
GET /api/v1/{customer}/identifications/{transaction-number}/documents/{identifier}
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customer | string | Yes | Your company identifier |
transaction-number | string | Yes | Transaction identifier |
identifier | string | Yes | Document definition identifier |
Request
Headers
| Header | Type | Required | Description |
|---|---|---|---|
X-API-LOGIN-TOKEN | string | Yes | Auth token for authentication |
Response
| Field | Type | Description |
|---|---|---|
name | string | Name of the file or document. Example: ABGesign |
hash | string | SHA256 hash of the document. Example: fc286667a0f569bec74f4a2db74c6d021f3b23029749e11ed66df5160a1809 |
displayHash | string | First 12 bytes of the hash, displayed to the user as a fingerprint. Example: 2fc2-8666-7a0f |
status | string | Document status: NEED_UPLOAD, UPLOADED, or SIGNED |
documentDefinition | object | Information about the document definition associated with this document |
documentDefinition.optional | boolean | Whether the document is optional. If true, a default document is provided if none is uploaded |
documentDefinition.name | string | Display name of the document definition. Example: ABGesign |
documentDefinition.identifier | string | Unique identifier of the document definition |
documentDefinition.mimeType | string | MIME type of the document. Example: application/pdf |
documentDefinition.sortOrder | integer | Display order position, starting from 1 |
{
"name": "ABGesign",
"hash": "fc286667a0f569bec74f4a2db74c6d021f3b23029749e11ed66df5160a1809",
"displayHash": "2fc2-8666-7a0f",
"status": "SIGNED",
"documentDefinition": {
"optional": false,
"name": "ABGesign",
"identifier": "contract_template_v1",
"mimeType": "application/pdf",
"sortOrder": 1
}
}
Get all documents associated with an identification transaction.
This request lists the details and statuses of documents that are associated with a partcular transaction number.
Endpoint
GET /api/v1/{customer}/identifications/{transaction-number}/documents
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customer | string | Yes | Your company identifier |
transaction-number | string | Yes | Transaction identifier |
Request
Headers
| Header | Type | Required | Description |
|---|---|---|---|
X-API-LOGIN-TOKEN | string | Yes | Auth token for authentication |
Response
Returns an array of document objects. Each object contains the following fields:
| Field | Type | Description |
|---|---|---|
name | string | Name of the document definition. Allowed characters: a–z, -, _ |
hash | string | SHA256 hash of the document. Example: 2fc286667a0f569bec74f4a2db74c6d021f3b23029749e11ed66df5160a1809f |
status | string | Document status: NEED_UPLOAD, UPLOADED, or SIGNED |
documentDefinition | object | Describes the type of document |
documentDefinition.optional | boolean | Whether the document is optional. If true, a default document is provided if none is uploaded |
documentDefinition.name | string | Friendly display name of the document. Example: Arbeitsvertrag |
documentDefinition.identifier | string | Identifier of the document used in the URL. Allowed characters: a–z, -, _, 0–9 |
documentDefinition.mimeType | string | MIME type of the document. Example: application/pdf |
documentDefinition.sortOrder | integer | Display order, starting from 1. The document is inserted before this position |
documentDefinition.viewPolicy | string | Controls PDF rendering in the web view: SCROLL shows the full PDF with a scrollbar; DEFAULT shows it at a fixed height |
[
{
"name": "contract_template_v1",
"hash": "2fc286667a0f569bec74f4a2db74c6d021f3b23029749e11ed66df5160a1809f",
"status": "SIGNED",
"documentDefinition": {
"optional": false,
"name": "Arbeitsvertrag",
"identifier": "contract_template_v1",
"mimeType": "application/pdf",
"sortOrder": 1,
"viewPolicy": "SCROLL"
}
},
{
"name": "privacy_policy",
"hash": "9ab1234567890abcdef1234567890abcdef1234567890abcdef1234567890abc",
"status": "UPLOADED",
"documentDefinition": {
"optional": true,
"name": "Datenschutzerklärung",
"identifier": "privacy_policy",
"mimeType": "application/pdf",
"sortOrder": 2,
"viewPolicy": "DEFAULT"
}
}
]
Document Status Values
| Status | Description |
|---|---|
NEED_UPLOAD | Document content has not been uploaded yet |
UPLOADED | Document content uploaded and pending signature |
SIGNED | Document successfully signed |