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 startedin_progress - the applicant has opened the link and started the sessioncompleted - 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). |
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
