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	Unauthorized — 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://api.eu.platform.idnow.io/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.
• Use this spec to generate a typed API client or to discover the expected payload structure before creating a session.