Customers

Customer APIs are in preview as part of USD Virtual Accounts.

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.

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

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

Reusing an idempotency key with a different body returns 409. Use a new key for each intended customer creation.

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

Verify a customer

Submit the verification required before creating a USD virtual account.

USD Virtual Accounts

Customers and verification

Customer verification

Virtual accounts

Virtual-account deposits

Customers

How ownership works

Create a customer

Read customers

Next step

Verify a customer

​How ownership works

​Create a customer

​Read customers

​Next step

Verify a customer

How ownership works

Create a customer

Read customers

Next step