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 /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 ( live or 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	Optional	Customer-scoped free-form key-value map (string values). Defaults to `{}`. 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"
  },
  "redirectUrl": "https://example.com/verification/complete",
  "state": "csrf-token-or-state-value"
}

Response

{
  "flowId": "40cbb7b3-7468-4b5d-8bb5-ff8e82510c70",
  "flowVersion": 2,
  "environment": "live",
  "sessionContext": {
    "sessionId": "123",
    "sessionStatus": "CREATED",
    "createdAt": "2024-11-04T10:30:00Z",
    "expiresAt": "2024-11-05T10:30:00Z"
  },
  "playerUrl": "https://player.eu.platform.idnow.io/player?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response parameters

Parameter	Type	Description
`flowId`	String	Flow identifier
`flowVersion`	String	Version of the flow being executed
`environment`	String	Environment where the session was created
`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
`sessionContext.expiresAt`	String	ISO 8601 timestamp of session expiration
`playerUrl`	String	url to start session on the Player

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

metadata is an optional object where you can attach your own session-related information.

It is customer-scoped, meaning it's for your internal use and business context.
It's a free-form key-value map: you can choose the field names, and the values must be strings.
Default value: {}

Commonly used keys:

subjectId: your internal reference ID for the user being verified

Create sessions with dynamic payloads

When creating a session, the payload you send is entirely defined by the flow that was configured. Each flow contains one or more steps. Each individual step specifies which input data block it requires.

Lets assume our flow consists only of a Trust service step called Instant signature issuance. The input data blocks required for this step are BasicIdentity and DocumentsToSign. Also, DocumentData might be required if the signatureLevel in the flow configuration was set to QES.

Some flows require several inputs, others only one, and some require none at all. Before creating a session for a specific flow, review the inputs required per step configured in the IDnow dashboard and construct the payload accordingly.

A full list of available steps and data blocks can be found under Platform-guides

Notes

Session status is set to CREATED upon successful creation and transitions to RUNNING once the first step starts executing
Input object format is analogous to the data block endpoint structure
Supports both interactive (customer-involved) and non-interactive (headless) flows
The playerUrl is a url and is used to start the session on the Player

Initiate a new verification session for a specific flow​

Endpoint​

Request​

Response​

Example​

Metadata​

Create sessions with dynamic payloads​

Notes​