Identity verification API overview

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.

{
  "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"
  }
}

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

{
  "identity_id": "01HZX8QK9VM5T9JY8ZQXQZQXQZ",
  "redirect_url": "https://yourapp.example/idv/return",
  "reason": "ONBOARDING",
  "request_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Response

{
  "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"
}

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, 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.

Authentication

API Reference

Webhooks

Identity verification API overview