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

# Customers

> Create and manage end-customer profiles

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

<Accordion title="Type Definitions">
  ```typescript theme={null}
  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"
  }
  ```
</Accordion>

***

## Create customer

```
POST /customer
```

<ParamField body="customer_name" type="string" required>
  Customer's full name.
</ParamField>

<ParamField body="customer_email" type="string" required>
  Customer's email address.
</ParamField>

<ParamField body="customer_phone" type="string" required>
  Customer's phone number in E.164 format (e.g. `"+5511999999999"`).
</ParamField>

<ParamField body="customer_country" type="string" required>
  Customer's country — ISO 3166-1 **alpha-3** code (e.g. `"BRA"`, `"USA"`, `"MEX"`).
</ParamField>

<ParamField body="customer_type" type="string">
  `"individual"` (default) or `"business"`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/customer' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

***

## 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}
```

<ParamField path="customer_id" type="string" required>
  The customer ID (UUID).
</ParamField>

<ParamField query="include" type="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`
</ParamField>

<RequestExample>
  ```bash All relations theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/customer/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx?include=all' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```

  ```bash Specific relations theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/customer/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx?include=deposits,virtualaccounts' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```

  ```bash Profile only (no include) theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/customer/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json Success (?include=all) theme={null}
  {
    "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": []
    }
  }
  ```

  ```json Profile only (no include param) theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

<Note>
  The `include` parameter is **additive** — fields not included in the request are simply omitted from the response rather than returning empty arrays.
</Note>

***

## List all customers

```
GET /customer
```

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

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/customer?page=1&per_page=15' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

***

## Update customer

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

```
PUT /customer/{customer_id}
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT 'https://api.yativo.com/api/v1/customer/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: update-customer-001' \
    -d '{
      "customer_phone": "+5511988887777"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

***

## Delete customer

```
DELETE /customer/{customer_id}
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE 'https://api.yativo.com/api/v1/customer/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "status_code": 200,
    "message": "Customer deleted successfully"
  }
  ```
</ResponseExample>

***

## Check KYC status

```
GET /customer/kyc/{customer_id}
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/customer/kyc/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "status_code": 200,
    "message": "Request successful",
    "data": {
      "first_name": "Jane",
      "last_name": "Doe",
      "status": "approved",
      "kyc_rejection_reasons": [],
      "kyc_requirements_due": [],
      "bio_data": {
        "customer_id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
        "customer_name": "Jane Doe",
        "customer_kyc_status": "approved",
        "kyc_verified_date": "2026-03-26T12:00:00.000000Z"
      },
      "kyc_link": "https://checkout.yativo.com/kyc/update-biodata/xxxxx-xxxxx-xxx-xxxx-xxxx",
      "is_va_approved": true
    }
  }
  ```
</ResponseExample>

<Note>
  Once `is_va_approved` is `true`, the customer can be issued virtual accounts. See the [KYC/KYB](/yativo-fiat/kyc) page for submitting identity verification.
</Note>