---
title: "Create a new customer"
method: POST
path: "/api/v1/customer"
tags: ["Customers"]
---

# Create a new customer

`POST /api/v1/customer`

## Request

- Base URL: `https://sandbox.api.afriex.com`
- URL: `https://sandbox.api.afriex.com/api/v1/customer`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/afriex/apis/afriex-business-api/docs/api/v1/customer/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new customer for a business. `phone` is validated against `countryCode` and stored in E.164 format. If you post the email of a customer that was previously deleted, that customer is reactivated (its stored `countryCode` is kept) and the call still returns `201`.

## Request body

- object
  - `fullName` string, required: The full name of the customer. Must not be empty.
  - `email` string, email, required: The email address of the customer.
  - `phone` string, required: The phone number of the customer. It must be valid for `countryCode`; it is normalised to E.164 on save.
  - `countryCode` string, required: The ISO 3166-1 alpha-2 country code of the customer (e.g., 'NG', 'US'). Must be a supported country, otherwise the request fails with `400 INVALID_BUSINESS_CUSTOMER_REQUEST`.
  - `meta` object: Optional meta data you can attach to the customer.

## Response `201`

Customer created successfully. Returns the newly created customer object.

- object
  - `data` Customer
    - `customerId` string: The unique identifier for the customer.
    - `reference` string: A shortened reference for the customer. Returned on every customer response (create, list, by-ID, update, KYC and verify) and used as the pool-account reference when submitting a payment proof. Falls back to the customer id when no shortened reference has been assigned.
    - `name` string: The full name of the customer.
    - `email` string, email: The email of the customer.
    - `phone` string: The phone number of the customer in E.164 format.
    - `countryCode` string: The country code of the customer in ISO 3166-1 alpha-2 format.
    - `meta` object: Optional meta data you can attach to the customer. On the responses of `PATCH /api/v1/customer/{customerId}/kyc` and `POST /api/v1/customer/{customerId}/verify` this holds `meta.kyc.data`, the customer's stored KYC documents, in place of your meta data.
    - `createdAt` string: The date and time the customer was created.
    - `updatedAt` string: The date and time the customer was last updated.

## Other responses

- `400`: Invalid request: a required field is missing, or the name, email, phone (checked against `countryCode`) or country code is invalid.
- `401`: Unauthorized.
- `409`: A customer with this email or phone already exists for the business. `details.data.customerId` carries the existing customer's id so you can adopt it without a follow-up lookup.
- `500`: Server error.
- `503`: Temporarily unavailable: an upstream service failed or timed out, or the API is momentarily offline. Retry with backoff and honour the Retry-After header when present.

---

[API](https://skmtc.dev/afriex/apis/afriex-business-api.md) - [All operations](https://skmtc.dev/afriex/apis/afriex-business-api/llms.txt) - [OpenAPI document](https://skmtc.dev/afriex/apis/afriex-business-api/revisions/d94198b6c256?raw)