> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mitu.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mitu.ai/_mcp/server.

# Customer API

Use the Customer API when your backend should explicitly provision customers before they connect to Mitu. Each customer record can be associated with your own customer identifier and later used with capabilities such as customer authentication and Agent Wallets.

Creating a customer does not create a wallet or fund an account. It establishes the identity record that other resources can belong to.

## Create a customer

Create a customer with a stable reference from your own system.

**`Create a customer`**

```bash title="Create a customer"
curl --request POST \
  --url https://api.mitu.ai/v1/customers \
  --header "x-api-key: $MITU_API_KEY" \
  --header "Idempotency-Key: customer-your_user_8841" \
  --header "Content-Type: application/json" \
  --data '{
    "client_reference_id": "your_user_8841",
    "first_name": "Ada",
    "last_name": "Obi",
    "email": "ada@example.com",
    "phone": "+2348099887766"
  }'
```

### Parameters

| Parameter             | Type     | Required | Description                                                                                                      |
| --------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `client_reference_id` | `string` | Yes      | A stable identifier from your own system used to associate the Mitu customer with your existing customer record. |
| `first_name`          | `string` | No       | The customer's first name.                                                                                       |
| `last_name`           | `string` | No       | The customer's last name.                                                                                        |
| `email`               | `string` | No       | The customer's email address.                                                                                    |
| `phone`               | `string` | No       | The customer's phone number.                                                                                     |

A successful request returns the customer record together with the connection information created for that customer.

**`Response`**

```json title="Response"
{
  "id": "cus_ds9hazr8jd3l",
  "client_reference_id": "your_user_8841",
  "first_name": "Ada",
  "last_name": "Obi",
  "email": "ada@example.com",
  "phone": "+2348099887766",
  "key": "mcpk_3a6f9d2a6bbc816b11d524fe052b26b7e75fb7b5fa7a1a7d",
  "mcp_url": "https://mcp.yourdomain.com/mcp",
  "created_at": "2026-09-11T15:00:34.915Z"
}
```

### Response fields

| Field                 | Description                                   |
| --------------------- | --------------------------------------------- |
| `id`                  | The Mitu identifier for the customer.         |
| `client_reference_id` | The identifier supplied by your own system.   |
| `first_name`          | The customer's first name when provided.      |
| `last_name`           | The customer's last name when provided.       |
| `email`               | The customer's email address when provided.   |
| `phone`               | The customer's phone number when provided.    |
| `key`                 | The customer key created for this customer.   |
| `mcp_url`             | The MCP endpoint the customer can connect to. |
| `created_at`          | When the customer record was created.         |

## Use your own customer reference

`client_reference_id` connects the Mitu customer to the corresponding customer in your own application. Use an identifier that is stable and unique within your system rather than an email address or other attribute that may change over time.

For example, if your database identifies a user as `your_user_8841`, use that value as the customer reference. Your application can then use the same reference when reconciling supported events and customer-aware requests without making the Mitu customer ID your primary identity.

```json
{
  "client_reference_id": "your_user_8841"
}
```

The Mitu `cus_...` identifier is still useful when calling APIs that operate directly on the customer, such as issuing an Agent Wallet. The two identifiers serve different purposes. Your reference connects the record to your application, while the Mitu ID identifies the resource within Mitu.

## Customer key

The `key` returned when the customer is created is a customer key with the `mcpk_...` prefix. It can be used when that customer connects to an MCP-compatible AI client using customer-key authentication.

> **The key is returned once**
>
> The customer key appears only in the response to this request and cannot be retrieved later. Save it or pass it to the customer straight away. If it is lost, [rotate the key](/api-reference/customers/rotate-customer-key) to issue a new one.

Treat the returned key as a credential and provide it only to the customer it belongs to. Customer keys are separate from your merchant API key and should not be used by your backend as a replacement for `sk_...` credentials.

See [Customer keys](/platform/customers/customer-keys) for how customer-key authentication works.

## Idempotency

Use an `Idempotency-Key` when creating customers so a network retry does not accidentally create the same resource more than once.

```http
Idempotency-Key: customer-your_user_8841
```

Use a stable key for the same creation attempt rather than generating a new value every time you retry the request. If the API receives a repeated request with the same idempotency key, it can return the result associated with the original operation rather than processing another independent creation request.

Keep idempotency separate from `client_reference_id`. The idempotency key protects a specific API operation from accidental repetition, while `client_reference_id` connects the resulting customer to the record in your own system.

## Retrieve customers

List the customers created for your account:

```http
GET /v1/customers?limit=20
```

Retrieve a specific customer using its Mitu customer ID:

```http
GET /v1/customers/{id}
```

Use these endpoints when your backend needs the current customer record or the customer ID required by another API operation.

## Customer creation and wallets are separate

A newly created customer does not automatically have an Agent Wallet. If the customer should receive a wallet their AI agent can spend from, issue the wallet separately after the customer exists.

This separation lets your product use Mitu customer identity without requiring every customer to hold funds or use Agent Wallets.

See [Agent Wallets](/platform/agent-wallets/overview) for wallet issuance.

## Related

#### [Customers](/platform/customers/overview)

Understand how customer identity fits across the platform.

#### [Customer keys](/platform/customers/customer-keys)

Understand the `mcpk_...` credential returned for a customer.

#### [OAuth](/platform/customers/oauth)

Let customers connect through your existing identity provider.

#### [Agent Wallets](/platform/agent-wallets/overview)

Issue a wallet after the customer has been created.