> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equalsmoney.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Guided ID status

> Track the status of Guided identity verification (guided ID) - get notified as it changes, or fetch the current state on demand.

## How it works

Guided identity verification (guided ID) is the step in [onboarding](/pages/accounts/about-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.

<Info>
  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.
</Info>

## 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](/pages/accounts/tutorial/onboarding-webhooks). For the full payload structure, see [`IdentityVerificationStatusUpdated` event details](/pages/webhooks/about-event-types#identityverificationstatusupdated).

<Tip>
  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.
</Tip>

## 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

```bash theme={null}
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'
```

```json theme={null}
{
  "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**](/pages/accounts/tutorial/onboarding-webhooks) - Track an application through to approval, including where the status webhook fits the flow
* [**About KYC profiles**](/pages/accounts/about-kyc-profile) - Retrieve the verified identity-document details captured during verification
* [**About onboarding**](/pages/accounts/about-onboarding) - How accounts are created and verified