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 a Verifying UK ID (eKYC) - API only (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 listed as properties but not marked as required. You must still send at least one of them. If both are missing, the request fails with a 412 MISSING_INPUT_DATA_BLOCKS error.
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 an ID document step (such as Verifying ID document - API only (IDC) (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 is the upload limit that applies to this flow. 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​