Skip to main content

Track step progress

Follow where a user is in a flow, and what the current step is waiting for​

Session events tell you when a session is created and how it ends. In between, a user can spend minutes capturing a document or waiting for a manual review. Step progress tells you where the user is during that time, and what the current step is waiting for, so you can follow a session without waiting for it to end.


The three step events​

Every step goes through the same events. Each one can reach you as a webhook, and the latest state is always available from the session endpoint.

EventWhen it is sentWhat you learn
step.startedA step beginsWhich step the user is on. Its progress is always IN_PROGRESS
step.updatedThe progress of a running step changesWhat the step is waiting for now, for example a manual review
step.endedA step finishes and the flow moves onThat the step is done. The flow carried on to the next step, or sent the user back (rolled back)

A few rules keep the stream easy to follow:

  • step.started always reports IN_PROGRESS. step.updated only follows a real change, so it never repeats the starting value and never fires when a step ends.
  • A step sends step.ended once. When the flow sends the user back, only the step that triggered it ends in a rollback. The steps it passes over had already ended, so they send nothing new, and the step the user is sent back to sends step.started again. One step can therefore start more than once in a session.
  • A step that is aborted or fails has no step event. The session events cover it: see Interpret session results.
  • To see whether a step moved on or was rolled back, read the session timeline. It shows the final picture of every attempt, including steps that were rolled back later.

Progress values​

ValueMeaning
IN_PROGRESSThe step is running and has nothing more specific to report
ENDUSER_INPUT_NEEDEDThe step is waiting for the user to act
IN_MANUAL_REVIEWThe step is waiting for a manual review of what the user submitted

Progress by step​

Each step may report one or more of the values above over its lifetime. Every running step begins at IN_PROGRESS. Any step not listed here reports IN_PROGRESS for as long as it runs. More steps and values may follow, so treat any value you don't recognise as IN_PROGRESS.

Document capture (IDC)​

Verifying ID document (IDC) (v2), (v3), (v4), (v5)

  1. IN_PROGRESS — set when the step starts, while the capture session is being prepared. The user cannot act yet.
  2. ENDUSER_INPUT_NEEDED — set once the capture session is ready; the step is now waiting for the user to capture their document, and holds this value until they do.
  3. IN_MANUAL_REVIEW — set only if the submission is sent for manual review; the step is waiting on a reviewer and nothing is expected from the user. Skipped if no review is needed.
  4. IN_PROGRESS — set once capture (and any review) is finished, while the result is processed. Nothing is expected from the user; the step is about to end.

Document capture and signing with manual review​

Verifying ID document (v2), (v3) · Signing incl. verifying ID (v1), (v2), (v3)

  1. IN_PROGRESS — set when the step starts, while the capture session is being prepared. The user cannot act yet.
  2. ENDUSER_INPUT_NEEDED — set once the capture session is ready; the step is now waiting for the user to capture or sign their document, and holds this value until they do.
  3. IN_MANUAL_REVIEW — set only if the submission is sent for manual review; the step is waiting on a reviewer and nothing is expected from the user. If no review is needed, the step ends without reporting this value.

eID, wallet and biometric verification steps​

Verifying eID (v1), (v2) · Verifying eID (France Identité) (v1) · Verifying using EUDI wallet (v1), (v2) · Biometric verification (v1)

  1. IN_PROGRESS — set when the step starts, while it is being set up. The user cannot act yet.
  2. ENDUSER_INPUT_NEEDED — set once setup is complete; the step is now waiting for the user to authenticate, present a credential, or complete the biometric check, and holds this value until they do.
  3. IN_PROGRESS — set after the user has finished, while the result is processed. Nothing is expected from the user; the step is about to end.

Single-input steps​

Verifying ID document (v1) · Verifying eID (Personalausweis) (v1) · Signing (v1) · Biometric enrolment (v1) · Method selector for verifying ID (v1), (v2) · Retry prompt (v1) · Verifying phone number (v1) · Biometric verification (v2)

  1. IN_PROGRESS — set when the step starts, before it is ready for the user.
  2. ENDUSER_INPUT_NEEDED — set once the step is ready; it is now waiting for the user to act, and holds this value until they do, after which the step ends.

Document review steps​

Verifying IBAN (v1) · Verifying proof of address (v1)

  1. IN_PROGRESS — set when the step starts; the submitted document is being analysed automatically. No user action is involved.
  2. IN_MANUAL_REVIEW — set only if the document is sent for manual review; the step is waiting on a reviewer. If no review is needed, the step ends without reporting this value.

Ways to follow progress​

Poll the session​

lastStep.stepProgress in the session response holds the current value. It is present while lastStep.stepStatus is STARTED, and absent otherwise.

GET /api/v1/{environment}/sessions/{sessionId}
{
"sessionStatus": "RUNNING",
"lastStep": {
"stepId": "step_docid_001",
"stepType": "SPHINX:v3",
"stepDescription": "Verify identity document",
"stepStatus": "STARTED",
"stepProgress": "IN_MANUAL_REVIEW"
}
}

Polling shows the current value only. A value that comes and goes between two requests is missed.

Receive step events​

Step events are webhooks. Select them next to the session events when you configure a webhook, and they reach your endpoint with the same delivery, retry and security rules as session events. As with session events, delivery order is not guaranteed: use eventSequence to put events back in order.

The event type tells you which of the three step events happened. See Webhook events for the fields every event carries.

Follow progress in the mobile SDK​

The mobile SDK reports the progress values above to your app while the SDK is on screen. The SDK reports progress, not steps: it tells your app what is happening, and your app decides what to do about it. For the code, see the iOS SDK and Android SDK pages. Short-lived values can be skipped, so use step events when you must not miss a change.


Example: a user waits for a manual review​

A flow with Verifying ID document (v3). The user captures their document, and the document is sent for manual review.

What happensWhat you can follow
The user reaches the stepstep.started, with IN_PROGRESS
The capture session is ready for the userstep.updated, to ENDUSER_INPUT_NEEDED
The user submits their document and review beginsstep.updated, to IN_MANUAL_REVIEW
The review finishesstep.ended, and the flow moves on along the route the review chose

While the review runs, your app can close the SDK and show its own waiting screen. When the step ends, your backend sees it, and decides whether to open the SDK again for the next step or to wait for the session to end.


Example: a user retries a step​

A flow where the cancelled route of Verifying ID document (v3) leads to Retry prompt (v1), and the prompt's retry route is a rollback.

What happensWhat you can follow
The user starts the verificationstep.started
The user cancels, and the step ends on cancelledstep.ended
The retry prompt is shownstep.started
The user chooses to retrystep.ended, with stepStatus ROLLED_BACK
The verification step runs againstep.started

A step can run more than once. When the user retries, the flow goes back to the verification step and starts a new attempt. To see which attempts were set aside, read the timeline: it lists them as ROLLED_BACK.


What to do with step events​

warning

A step that ends normally finished. It does not mean the user passed. The accepted or rejected decision only exists once the session completes, in the session's outcome. See Interpret session results.

  • Use step events to follow and react while a session runs: update a progress screen, notify the user, or release resources.
  • Use the session events to decide. When a session reaches a terminal status, call the timeline to fetch its final record.
  • Treat progress values as an open set and keep a default branch for values you don't recognise.

PageWhat it covers
Webhook eventsEvent types, payload fields and JWT verification
Configure webhooksCreate an endpoint and choose the events you receive
Get session resultsThe session endpoint and its lastStep fields
Get session timelineEvery step attempt in a session, including rolled back ones
Interpret session resultsWhat a session's status and outcome mean
iOS SDKUse the SDK in an iOS app
Android SDKUse the SDK in an Android app