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

# Customers

> Create and manage the people and businesses that receive customer-scoped Yara products.

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

A customer is a person or business that belongs to your merchant account. Create the customer once,
then use its Yara `id` when you request customer-scoped products such as a USD virtual account.

Customer records are general Yara resources. They live in this section because USD Virtual Accounts
is the first product that requires customer verification.

## How ownership works

| Party         | Responsibility                                                                                                                                           |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Your merchant | Authenticates with the API, owns the customer relationship, receives customer deposits in its merchant balance, and remains the principal for transfers. |
| Your customer | Completes the verification required for customer-scoped products and owns their virtual-account relationship.                                            |

A customer does not receive an API key or a separate Yara ledger balance. You manage any customer
balance shown in your product. Yara keeps the customer ID as attribution on customer-scoped activity.

## Create a customer

Send a unique `external_reference` that links the Yara customer to the customer in your system.
Individual customers require `first_name` and `last_name`.

```bash theme={null}
curl https://api.yara.cash/v1/customers \
  --request POST \
  --header "x-yara-api-key: $YARA_API_KEY" \
  --header "X-Idempotency-Key: $(uuidgen)" \
  --header "Content-Type: application/json" \
  --data '{
    "external_reference": "customer_001",
    "type": "INDIVIDUAL",
    "email": "customer@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace"
  }'
```

```json theme={null}
{
  "data": {
    "id": "908a76cf-4ff1-4e0e-bda4-d3a939970abc",
    "external_reference": "customer_001",
    "type": "INDIVIDUAL",
    "status": "CREATED",
    "email": "customer@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "tier_1_complete": false,
    "tier_2_complete": false,
    "capabilities": {},
    "rejection_reasons": [],
    "created_at": "2026-08-03T12:00:00Z",
    "updated_at": "2026-08-03T12:00:00Z"
  }
}
```

Store the returned customer `id`. Resource IDs are always scoped to your authenticated merchant
account. A request for a customer owned by another merchant returns `404`.

Yara returns `201 Created` when provisioning completes immediately. If the provider result is
temporarily uncertain, Yara returns the same durable customer in `PROVISIONING` with
`202 Accepted`. Keep its `id` and poll `GET /v1/customers/{customer_id}`; do not create another
customer. A retry with the same idempotency key returns the original status and body.

Customer email is unique across Yara's customer namespace, while `external_reference` is unique
within your merchant account.

<Warning>
  Reusing an idempotency key with a different body returns `409`. Use a new key for each intended
  customer creation.
</Warning>

## Read customers

Use `GET /v1/customers` to list customers. You can filter by `external_reference`, `type`, `status`,
or creation time. Use `GET /v1/customers/{customer_id}` to retrieve one customer.

Customer responses include only authorized customer fields and normalized verification state.
Yara protects identity and verification data at rest.

## Next step

<Card title="Verify a customer" icon="badge-check" href="/virtual-accounts/verification">
  Submit the verification required before creating a USD virtual account.
</Card>