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
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 data with mandatory subjectId. 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:00Z"
},
"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 session on the Player |
sessionContext | Object | Session metadata |
sessionContext.sessionId | String | Unique session identifier |
sessionContext.sessionStatus | String | Initial status: CREATED |
sessionContext.createdAt | String | ISO 8601 timestamp of session creation |
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.
- It must include a
subjectIdfield: your internal reference ID for the user being verified. - 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. - Beyond
subjectId, it is a free-form key-value map: you can add any additional fields, and the values can be of any type.
| 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. |
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"
}
}
}
}
}
}
}
}
}
}
}
}
}
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.