Document Definition

A document definition is a system configuration that tells IDnow about a document type that will be part of an identification transaction's QES/eSign flow. It is registered once per shortname and describes each contract document that users may be asked to sign.

Backend alignment required

Document definitions you create via the API must match the IDnow backend account configuration for your shortname. Contact your IDnow Solution Engineering or Customer Success representative before creating or modifying document definitions to ensure both sides are configured correctly and validated.

Key concepts

Document definitions are created once per shortname, not per identification. You register a document definition once before your first identification transaction; you do not need to create one for each transaction.

Each shortname can have multiple document definitions, each identified by a unique identifier value.

Document definitions are only required for the Contract Signing use case. For a QES-only flow (identity verification without contract signing), document definitions are created automatically by the system when the first identification is started — no manual setup is needed.

DocIDV supports signing up to 10 contract documents per identification transaction. Each document to be signed requires its own document definition.

Identifier naming rules

The identifier field must meet the following requirements:

• Single or multi-word string
• Starts with one or more word characters ([a-zA-Z0-9_])
• Multi-word identifiers must be separated by underscores
• Ends with one or more word characters
• Does not contain accented or special characters — hyphens and underscores are accepted

Valid	Invalid
contract	contract-v1 (hyphen not supported in identifier)
privacy_policy	Contrat_Qualifié (accented characters)
nda_v2	__leading_underscores

note

The identifier value you specify must match your IDnow backend account configuration exactly. The name field is also subject to the same character restrictions — no accented or special characters.

---

Creates a new document definition for a shortname.

Endpoint

POST /api/v1/{customer}/documentdefinitions

Path parameters

Parameter	Type	Required	Description
customer	string	Yes	Your company identifier

Request

Headers

Header	Type	Required	Description
X-API-LOGIN-TOKEN	string	Yes	Auth token for authentication

Request Parameters

Field	Type	Required	Description
identifier	string	Yes	Unique identifier (must match IDnow backend config — see naming rules above)
name	string	Yes	Display name for the document
mimeType	string	Yes	Must be application/pdf
optional	boolean	No	Whether the document is optional for the user to sign
instructions	string	No	Instructions displayed to the user
sortOrder	integer	No	Display order when multiple documents are presented
viewPolicy	string	No	Controls whether the user must view the document before signing
displayHash	boolean	No	If true, displays the first 12 bytes of the document SHA256 to the user

{
  "identifier": "contract_template_v1",
  "name": "Standard Contract Template",
  "mimeType": "application/pdf",
  "optional": false,
  "instructions": "Please review and sign the contract",
  "sortOrder": 1
}

Response

{
  "identifier": "contract_template_v1",
  "name": "Standard Contract Template",
  "mimeType": "application/pdf",
  "optional": false,
  "instructions": "Please review and sign the contract",
  "createdAt": "2024-03-21T10:30:00Z"
}

---

Updates an existing document definition.

Endpoint

POST /api/v1/{customer}/documentdefinitions/{identifier}

Path parameters

Parameter	Type	Required	Description
customer	string	Yes	Your company identifier
identifier	string	Yes	Document definition identifier

Request

Headers

Header	Type	Required	Description
X-API-LOGIN-TOKEN	string	Yes	Auth token for authentication

Request Parameters

Same fields as Create Document Definition. All fields are optional — only the fields you include will be updated.

---

Permanently deletes a document definition.

Endpoint

DELETE /api/v1/{customer}/documentdefinitions/{identifier}

Path parameters

Parameter	Type	Required	Description
customer	string	Yes	Your company identifier
identifier	string	Yes	Document definition identifier

Request

Headers

Header	Type	Required	Description
X-API-LOGIN-TOKEN	string	Yes	Auth token for authentication

warning

Deleting a document definition will affect all identifications that reference it.

---

Retrieves all document definitions for your shortname.

Endpoint

GET /api/v1/{customer}/documentdefinitions

Path parameters

Parameter	Type	Required	Description
customer	string	Yes	Your company identifier

Request

Headers

Header	Type	Required	Description
X-API-LOGIN-TOKEN	string	Yes	Auth token for authentication

Response

{
  "documentDefinitions": [
    {
      "identifier": "contract_template_v1",
      "name": "Standard Contract Template",
      "mimeType": "application/pdf",
      "optional": false,
      "createdAt": "2024-03-21T10:30:00Z"
    },
    {
      "identifier": "privacy_policy",
      "name": "Privacy Policy Agreement",
      "mimeType": "application/pdf",
      "optional": true,
      "createdAt": "2024-03-20T15:20:00Z"
    }
  ],
  "total": 2
}

---

Retrieves a specific document definition by identifier.

Endpoint

GET /api/v1/{customer}/documentdefinitions/{identifier}

Path parameters

Parameter	Type	Required	Description
customer	string	Yes	Your company identifier
identifier	string	Yes	Document definition identifier

Request

Headers

Header	Type	Required	Description
X-API-LOGIN-TOKEN	string	Yes	Auth token for authentication

Response

{
  "identifier": "contract_template_v1",
  "name": "Standard Contract Template",
  "mimeType": "application/pdf",
  "optional": false,
  "instructions": "Please review and sign the contract",
  "sortOrder": 1,
  "createdAt": "2024-03-21T10:30:00Z"
}