Get flow OpenAPI spec

Retrieve a flow-specific OpenAPI specification for the create-session endpoint

Use this endpoint to obtain an OpenAPI 3.0 specification tailored to a specific flow. The returned spec describes the create-session endpoint with a request body schema that includes only the data blocks required by that flow. This is useful for generating typed API clients or for validating payloads before creating a session.

Endpoint

GET /api/v1/flows/{environment}/{flowId}

Path parameters

Parameter	Type	Required	Description
`environment`	string	Yes	Environment identifier (e.g. `live`, `staging`)
`flowId`	string	Yes	The unique identifier of the flow

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for authentication

Request

No request body is required for this endpoint.

Response

Returns an OpenAPI 3.0 specification object. The paths section contains a single POST endpoint for creating a session, with a request body schema restricted to the data blocks required by the flow.

The info object includes flow metadata as extension fields:

Field	Type	Description
`info.title`	string	Flow display name
`info.description`	string	Flow description
`info.version`	string	Deployed flow version number
`info.x-flow-id`	string	Flow unique identifier
`info.x-flow-version`	number	Deployed flow version number (numeric)
`info.x-environment`	string	Environment (`live` or `staging`)

{
  "openapi": "3.0.0",
  "info": {
    "title": "Document-based IDV - Capture",
    "description": "Verifies identity by capturing and checking official ID documents",
    "version": "2",
    "x-flow-id": "082dc7d8-05cb-458b-9767-241b109097fb",
    "x-flow-version": 2,
    "x-environment": "live"
  },
  "servers": [{ "url": "https://api.eu.platform.idnow.io" }],
  "paths": {
    "/api/v1/flows/082dc7d8-05cb-458b-9767-241b109097fb/live/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][familyName]": { "type": "string" },
                  "input[basicIdentity][givenName]": { "type": "string" },
                  "input[documentImages][front]": { "type": "string", "format": "binary" },
                  "metadata[subjectId]": { "type": "string" }
                },
                "required": [
                  "input[basicIdentity][familyName]",
                  "input[basicIdentity][givenName]",
                  "input[documentImages][front]",
                  "metadata[subjectId]"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Session successfully created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreateSessionResponse" }
              }
            }
          },
          "400": {
            "description": "Bad request - validation error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Unauthorised - invalid or missing token",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "403": {
            "description": "Forbidden - environment mismatch",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "404": {
            "description": "Flow not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateSessionResponse": {
        "type": "object",
        "properties": {
          "flowId": { "type": "string", "format": "uuid" },
          "environment": { "type": "string", "enum": ["live", "staging"] },
          "flowVersion": { "type": "integer" },
          "playerUrl": { "type": "string" },
          "sessionContext": {
            "type": "object",
            "properties": {
              "sessionId": { "type": "string", "format": "uuid" },
              "sessionStatus": {
                "type": "string",
                "enum": ["CREATED", "RUNNING", "COMPLETED", "ERROR", "EXPIRED", "ABORTED"]
              },
              "createdAt": { "type": "string", "format": "date-time" }
            },
            "required": ["sessionId", "sessionStatus"]
          },
          "metadata": {
            "type": "object",
            "properties": {
              "subjectId": { "type": "string" },
              "locale": { "type": "string" }
            },
            "required": ["subjectId"]
          }
        },
        "required": [
          "flowId",
          "environment",
          "flowVersion",
          "playerUrl",
          "sessionContext",
          "metadata"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "statusCode": { "type": "integer" },
          "timestamp": { "type": "string", "format": "date-time" },
          "path": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    },
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}

Error responses

Status	Description
`400`	Bad request — invalid environment value
`401`	Unauthorised — invalid or missing token
`403`	Forbidden — environment mismatch
`404`	Flow not found, or no deployed version in this environment
`500`	Internal server error

Example

curl https://localhost:3000/api/v1/flows/live/082dc7d8-05cb-458b-9767-241b109097fb \
-H "Authorization: Bearer YOUR_API_KEY"

Notes

The flow must have an active deployment in the specified environment. If no version is deployed, a 404 is returned.
The request body schema in the returned spec reflects the exact data blocks required by the current deployed version of the flow.
Individual fields within a data block may be promoted to required when at least one step in the flow demands them. For example, a flow containing an EKYC_UK_V1 step marks givenName, familyName, and birthDate as required within basicIdentity, and residentPostalCode as required within extendedIdentity:
```
"input[basicIdentity][givenName]": { "type": "string" },
"input[basicIdentity][familyName]": { "type": "string" },
"input[basicIdentity][birthDate]": { "type": "string" },
"input[extendedIdentity][residentPostalCode]": { "type": "string" },
"input[extendedIdentity][residentHouseNumber]": { "type": "string" },
"input[extendedIdentity][residentHouseName]": { "type": "string" }
```
with givenName, familyName, birthDate, and residentPostalCode in the required array. residentHouseNumber and residentHouseName are included as properties but are not individually required in the spec — the step enforces an OR constraint (at least one must be present) at runtime, returning a 412 MISSING_INPUT_DATA_BLOCKS error if both are absent. JSON Schema cannot express OR-required constraints, so the spec reflects only individually-required fields.
Field-level enums within a data block may be narrowed beyond the data block's default set. This narrowing applies to any field-level constraint declared by a step in the flow, not only documentType. For example:
- A flow containing an IBAN verification step restricts documentType to a single value:
```
"input[documentImages][documentType]": { "type": "string", "enum": ["IBAN"] }
```
- A flow containing a document ID capture step (such as DOC_ID_HEADLESS_V2) restricts documentType to the six supported ID-category values:
```
"input[documentImages][documentType]": {
  "type": "string",
  "enum": ["ID", "PASSPORT", "RESIDENT_PERMIT", "VISA", "DRIVING_LICENSE", "HEALTH_CARD"]
}
```
  Integrators who generate clients or validate payloads against a cached version of this spec should re-fetch it whenever the flow definition changes, as narrowed enums will cause 412 errors if a disallowed value is submitted.
Use this spec to generate a typed API client or to discover the expected payload structure before creating a session.

Retrieve a flow-specific OpenAPI specification for the create-session endpoint​

Endpoint​

Request​

Response​

Error responses​

Example​

Notes​