---
title: "Initiate Tier 3 verification for a KYC request"
method: POST
path: "/v1/headless_kyc/{id}/initiate_tier_3_kyc"
tags: ["Headless KYC"]
---

# Initiate Tier 3 verification for a KYC request

`POST /v1/headless_kyc/{id}/initiate_tier_3_kyc`

## Request

- Base URL: `https://api.breeze.cash`
- URL: `https://api.breeze.cash/v1/headless_kyc/{id}/initiate_tier_3_kyc`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/breeze/apis/breeze-api/docs/v1/headless_kyc/:id/initiate_tier_3_kyc/post.ts> (a function with typed inputs; its response is checked against the schema)

Starts the user-facing part of a Tier 3 KYC request and returns the request with its `actionLink`: a hosted verification link the end user must open to complete the Tier 3 identity checks.

Tier 3 requests are raised by Breeze, not submitted by the merchant. A new Tier 3 request is created in the `pending_user_info` status and announced through the `HEADLESS_KYC_STATUS_UPDATED` webhook; call this endpoint with its `id` when you are ready to send the user through verification. Only requests with `tier` set to `TIER_3` are accepted — any other request ID is answered with `RESOURCE_NOT_FOUND`.

The call is idempotent and safe to repeat: while the request is `pending_user_info`, every call returns a usable `actionLink`. A verification link expires after some time; when that happens the next call issues a replacement, so always hand the user the `actionLink` from the most recent response rather than one stored earlier. Once the request has left `pending_user_info` (the user completed verification, or Tier 3 was approved by other means) the request is returned as-is and no link is issued.

Status changes after the user completes the link are delivered through the `HEADLESS_KYC_STATUS_UPDATED` webhook, exactly as for Tier 2 requests.

**Note:** This endpoint is only available to merchants configured by the Breeze team. Please reach out to the Breeze team to find out more.

## Path parameters

- `id` string, required

## Response `200`

Success

- object: The Tier 3 KYC request, including `actionLink` while user action is still pending
  - `status` 'SUCCEEDED', required
  - `data` InitiateHeadlessKycTier3Response, required: Response data for headless KYC endpoints
    - `id` string, required
    - `customerId` string
    - `accountId` string
    - `kycId` string
    - `kycStatus` 'processing' | 'approved' | 'rejected' | 'under_review' | 'pending_user_info', required
    - `customerReferenceId` string, required
    - `tier` 'TIER_3', required
    - `rejectionReason` string
    - `actionLink` string: Hosted verification link the end user must open to finish the tier's identity checks. Only present once a flow that needs user action has been initiated (Tier 3 today). May change between calls once the previous Persona inquiry has expired.
    - `createdAt` number, required
    - `updatedAt` number, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized

## Changes

- **2026-11-03** `4af083d182a6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/breeze/apis/breeze-api/changes/v1/headless_kyc/:id/initiate_tier_3_kyc/post.md)

---

[API](https://skmtc.dev/breeze/apis/breeze-api.md) - [All operations](https://skmtc.dev/breeze/apis/breeze-api/llms.txt) - [OpenAPI document](https://skmtc.dev/breeze/apis/breeze-api/revisions/4af083d182a6?raw)