Create a session
Initiate a new verification session for a specific flow
Create a new session to initiate a Trust Platform flow. It returns the session with sessionStatus: "CREATED". The flow starts immediately and the status moves to RUNNING.
Creates a new session instance for a specified flowId and returns session details. The request payload is dynamic. Create sessions with dynamic payloads by providing exactly the data blocks required by the flow's configured steps, as defined in the flow configuration.
Endpoint
POST /api/v1/flows/{flowId}/{environment}/sessions
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
flowId | string | Yes | The unique identifier of the flow used to execute the session |
environment | string | Yes | Environment identifier (e.g. live, staging) |
Request
Headers
| Header | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer token for authentication |
Content-Type | string | Yes | application/json or multipart/form-data |
Request parameters
| Field | Type | Required | Description |
|---|---|---|---|
input | object | Optional | Dynamic payload containing the data blocks required by the flow's configured steps. Keys are data block names in camelCase (e.g., basicIdentity, documentImages). Defaults to {}. |
metadata | object | Yes | Customer-scoped session data. Only subjectId and locale are accepted. See Metadata. |
redirectUrl | string | Optional | URL to redirect the user after session completion. Must be allowlisted in the IDnow dashboard. |
state | string | Optional | Opaque value echoed back in the redirect URL (e.g., for CSRF protection). Max 2048 characters. |
{
"input": {
"basicIdentity": {
"familyName": "Schmidt",
"givenName": "Max",
"birthDate": "1985-08-22"
},
"documentImages": {
"documentType": "ID",
"frontSide": "byte array",
"backSide": "byte array"
}
},
"metadata": {
"subjectId": "customer-internal-subject-id-123",
"locale": "en"
},
"redirectUrl": "https://example.com/verification",
"state": "csrf-token-or-state-value"
}
Response
{
"flowId": "40cbb7b3-7468-4b5d-8bb5-ff8e82510c70",
"flowVersion": 2,
"environment": "live",
"sessionContext": {
"sessionId": "0197c55f-5af6-7e3d-af9b-f2359b104be8",
"sessionStatus": "CREATED",
"createdAt": "2024-11-04T10:30:00.000Z"
},
"metadata": {
"subjectId": "customer-internal-subject-id-123",
"locale": "en"
},
"playerUrl": "https://player.eu.platform.idnow.io/player?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Response parameters
| Parameter | Type | Description |
|---|---|---|
flowId | string | Flow identifier |
environment | string | Environment where the session was created |
flowVersion | number | Version of the flow being executed |
playerUrl | string | URL to start the session on the Player |
sessionContext | object | Session context |
sessionContext.sessionId | string | Unique session identifier |
sessionContext.sessionStatus | string | Initial status: CREATED |
sessionContext.createdAt | string | ISO 8601 timestamp of session creation |
metadata | object | Customer metadata echoed back from the request |
metadata.subjectId | string | Your internal reference ID for the subject being verified |
metadata.locale | string | Locale for the Player UI (optional). One of en, de, fr. |
Example
curl https://api.eu.platform.idnow.io/api/v1/flows/12345/live/sessions \
-X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"basicIdentity": {
"familyName": "Schmidt",
"givenName": "Max",
"birthDate": "1985-08-22"
}
},
"metadata": {
"subjectId": "customer-internal-subject-id-123"
}
}'
Metadata
metadata is a required object containing customer-scoped session data. Only the two fields below are accepted — any additional key will be rejected with 400 Bad Request.
| Field | Type | Required | Description |
|---|---|---|---|
subjectId | string | Yes | Your internal reference ID for the user being verified |
locale | string | No | Locale for the Player UI. Supported values: en, de, fr. Defaults to en. |
Do not store personally identifiable information (PII) in metadata. No encryption is applied to this field — values may appear in logs and audit trails.
- A
UserReferencedata block is automatically generated from thesubjectIdvalue and made available to all steps in the flow. You do not need to provide it in theinputobject. metadatais echoed back in all session responses (create sessionandget session).
Create sessions with dynamic payloads
When creating a session via the API, the request payload is entirely determined by the configured flow.
Each configured flow consists of one or more steps. Some but not all of these steps require input data blocks, which in turn define the structure of the session creation request payload.
Example
Assume a flow that consists of a single Trust Service step: [Instant signature issuance](/docs/platform-guides/instant-signature-issuance.
This step requires always following input data blocks:
BasicIdentityDocumentsToSign
Optionally DocumentData may be required if the signatureLevel in the flow configuration is set to QES as shown in the example below.
{
"openapi": "3.0.0",
"info": {
"title": "instant_signiture_issance_with_qes",
"description": "",
"version": "7",
"x-flow-id": "de74a1b6-ca7d-4222-ae03-a4292b7da07c",
"x-flow-version": 7,
"x-environment": "staging"
},
"servers": [
{
"url": "https://api.eu.platform.idnow.io"
}
],
"paths": {
"/api/v1/flows/de74a1b6-ca7d-4222-ae03-a4292b7da07c/staging/sessions": {
"post": {
"summary": "Create a session",
"operationId": "createSession",
"description": "Creates a new session for this flow. The request body includes only the data blocks required by this specific flow.",
"security": [
{
"bearer": []
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"input[basicIdentity][givenName]": {
"type": "string",
"maxLength": 150
},
"input[basicIdentity][familyName]": {
"type": "string",
"maxLength": 150
},
"input[basicIdentity][name]": {
"type": "string",
"maxLength": 150
},
"input[basicIdentity][birthDate]": {
"type": "string"
},
"input[basicIdentity][birthPlace]": {
"type": "string",
"maxLength": 150
},
"input[documentsToSign][documents]": {
"type": "array",
"items": {
"type": "object",
"properties": {
"templateId": { "type": "string" },
"source": {
"type": "string",
"format": "binary"
}
},
"required": ["templateId", "source"]
}
},
"metadata[subjectId]": {
"type": "string"
},
"metadata[locale]": {
"type": "string",
"enum": ["en", "de", "fr"]
},
"redirectUrl": {
"type": "string"
},
"state": {
"type": "string"
}
},
"required": [
"input[basicIdentity][givenName]",
"input[basicIdentity][familyName]",
"input[documentsToSign][documents]",
"metadata[subjectId]"
]
}
}
}
},
"responses": {
"201": {
"description": "Session successfully created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"flowId": {
"type": "string"
},
"environment": {
"type": "string"
},
"flowVersion": {
"type": "number"
},
"playerUrl": {
"type": "string"
},
"sessionContext": {
"type": "object",
"properties": {
"sessionId": {
"type": "string"
},
"sessionStatus": {
"type": "string"
},
"createdAt": {
"type": "string"
}
}
},
"metadata": {
"type": "object",
"properties": {
"subjectId": {
"type": "string"
},
"locale": {
"type": "string",
"enum": ["en", "de", "fr"]
}
},
"required": ["subjectId"]
}
}
}
}
}
}
}
}
}
}
}
Programmatically get a flow-specific OpenAPI schema
Trust Platform can automatically generate a flow-specific OpenAPI specification for the session creation endpoint. This specification clearly defines which data blocks are required for a given flow by providing a tailored request body schema for the create-session API.
It helps you understand dynamic, flow-specific payloads, generate typed API clients, and reduce errors when creating sessions.
Download OpenAPI specification from dashboard
Go to Flows → Your Flow → Versions, then click "Download" above the flow funnel to download the OpenAPI file. You can import the file into tools like Postman to test session creation requests directly.
Available only for flows published to staging or live.
Or get OpenAPI specification via API
You can also retrieve the OpenAPI schema for a specific flow by using the flow ID with the Get flow OpenAPI spec endpoint.