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

# Customer verification

> Submit and track the KYC or KYB required for customer-scoped products.

<Note>
  Customer verification APIs are in preview as part of USD Virtual Accounts.
</Note>

Verification belongs to the customer, not your merchant transfer profile. A customer must complete
Tier 2 verification and have an approved `usd_banking` capability before you can create their USD
virtual account.

## Verification path

| Customer type | Required order                                              |
| ------------- | ----------------------------------------------------------- |
| `INDIVIDUAL`  | Submit `TIER_1`, wait for completion, then submit `TIER_2`. |
| `BUSINESS`    | Submit `TIER_2`. Business customers do not submit Tier 1.   |

Each request creates an immutable verification submission. If a submission is rejected and the
customer corrects their information, create a new submission. Previous attempts remain available
in the submission history.

## Submit individual Tier 1

```bash theme={null}
curl https://api.yara.cash/v1/customers/908a76cf-4ff1-4e0e-bda4-d3a939970abc/verification-submissions \
  --request POST \
  --header "x-yara-api-key: $YARA_API_KEY" \
  --header "X-Idempotency-Key: $(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
    "tier": "TIER_1",
    "bvn": "22345678901",
    "image_url": "https://files.example.com/selfie.jpg"
  }'
```

The endpoint returns `202 Accepted`. It does not echo the submitted verification fields.

```json theme={null}
{
  "data": {
    "id": "a9203946-43ef-45ed-a806-7b0bbd3de424",
    "customer_id": "908a76cf-4ff1-4e0e-bda4-d3a939970abc",
    "tier": "TIER_1",
    "customer_type": "INDIVIDUAL",
    "status": "PENDING",
    "rejection_reasons": [],
    "submitted_at": "2026-08-03T12:05:00Z",
    "created_at": "2026-08-03T12:05:00Z",
    "updated_at": "2026-08-03T12:05:00Z"
  }
}
```

## Submit Tier 2

Tier 2 collects the customer information required for USD banking. The fields depend on the stored
customer type:

* Individuals submit their address, date of birth, account purpose, expected activity, employment,
  source of funds, nationality, and identifying document.
* Businesses submit their legal information, registered address, expected activity, associated
  control persons and signers, tax identification, and supporting documents.

Yara derives the verification shape from the customer record. You cannot change the customer type
inside a verification request. See the API reference for the complete request schema.

## Submission states

| State             | Meaning                                                                                                                |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `DRAFT`           | Yara stored the submission but has not yet confirmed provider acceptance. Poll the submission; do not submit it again. |
| `PENDING`         | Verification is still being processed.                                                                                 |
| `VERIFIED`        | This tier is complete.                                                                                                 |
| `REJECTED`        | Review `rejection_reasons`, correct the information, and create a new submission.                                      |
| `REQUIRES_REVIEW` | Processing needs additional review or information.                                                                     |

Use these endpoints to inspect the latest state:

* `GET /v1/customers/{customer_id}` for the customer's normalized status and capabilities.
* `GET /v1/customers/{customer_id}/verification-submissions` for submission history.
* `GET /v1/customers/{customer_id}/verification-submissions/{submission_id}` for one attempt.

The read endpoints never return BVNs, government identification numbers, document contents, image
data, or the original verification request.

<Card title="Verification webhooks" icon="webhook" href="/virtual-accounts/webhooks">
  React to submitted, approved, and rejected verification states.
</Card>