Skip to main content

Quickstart guide

6 endpoints. Zero friction. Ship identity flows in minutes​

Ship identity flows in minutes, not weeks. One authentication. A small, stable set of endpoints. Unlimited identity journeys.

Prerequisite​

Before beginning your integration, ensure the following:

  • An organization was created in the IDnow dashboard
  • Your user in the IDnow dashboard has an Editor role
  • A flow was created in the IDnow dashboard and its version is published to staging or live
  • A webhook for the flow is configured on staging or live
  • You obtained a client ID and client secret by creating API credentials

Each published flow receives a flowId, used to create individual user sessions. Webhooks and API clients are environment‑specific and depend on the flow being published to the configured environment staging or live.

note

The environment specified in all API endpoint URLs must match the environment for which your API client was created. An API client created for staging can only access flows and sessions in the staging environment.

Integration steps​

  1. Authenticate: Request an access token using POST /oidc/token with your environment‑specific client ID and client secret.
  2. Get flows: Use GET /api/v1/flows/{environment} to list all flows published or promoted to the environment associated with your API client, and retrieve their id (the flow identifier).
  3. Create a session: Use POST /api/v1/flows/{flowId}/{environment}/sessions to create a user session and receive a playerUrl and sessionContext.sessionId.
  4. Listen to webhook events: Receive updates through webhook events and process the data.
  5. Track status and decisions: Poll GET /api/v1/{environment}/sessions/{sessionId} to retrieve sessionStatus and potential flow outcome.
  6. Get data blocks: Retrieve data blocks via GET /api/v1/{environment}/sessions/{sessionId}/datablocks.
  7. Get files: Retrieve files via GET /api/v1/{environment}/files/{vaultEntryId} only when needed.

Optionally

  1. Embed or redirect: Integrate IDnow’s Player into your frontend using the playerUrl returned by the create session response.

API-only steps (no Player UI)​

Some steps — such as Phone number verification (v1) — have no Player UI. Your backend drives the interaction directly through two additional endpoints:

EndpointPurpose
GET /api/v1/{environment}/sessions/{sessionId}/stepPoll for the current step state and the list of available actions
POST /api/v1/{environment}/sessions/{sessionId}/actionsSubmit a user action (e.g. validate an OTP, request a new code)

How it works:

  1. After creating the session (step 3 above), start polling GET /step every 2–3 seconds.
  2. The response always has a stepType. Keep polling while stepType === "START" (the engine is starting). When stepType matches the active step, check data.state: a non-null value means the step is ready for input; null means the step is running but requires no action (e.g. a headless processing step) — keep polling until stepType === "END" or the next interactive step.
  3. When the step is active, the response includes an actions array. Each entry has a type and a schema — use the schema to validate your request body before calling POST /actions.
  4. Pass the ticketId from the /step response as the X-Ticket-Id header on every POST /actions call.
  5. After submitting an action, poll GET /step again to observe the updated state.
  6. Stop polling when stepType === "END", then retrieve the outcome via GET /sessions/{sessionId}.

See the individual step guides for the full state machine, available actions, and error handling for each step type.

For complete endpoint documentation with parameters, schemas, and examples, see also API reference.

Obtain data blocks​

Data blocks are the structured outputs produced by each step of a flow. They are not returned automatically when creating a session or requesting session details and must be retrieved explicitly using GET /api/v1/{environment}/sessions/{sessionId}/datablocks.

note

APIs return only what you need. No bloat and no unnecessary PII exposure. Request full data when you need it, and ignore it when you don’t.

Create sessions with dynamic payloads​

The session creation payload is fully determined by the configured flow, more precisly the respective steps and its required input data blocks. Always review the required inputs and construct your payload accordingly.

The Trust Platform automatically generates a flow-specific OpenAPI schema for the session creation endpoint, helping you understand dynamic payload requirements and reduce errors when creating sessions.

Read more underdynamic payloads.

Environment and API versions​

Environments and versions are reflected directly in the endpoint base path.

The domain indicates the environment, using api.eu.platform.idnow.io for production and api.eu.platform.idnow.sx for sandbox. The API version is included as a versioned path segment such as /api/v1.

Each environment contains two logical environments — live and staging — which must be explicitly defined in the endpoint path, for example:

  • POST /api/v1/flows/{flowId}/{environment}/sessions

Example endpoint calls:

  • POST https://api.eu.platform.idnow.io/api/v1/flows/12345/live/sessions
  • POST https://api.eu.platform.idnow.sx/api/v1/flows/12345/staging/sessions