Track Guided ID status

How it works

Guided identity verification (Guided ID) is the step in onboarding where an applicant proves their identity. Equals issues them a link to a hosted verification session, where they complete a liveness check and upload an identity document (in some cases we also ask for proof of address and visa / residence permit). Once the link has been issued, you can track how each applicant is progressing — whether they’ve opened it or completed it, and what the outcome was. There are two ways to consume the same information:

Get notified (push) - subscribe to the IdentityVerificationStatusUpdated webhook to receive each state change as it happens.
Fetch on demand (pull) - call the list sessions endpoint to retrieve the current state whenever you need it.

Both report the same status and result values and share a correlationId, so you can use either or both. Results are always scoped to your own product - you only ever see sessions for applications and people that belong to you.

Guided ID sessions are only issued under the Managed by Equals KYC model. Under the Hybrid or Delegated model you handle verification yourself, so no sessions are created.

The status lifecycle

Every session moves through the same lifecycle, reported by the status field:

to_be_completed - the verification link has been issued but not yet started
in_progress - the applicant has opened the link and started the session
completed - the applicant has finished the session; a result is included

When status is completed, a result is included: approved, declined, or resubmission_requested. The result field is omitted (not null) for every other status.

Get notified (push)

If you subscribe to the IdentityVerificationStatusUpdated webhook, you’ll receive an event each time a session changes state - so you can surface progress without polling. Because the status changes more than once, this event may fire multiple times for the same applicant. Each event identifies the subject with exactly one of applicationId (personal application) or associatedPersonId (an associated person on a business application), and carries the correlationId, status, and - once completed - the result. The webhook fires during the onboarding sequence, so it’s also covered in the onboarding webhooks guide. For the full payload structure, see IdentityVerificationStatusUpdated event details.

If you can’t host a webhook receiver, or need to reconcile state after a missed or duplicated delivery, use the pull endpoint below instead.

Fetch on demand (pull)

Call GET /v2/applications/identity-verification-sessions to retrieve a paginated list of sessions, sorted by createdAt descending (newest first), using the standard list envelope (count, limit, offset, rows). Use this when:

You can’t host a webhook receiver - poll the endpoint instead of subscribing.
You need an ad-hoc status check - answer “where is this applicant up to?” on demand.
You’re reconciling - recover state after a missed or duplicated webhook delivery, matching on correlationId.

Filtering

Use the optional query parameters to narrow the list:

Parameter	Description
`applicationId`	Return sessions for this application.
`associatedPersonId`	Return sessions for this associated person. May span multiple applications.
`limit`	Maximum number of rows to return (default 100).
`offset`	Number of rows to skip, for pagination (default 0).

Passing both applicationId and associatedPersonId returns the intersection. Passing no filter returns every session visible to your product.

Response

Each row in rows has the following shape:

Field	Type	Description
`id`	string (UUID)	Unique identifier of the session.
`applicationId`	string (UUID)	The application this row reports against. Always present.
`associatedPersonId`	string (UUID)	The associated person (director or UBO) the session relates to. Present for business applications only.
`correlationId`	string (UUID)	Identifier shared with the matching `IdentityVerificationStatusUpdated` webhook event.
`actionUrl`	string (URL)	The Guided ID link issued to the applicant.
`status`	enum	The current state of the session. One of `to_be_completed`, `in_progress`, or `completed`.
`result`	enum	The verification outcome. One of `approved`, `declined`, or `resubmission_requested`. Only present when `status` is `completed`.
`createdAt`	string (ISO 8601)	When the session was created.
`updatedAt`	string (ISO 8601)	When the session was last updated.

Example

curl -i -X GET \
  'https://api.equalsmoney.com/v2/applications/identity-verification-sessions?applicationId=7b3e4d2a-1f5c-4a8b-9e6d-0c2f8a7b3e4d' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

{
  "count": 2,
  "limit": 100,
  "offset": 0,
  "rows": [
    {
      "id": "e9293471-5eb3-4dbc-916c-dbaf9e2deefd",
      "applicationId": "7b3e4d2a-1f5c-4a8b-9e6d-0c2f8a7b3e4d",
      "associatedPersonId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "correlationId": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
      "actionUrl": "https://verify.example.com/session/abc123",
      "status": "completed",
      "result": "approved",
      "createdAt": "2026-06-10T10:00:00.000Z",
      "updatedAt": "2026-06-10T10:15:00.000Z"
    },
    {
      "id": "a4f5b6c7-d8e9-4012-9abc-def012345678",
      "applicationId": "7b3e4d2a-1f5c-4a8b-9e6d-0c2f8a7b3e4d",
      "associatedPersonId": "d4e5f6a7-b8c9-0123-def0-123456789012",
      "correlationId": "e3f4a5b6-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
      "actionUrl": "https://verify.example.com/session/xyz789",
      "status": "to_be_completed",
      "createdAt": "2026-06-11T08:00:00.000Z",
      "updatedAt": "2026-06-11T08:00:00.000Z"
    }
  ]
}

Personal vs business applications

How sessions map to rows depends on the application type:

For a personal application, the session belongs to the applicant. applicationId is the applicant’s application and associatedPersonId is omitted.
For a business application, sessions belong to the associated people (directors, UBOs, and the applicant), so each row also carries associatedPersonId.

A single underlying session can relate to a person who is on more than one application. In that case the session appears once per application: the rows share the same id but differ in applicationId. Because pagination counts rows rather than unique sessions, one session for a person on three applications counts as three rows.

Reconciling push and pull

The webhook and the endpoint describe the same sessions, so you can safely combine them - for example, subscribe to the webhook for real-time updates and fall back to the endpoint to recover from a missed delivery. Match a pulled row to a webhook event using correlationId, which is identical on both sides.

Things to know

result is omitted (not null) whenever status is anything other than completed - on both the webhook and the endpoint.
associatedPersonId is present only for business applications; personal rows and events don’t carry it.
In the pull response, rows that share an id but differ in applicationId describe the same session reported against different applications - don’t treat them as separate sessions.
You can only see sessions for applications and people belonging to your own product.

Next steps

Onboarding webhooks - Track an application through to approval, including where the status webhook fits the flow
About KYC profiles - Retrieve the verified identity-document details captured during verification
About onboarding - How accounts are created and verified

Group placeholder

Group

Group

How it works

The status lifecycle

Get notified (push)

Fetch on demand (pull)

Filtering

Response

Example

Personal vs business applications

Reconciling push and pull

Things to know

Next steps

​How it works

​The status lifecycle

​Get notified (push)

​Fetch on demand (pull)

​Filtering

​Response

​Example

​Personal vs business applications

​Reconciling push and pull

​Things to know

​Next steps

How it works

The status lifecycle

Get notified (push)

Fetch on demand (pull)

Filtering

Response

Example

Personal vs business applications

Reconciling push and pull

Things to know

Next steps