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

# Identity verification API overview

> How Bastion signals when identity verification (IDV) is required for a KYC identity, and how to create an IDV check with a redirect URL for the customer.

For a subset of identities that are undergoing KYC, Bastion may require an additional identity verification (IDV) process. When required, Bastion emits the `identity_status_update` event.

<CodeGroup>
  ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "id": "01HZXISMEVT0000000000001",
    "type": "identity_status_update",
    "data": {
      "identity": {
        "id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
        "label": "user_ext_ref",
        "identity_type": "INDIVIDUAL",
        "status": "PENDING_ONBOARDING",
        "sub_status": "IDV_REQUIRED"
      },
      "affected_account_ids": [],
      "status_reason": null,
      "previous_status": "PENDING_ONBOARDING",
      "previous_sub_status": "COMPLIANCE_CHECKS_IN_PROGRESS"
    }
  }
  ```
</CodeGroup>

When IDV is required, create a new IDV by using the endpoint `/v2/identities/{identity_id}/id_verification`

**Request**

<CodeGroup>
  ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "identity_id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
    "redirect_url": "https://yourapp.example/idv/return",
    "reason": "ONBOARDING",
    "request_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }
  ```
</CodeGroup>

**Response**

<CodeGroup>
  ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  {
    "id": "01HZXIDVCHK0000000001",
    "identity_id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
    "verification_url": "https://idv.vendor.example/session/abc123",
    "reason": "ONBOARDING",
    "request_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "redirect_url": "https://yourapp.example/idv/return",
    "status": "IN_PROGRESS",
    "created_at": "2026-04-20T16:00:00Z",
    "updated_at": "2026-04-20T16:00:00Z"
  }
  ```
</CodeGroup>

Provide the returned `verification_url` to the onboarding end user to undergo IDV.

Continue polling (or listening to the webhook) for the identity `status` to turn to `ACTIVE` as the signal for completion of KYC.

* The source of truth for identity status is the identity's `status` field — from [GET identity](/v2/api-reference/identities/get-identity), or `data.identity.status` on the `identity_status_update` webhook. Do not rely on this endpoint's top-level `status`, which reports only the IDV check status.


## Related topics

- [Identities API overview](/v2/api-reference/identities/overview.md)
- [Compliance API overview](/v2/api-reference/compliance/overview.md)
- [Get Identity Verification Check](/v2/api-reference/identity-verification/get-identity-verification-check.md)
- [List Identity Verification Checks](/v2/api-reference/identity-verification/list-identity-verification-checks.md)
- [Create Identity Verification Check](/v2/api-reference/identity-verification/create-identity-verification-check.md)