> ## 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.

# Onboard a customer

> Tell us who is making payments before you create a quote.

Every quote and payment belongs to a customer. Add each customer once, save their ID, and reuse it for all their payments.

## Two kinds of customer

| Type | Use it for | Details you send |
| - | - | - |
| `retail` | A person | `first_name`, `last_name`, `email`, `phone` |
| `business` | A company | `business_name`, `business_email`, `business_phone`, `registered_address`, `registered_country` |

All fields are required.

## Add a person

```shellscript 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"
    }
  }'
```

## Add a company

```bash 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": "business",
    "details": {
      "business_name": "Kola Traders Ltd",
      "business_email": "finance@kolatraders.com",
      "business_phone": "+233201234567",
      "registered_address": "12 Oxford Street, Accra",
      "registered_country": "GH"
    }
  }'
```

## What you get back

`201 Created`, with the customer:

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

Save the `id`. You'll use it in every quote and payment for this customer.

> [!NOTE]
>
> Unlike other endpoints, this one returns the customer directly, not inside a `customer` field.

## What can go wrong

| Status | Code | Why | What to do |
| - | - | - | - |
| `422` | `validation_failed` | A field is missing or wrong, for example an invalid email. | Read `errors` to see which field, fix it, and try again. |
| `401` | `authentication_failed` | Problem with your API key. | See [API keys](https://docs.bridge.linkio.world/control-app/api-keys.md#key-errors). |
| `403` | `forbidden` | Your IP isn't allowlisted, or your key can't manage customers. | See [IP allowlist](https://docs.bridge.linkio.world/control-app/ip-allowlist.md). |

Example:

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

## Banned customers

If a customer is banned, you can't create quotes or payments for them. You'll get a `409` error with code `customer_banned`. Contact support if you think this is a mistake.

## Next

[Get a quote](https://docs.bridge.linkio.world/flows/quotes.md) for this customer.


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