List sessions

Retrieves a paginated list of sessions

Retrieves a paginated list of sessions for a specific flow. Supports pagination through query parameters.

Endpoint

GET /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 name

Query parameters

Parameter	Type	Required	Default	Description
page	number	No	1	Page number for pagination
size	number	No	20	Number of items per page. Maximum: 100.
sortBy	string	No	createdAt	Field to sort by. One of status, createdAt, or updatedAt.
sortDesc	boolean	No	true	Sort in descending order

Request

No request body is required for this endpoint.

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Response

Response parameters

Parameter	Type	Description
content	array	Array of session objects
flowId	string	Flow identifier
flowVersion	number	Version of the flow executed
environment	string	Environment name
subjectId	string	Deprecated — use metadata.subjectId instead. The provided reference ID for the user.
sessionId	string	The unique identifier of the session
sessionStatus	string	Current status. One of CREATED, RUNNING, COMPLETED, EXPIRED, ABORTED, or ERROR
createdAt	string	ISO 8601 timestamp when session was created
startedAt	string	ISO 8601 timestamp when processing started (null if not started)
updatedAt	string	ISO 8601 timestamp of last update
completedAt	string	ISO 8601 timestamp when session completed
expiresAt	string	ISO 8601 timestamp when session expires. Omitted (key absent) when no expiry is set — it is never null.
outcome	string	Final session outcome. "accepted" or "rejected" when sessionStatus is COMPLETED; "NO_OUTCOME" otherwise.
metadata	object	Customer metadata provided at session creation.
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, pl, it, es.
redirectUrl	string	Redirect URL for session completion (optional)
state	string	State parameter for CSRF protection in redirect (optional)
lastStep	object	Information about the last executed step (optional, present whenever at least one step has been executed)
lastStep.stepId	string	Unique identifier of the last step
lastStep.stepType	string	Type of the last step (e.g., END, DOC_ID:v2, CHOICE)
lastStep.stepDescription	string	Human-readable description of the step (as configured in the flow). Empty string if not set.
lastStep.verdict	string	Deprecated — use lastStep.stepStatus instead. Last step verdict (e.g., COMPLETED, FAILED)
lastStep.stepStatus	string	Internal execution status of the step. One of STARTED, COMPLETED, ERROR, ABORTED, WORKFLOW_EXPIRED, ROLLED_BACK.
lastStep.stepStatusDetails	string	Error detail when stepStatus is ERROR. Absent otherwise.
results	object	References to the output data blocks produced by the flow. Always present as an object. Empty () when the session has not yet started (CREATED, RUNNING), or when terminal (COMPLETED, ERROR, EXPIRED, ABORTED) but no step produced any output. Keys are data block type names.
results.<type>	object	A typed reference to a data block. The key is the data block type (e.g., documentVerification).
results.<type>.type	string	Reference discriminator. Always "dataBlock".
results.<type>.id	string	The dataBlockId of the referenced data block.

{
  "content": [
    {
      "sessionId": "0197c55f-5af6-7e3d-af9b-f2359b134be8",
      "sessionStatus": "COMPLETED",
      "flowId": "0197c55f-5af6-7e3d-af9b-f2359b154be8",
      "flowVersion": 1,
      "environment": "live",
      "subjectId": "subj_8f3a2c91b47d4e6b",
      "outcome": "accepted",
      "createdAt": "2025-01-07T10:30:00.000Z",
      "startedAt": "2025-01-07T10:30:00.000Z",
      "updatedAt": "2025-01-07T10:35:00.000Z",
      "completedAt": "2025-01-07T10:35:00.000Z",
      "metadata": {
        "subjectId": "subj_8f3a2c91b47d4e6b"
      },
      "lastStep": {
        "stepId": "step_end_001",
        "stepType": "END",
        "stepDescription": "Final step",
        "verdict": "COMPLETED",
        "stepStatus": "COMPLETED"
      },
      "results": {
        "documentVerification": {
          "type": "dataBlock",
          "id": "0197c55f-5af6-7e3d-af9b-f2359b200be1"
        }
      }
    }
  ],
  "page": {
    "size": 20,
    "number": 1,
    "totalElements": 25,
    "totalPages": 2
  }
}

Example

curl https://localhost:3000/api/v1/flows/12345/live/sessions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"

Notes

• Response implements data minimization by default for GDPR compliance
• If the session outcome is not accepted, the lastStep object provides debugging context
• Data block access is separated to allow granular access control

---