# Customers (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/customers/
> Staging base URL: https://core-staging.coinbax.com/api/v1

Global customer management (admin only)

## List all customers

`GET /customers`

- Auth: Bearer token
- Operation ID: `listCustomers`

Retrieve a paginated list of all customers across workspaces.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Page number (1-indexed) |
| `limit` | query | integer | no | Items per page |
| `workspaceId` | query | string (uuid) | no | Filter by workspace ID |
| `status` | query | enum ("active", "inactive", "suspended", "pending") | no | Filter by customer status |
| `search` | query | string | no | Search by name or email |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/customers \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Customers list retrieved successfully

```json
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "status": "active",
      "createdAt": "2026-01-20T08:30:00.000Z",
      "updatedAt": "2026-02-15T16:45:00.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 500,
      "totalPages": 25
    }
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Create a new customer

`POST /customers`

- Auth: Bearer token
- Operation ID: `createCustomer`

Create a new customer in a specified workspace.

**Permissions:** ADMIN or SUPER_ADMIN only

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | string (uuid) | yes | Workspace ID to create customer in |
| `email` | string (email) | yes | Customer's email address |
| `firstName` | string | yes | Customer's first name |
| `lastName` | string | yes | Customer's last name |
| `phoneNumber` | string | no | Customer's phone number |
| `dateOfBirth` | string (date) | no | Customer's date of birth |
| `address` | string | no | Customer's street address |
| `city` | string | no | Customer's city |
| `state` | string | no | Customer's state/province |
| `postalCode` | string | no | Customer's postal code |
| `country` | string | no | Customer's country |
| `status` | enum ("active", "inactive", "suspended", "pending") | no | Initial customer status |
| `metadata` | object | no | Custom metadata |

```json
{
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1-555-123-4567",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94102",
  "country": "USA"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/customers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1-555-123-4567",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "postalCode": "94102",
  "country": "USA"
}'
```

### Responses

**201** Customer created successfully

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active",
    "createdAt": "2026-02-24T12:00:00.000Z",
    "updatedAt": "2026-02-24T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**500** Internal server error

---

## Get customer by ID

`GET /customers/{id}`

- Auth: Bearer token
- Operation ID: `getCustomer`

Retrieve a customer by their unique identifier.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Customer UUID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/customers/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Customer found

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+1-555-123-4567",
    "status": "active",
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "emailVerified": true,
    "createdAt": "2026-01-20T08:30:00.000Z",
    "updatedAt": "2026-02-15T16:45:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Update customer

`PUT /customers/{id}`

- Auth: Bearer token
- Operation ID: `updateCustomer`

Update customer details.

**Permissions:** ADMIN or SUPER_ADMIN only

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | no | Customer's email address |
| `firstName` | string | no | Customer's first name |
| `lastName` | string | no | Customer's last name |
| `phoneNumber` | string | no | Customer's phone number |
| `dateOfBirth` | string (date) | no | Customer's date of birth |
| `address` | string | no | Customer's street address |
| `city` | string | no | Customer's city |
| `state` | string | no | Customer's state/province |
| `postalCode` | string | no | Customer's postal code |
| `country` | string | no | Customer's country |
| `status` | enum ("active", "inactive", "suspended", "pending") | no | Customer status |
| `metadata` | object | no | Custom metadata |

```json
{
  "firstName": "Jonathan",
  "lastName": "Doe",
  "phoneNumber": "+1-555-987-6543",
  "status": "active"
}
```

### Example request

```bash
curl -X PUT https://core-staging.coinbax.com/api/v1/customers/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Jonathan",
  "lastName": "Doe",
  "phoneNumber": "+1-555-987-6543",
  "status": "active"
}'
```

### Responses

**200** Customer updated successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "cust_12345",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+1-555-123-4567",
    "dateOfBirth": "1990-01-15",
    "address": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "USA",
    "status": "active",
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "emailVerified": true,
    "metadata": {
      "tier": "premium"
    },
    "createdAt": "2026-01-20T08:30:00.000Z",
    "updatedAt": "2026-02-15T16:45:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Delete customer

`DELETE /customers/{id}`

- Auth: Bearer token
- Operation ID: `deleteCustomer`

Permanently delete a customer.

**Permissions:** ADMIN or SUPER_ADMIN only

**Warning:** This action is irreversible.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes |  |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/customers/<id> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Customer deleted successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "message": "Customer deleted successfully"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**403** Forbidden - insufficient permissions

**404** Resource not found

**500** Internal server error

---

## Get customer Circle wallet

`GET /customers/{id}/circle-wallet`

- Auth: Bearer token
- Operation ID: `getCustomerCircleWallet`

Get the Circle wallet information for a customer.
Returns the wallet address and ID if the customer has a Circle wallet.

**Permissions:** Requires workspace access to the customer's workspace

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Customer UUID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/customers/<id>/circle-wallet \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Circle wallet information

```json
{
  "hasWallet": true,
  "walletId": "string",
  "walletAddress": "string",
  "walletLinkedAt": "2026-01-15T12:00:00.000Z"
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Provision Circle wallet for customer

`POST /customers/{id}/circle-wallet`

- Auth: Bearer token
- Operation ID: `createCustomerCircleWallet`

Provision a Circle wallet for a customer.
Creates a new wallet in the workspace's Circle wallet set.

**Prerequisites:**
- Workspace must have a Circle wallet provider configured
- Customer must not already have a Circle wallet

**Permissions:** Requires workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Customer UUID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `network` | enum ("BASE_SEPOLIA", "BASE", "ETH_SEPOLIA", "ETH") | no | Blockchain network for the wallet |

```json
{
  "network": "BASE_SEPOLIA"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/customers/<id>/circle-wallet \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "network": "BASE_SEPOLIA"
}'
```

### Responses

**201** Circle wallet created successfully

```json
{
  "success": true,
  "walletId": "string",
  "walletAddress": "string",
  "blockchain": "string",
  "createdAt": "2026-01-15T12:00:00.000Z"
}
```

**400** Bad request (customer already has wallet, workspace not configured)

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get customer Circle wallet balance

`GET /customers/{id}/circle-wallet/balance`

- Auth: Bearer token
- Operation ID: `getCustomerCircleWalletBalance`

Get the token balance for a customer's Circle wallet.

**Permissions:** Requires workspace access to the customer's workspace

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Customer UUID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/customers/<id>/circle-wallet/balance \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Wallet balance retrieved

```json
{
  "walletAddress": "string",
  "balances": [
    {
      "token": "USDC",
      "balance": "100.50",
      "network": "BASE_SEPOLIA"
    }
  ]
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get customer transactions

`GET /customers/{id}/transactions`

- Auth: Bearer token
- Operation ID: `getCustomerTransactions`

Retrieve transactions for a specific customer.

**Permissions:** Requires workspace access to the customer's workspace

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Customer UUID |
| `page` | query | integer | no |  |
| `limit` | query | integer | no |  |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/customers/<id>/transactions \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Customer transactions retrieved

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "transactions": [
      {
        "id": "tx_550e8400-e29b-41d4-a716-446655440000",
        "status": "COMPLETED",
        "amount": "100.00",
        "currency": "USDC",
        "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
        "toAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
        "blockchainNetwork": "base",
        "chainId": 8453,
        "txHash": "0xabcd...ef12",
        "orchestrationType": "raw",
        "metadata": {
          "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
          "customerId": "cust_12345"
        },
        "createdAt": "2026-02-24T10:00:00.000Z",
        "updatedAt": "2026-02-24T10:05:00.000Z",
        "_platformName": "Main Platform",
        "_platformId": "platform_xyz"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error