Customers

curl -X POST 'https://api.yativo.com/api/v1/customer' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+5511999999999",
    "customer_country": "BRA",
    "customer_type": "individual"
  }'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+5511999999999",
    "customer_country": "BRA",
    "customer_status": "active",
    "created_at": "2026-03-26T10:00:00.000000Z"
  }
}

curl -X POST 'https://api.yativo.com/api/v1/customer' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+5511999999999",
    "customer_country": "BRA",
    "customer_type": "individual"
  }'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+5511999999999",
    "customer_country": "BRA",
    "customer_status": "active",
    "created_at": "2026-03-26T10:00:00.000000Z"
  }
}

Customers are end-users of your platform. Once created, customers can be assigned virtual accounts, attached to payins/payouts, and verified through KYC/KYB.

Type Definitions

interface Customer {
  customer_id: string;
  customer_name: string;
  customer_email: string;
  customer_phone: string;
  customer_country: string;       // ISO 3166-1 alpha-3 (e.g. "USA", "BRA")
  customer_status: "active" | "inactive";
  customer_kyc_status: "not_started" | "pending" | "approved" | "rejected" | null;
  customer_kyc_reject_reason: string | null;
  created_at: string;
  kyc_verified_date?: string;
}

interface CreateCustomerRequest {
  customer_name: string;
  customer_email: string;
  customer_phone: string;          // E.164 format (e.g. "+5511999999999")
  customer_country: string;        // ISO 3166-1 alpha-3
  customer_type?: "individual" | "business";  // defaults to "individual"
}

Create customer

POST /customer

string

required

Customer’s full name.

string

required

Customer’s email address.

string

required

Customer’s phone number in E.164 format (e.g. "+5511999999999").

string

required

Customer’s country — ISO 3166-1 alpha-3 code (e.g. "BRA", "USA", "MEX").

string

"individual" (default) or "business".

curl -X POST 'https://api.yativo.com/api/v1/customer' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+5511999999999",
    "customer_country": "BRA",
    "customer_type": "individual"
  }'

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+5511999999999",
    "customer_country": "BRA",
    "customer_status": "active",
    "created_at": "2026-03-26T10:00:00.000000Z"
  }
}

Get customer

Retrieve a single customer’s profile. By default only the core profile fields are returned. Use the include query parameter to embed related data in the same response.

GET /customer/{customer_id}

string

required

The customer ID (UUID).

string

Comma-separated list of relations to embed. Accepted values: deposits, payouts, virtualaccounts, virtual_cards, crypto_wallets. Pass all to include every relation at once.Examples

?include=all
?include=deposits,payouts
?include=virtualaccounts,virtual_cards

curl -X GET 'https://api.yativo.com/api/v1/customer/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx?include=all' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

curl -X GET 'https://api.yativo.com/api/v1/customer/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx?include=deposits,virtualaccounts' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

curl -X GET 'https://api.yativo.com/api/v1/customer/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Customer retrieved successfully",
  "data": {
    "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+5511999999999",
    "customer_country": "BRA",
    "customer_status": "active",
    "customer_kyc_status": "approved",
    "customer_kyc_reject_reason": null,
    "created_at": "2026-03-26T10:00:00.000000Z",
    "kyc_verified_date": "2026-03-26T12:00:00.000000Z",
    "customer_deposit": [
      {
        "transaction_id": "txn_xxxxxx",
        "transaction_amount": "500.00",
        "transaction_currency": "BRL",
        "transaction_status": "Complete",
        "transaction_purpose": "Top-up",
        "created_at": "2026-03-27T08:00:00.000000Z"
      }
    ],
    "customer_payouts": [
      {
        "transaction_id": "txn_yyyyyy",
        "transaction_amount": "200.00",
        "transaction_currency": "BRL",
        "transaction_payout_details": { "status": "Complete" },
        "created_at": "2026-03-28T09:00:00.000000Z"
      }
    ],
    "customer_virtualaccounts": [
      {
        "account_id": "va_xxxxxx",
        "currency": "BRL",
        "account_number": "BRLPIX0000000000000000000000000000000000",
        "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx"
      }
    ],
    "customer_virtual_cards": [],
    "customer_crypto_wallets": []
  }
}

{
  "status": "success",
  "status_code": 200,
  "message": "Customer retrieved successfully",
  "data": {
    "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+5511999999999",
    "customer_country": "BRA",
    "customer_status": "active",
    "customer_kyc_status": "approved",
    "customer_kyc_reject_reason": null,
    "created_at": "2026-03-26T10:00:00.000000Z",
    "kyc_verified_date": "2026-03-26T12:00:00.000000Z"
  }
}

The include parameter is additive — fields not included in the request are simply omitted from the response rather than returning empty arrays.

List all customers

GET /customer

Supports filtering by kyc_status, country, email, and pagination via page / per_page.

curl -X GET 'https://api.yativo.com/api/v1/customer?page=1&per_page=15' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Records retrieved successfully",
  "data": [
    {
      "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
      "customer_name": "Jane Doe",
      "customer_email": "jane@example.com",
      "customer_phone": "+5511999999999",
      "customer_country": "BRA",
      "customer_status": "active",
      "customer_kyc_status": "approved",
      "created_at": "2026-03-26T10:00:00.000000Z"
    }
  ],
  "pagination": {
    "total": 142,
    "per_page": 15,
    "current_page": 1,
    "last_page": 10
  }
}

Update customer

Update mutable fields on a customer record. Only include the fields you want to change.

PUT /customer/{customer_id}

curl -X PUT 'https://api.yativo.com/api/v1/customer/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: update-customer-001' \
  -d '{
    "customer_phone": "+5511988887777"
  }'

{
  "status": "success",
  "status_code": 200,
  "message": "Customer updated successfully",
  "data": {
    "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
    "customer_name": "Jane Doe",
    "customer_phone": "+5511988887777",
    "updated_at": "2026-04-02T14:00:00.000000Z"
  }
}

Delete customer

DELETE /customer/{customer_id}

curl -X DELETE 'https://api.yativo.com/api/v1/customer/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'X-Api-Secret: YOUR_API_SECRET'

{
  "status": "success",
  "status_code": 200,
  "message": "Customer deleted successfully"
}

Check verification

A customer’s KYC or KYB result is only available through their endorsements: the endorsement list on GET /customer/{customer_id}, and the endorsement.updated webhook. Each endorsement covers one service and has its own status. A service is available when its endorsement is approved. customer_kyc_status and is_va_approved don’t tell you which services a customer can use. See Track verification with endorsements.

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

SDKs

Regional Guides

Create customer

Get customer

List all customers

Update customer

Delete customer

Check verification

​Create customer

​Get customer

​List all customers

​Update customer

​Delete customer

​Check verification

Create customer

Get customer

List all customers

Update customer

Delete customer

Check verification