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.

Event	When it is sent	What you learn
step.started	A step begins	Which step the user is on. Its progress is always IN_PROGRESS
step.progress	The progress of a running step changes	What the step is waiting for now, for example a manual review
step.ended	A step finishes and the flow moves on	That 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.progress 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

Value	Meaning
IN_PROGRESS	The step is running and has nothing more specific to report
ENDUSER_INPUT_NEEDED	The step is waiting for the user to act
IN_MANUAL_REVIEW	The step is waiting for a manual review of what the user submitted

note

Today, only Verifying ID document (v2) and Verifying ID document (v3) report IN_MANUAL_REVIEW. Every other step reports IN_PROGRESS for as long as it runs, and no step reports ENDUSER_INPUT_NEEDED yet. Don't build logic that waits for a value no step reports. More steps and values will follow, so treat any value you don't recognise as IN_PROGRESS.

---

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 happens	What you can follow
The user reaches the step	step.started, with IN_PROGRESS
The user submits their document and review begins	step.progress, to IN_MANUAL_REVIEW
The review finishes	step.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 happens	What you can follow
The user starts the verification	step.started
The user cancels, and the step ends on cancelled	step.ended
The retry prompt is shown	step.started
The user chooses to retry	step.ended
The verification step runs again	step.started

The first step.ended says the step finished and the flow moved on. It does not change later, even though the retry sends the user back to that step. To tell a step that moved on from one that was rolled back, read the timeline: it shows the final picture and lists both earlier attempts 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.

---

Related pages

Page	What it covers
Webhook events	Event types, payload fields and JWT verification
Configure webhooks	Create an endpoint and choose the events you receive
Get session results	The session endpoint and its lastStep fields
Get session timeline	Every step attempt in a session, including rolled back ones
Interpret session results	What a session's status and outcome mean
iOS SDK	Use the SDK in an iOS app
Android SDK	Use the SDK in an Android app