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.

What is Trust Platform?​

IDnow Trust Platform brings identity verification, fraud prevention and regulatory compliance together in one platform. Instead of integrating a single check, you compose a flow: a sequence of verification and risk steps, such as document verification, eID or EUDI Wallet checks, AML screening, biometrics and fraud signals. Each user runs through the flow as a session, following the path that fits them.

Each session records a complete, auditable trail of what happened and why, and ends with a business decision (accepted or rejected) plus the structured data behind it. Because everything is orchestrated through one platform, you integrate once: you can add, switch or fine-tune services and flows later without redoing your integration.

How it works​

  1. Design: build a flow in the IDnow dashboard and publish it to staging or live.
  2. Start: your backend creates a session for a user through the API (or hands the session to the mobile SDK).
  3. Run: the user completes the flow in IDnow's Player or in your app through the mobile SDK.
  4. Decide: a webhook tells you the session ended; your backend reads the outcome and the data blocks and acts on them.

What Trust Platform orchestrates​

Flows combine steps from IDnow and selected third-party services. Some examples:

For the full set of steps, see the Platform guides. To see what you can orchestrate, observe and decide with the platform, see Capabilities & Features.

For the building blocks behind flows, see Core concepts. To follow one user through a flow from start to finish, see How a verification works.

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 Verifying phone number - API only (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. GET /step returns 400 Bad Request while the session status is still CREATED. If your first calls return 400, keep polling.
  2. The response always has a stepType. Keep polling while stepType is "START". This means the session has not yet reached a step that accepts API actions. When stepType names a step, check ticketId. If it is set, the step is waiting for your input. If it is null, no action is needed yet, so keep polling until the next interactive step or until stepType is "END".
  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. 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://localhost:3000/api/v1/flows/12345/live/sessions
POST https://localhost:3000/api/v1/flows/12345/staging/sessions

Where to go next​