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][frontSide]": {
                    "type": "string",
                    "format": "binary",
                    "maxLength": 26214400,
                    "description": "Front side document image. Accepted formats: JPEG, PNG. Maximum size: 25 MB."
                  },
                  "metadata[subjectId]": { "type": "string" },
                  "redirectUrl": { "type": "string" },
                  "state": { "type": "string" }
                },
                "required": [
                  "input[basicIdentity][familyName]",
                  "input[basicIdentity][givenName]",
                  "input[documentImages][frontSide]",
                  "metadata[subjectId]"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Session successfully created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "flowId": { "type": "string", "format": "uuid" },
                    "environment": { "type": "string", "enum": ["live", "staging"] },
                    "flowVersion": { "type": "number" },
                    "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"
                  ]
                }
              }
            }
          },
          "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": {
      "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",
        "bearerFormat": "JWT"
      }
    }
  }
}

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.
Binary fields (those with "format": "binary") carry a maxLength extension and a human-readable size hint in description (e.g. "Maximum size: 25 MB"). The value reflects the upload limit configured for the flow's product type. Use maxLength to enforce the limit client-side before uploading.
The path parameter order differs between this endpoint and the create-session path embedded in the returned spec. This endpoint uses environment before flowId (GET /api/v1/flows/{environment}/{flowId}), while the create-session path in the spec uses flowId before environment (/api/v1/flows/{flowId}/{environment}/sessions). Take care not to swap the parameters when constructing either URL.
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​