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

# Add a customer

> Create a person or company that can make payments.

Requires the **Customers** scope (write). See [Onboard a customer](https://docs.bridge.linkio.world/flows/onboard-customer.md) for a walkthrough.

## Headers

**API-Version** `string` *required* (default: 2026-10-29-atlas)

Your account's API version.

## Body

**type** `string` *required*

`retail` for a person, `business` for a company.

**details** `object` *required*

**retail fields**

**first\_name** `string` *required*

First name.

**last\_name** `string` *required*

Last name.

**email** `string` *required*

Email address.

**phone** `string` *required*

Phone number, for example `+2348012345678`.

**business fields**

**business\_name** `string` *required*

Registered company name.

**business\_email** `string` *required*

Company email.

**business\_phone** `string` *required*

Company phone.

**registered\_address** `string` *required*

Registered address.

**registered\_country** `string` *required*

Country of registration, for example `GH`.

## Response

`201 Created`. The customer is returned at the top level.

**id** `string`

Customer ID, starting with `cus_`.

**type** `string`

`retail` or `business`.

**name** `string`

Full name or company name.

**email** `string`

Email address.

**phone** `string | null`

Phone number.

**address** `string | null`

Address.

**country** `string | null`

Country.

**metadata** `object`

Extra information.

## Errors

| Status | Code | Why |
| - | - | - |
| `422` | `validation_failed` | A field is missing or invalid. `errors` lists each one. |

```bash cURL theme={null}
curl -X POST https://sandbox.core.linkio.world/api/customers/onboard \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "retail",
    "details": {
      "first_name": "Ada",
      "last_name": "Obi",
      "email": "ada@example.com",
      "phone": "+2348012345678"
    }
  }'
```

```json 201 theme={null}
{
  "id": "cus_4hT9pL2mQx8VnR3tY7wZ1cB5dE",
  "type": "retail",
  "name": "Ada Obi",
  "email": "ada@example.com",
  "phone": "+2348012345678",
  "address": null,
  "country": null,
  "metadata": {}
}
```

```json 422 theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "Request validation failed",
    "request_id": "req_3VnR7tY1wZ4cB6dE8fK2mQ9xLp",
    "status": 422,
    "errors": [
      { "field": "details.last_name", "message": "last_name is required" }
    ]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.