> For the complete documentation index, see [llms.txt](https://docs.cuoral.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuoral.com/api-reference/customers/contact/create-customer.md).

# Create Customer

**POST** `/external/v1/external/v1/customers`

### Request

#### Parameters

* None

#### Request Body

The request body is a JSON object defining the new customer's details.

**Content Type:** `application/json`

| Field                | Type      | Description                                                         | Example              | Required |
| -------------------- | --------- | ------------------------------------------------------------------- | -------------------- | -------- |
| **name**             | `string`  | The customer's full name.                                           | `"Alice Johnson"`    | **Yes**  |
| **email**            | `string`  | The customer's email address.                                       | `"user@example.com"` | **Yes**  |
| **whatsapp\_number** | `string`  | The customer's WhatsApp contact number.                             | `"2348000000000"`    | No       |
| **source**           | `string`  | Customer acquisition source (e.g., `'web'`, `'api'`, `'whatsapp'`). | `"web"`              | **Yes**  |
| **ip**               | `string`  | The customer's IP address.                                          | `"192.168.1.1"`      | No       |
| **city**             | `string`  | The city where the customer is located.                             | `"Accra"`            | No       |
| **country**          | `string`  | The country where the customer is located.                          | `"Ghana"`            | No       |
| **location**         | `string`  | A general location description.                                     | `"Spintex Road"`     | No       |
| **latitude**         | `string`  | Geographical latitude.                                              | `"5.6037"`           | No       |
| **longitude**        | `string`  | Geographical longitude.                                             | `"0.1870"`           | No       |
| **is\_active**       | `boolean` | Indicates if the customer account is active.                        | `true`               | No       |
| **company\_id**      | `string`  | The ID of the company the customer is associated with.              | `"CMP-A9B8"`         | No       |

**Example Request Body:**

```json
{
  "name": "Alice Johnson",
  "email": "alice.johnson@example.com",
  "whatsapp_number": "2348000000000",
  "source": "api",
  "ip": "10.0.0.2",
  "city": "Accra",
  "country": "Ghana",
  "is_active": true,
  "company_id": "CMP-A9B8"
}
```

***

### Responses

#### 201 Successful Response (Created)

Returns the newly created customer object, including generated IDs and timestamps.

Content Type: `application/json`

| **Field**          | **Type**            | **Description**                                                 |
| ------------------ | ------------------- | --------------------------------------------------------------- |
| id                 | `integer`           | The internal database ID of the customer.                       |
| customer\_id       | `string`            | The unique external ID assigned to the customer.                |
| time\_created      | `string` (datetime) | The timestamp when the customer record was created.             |
| time\_updated      | `string` (datetime) | The timestamp when the customer record was last updated.        |
| organization\_id   | `integer`           | The organization ID the customer belongs to.                    |
| company\_id        | `integer`           | The company ID the customer is associated with (as an integer). |
| *... other fields* | *...*               | *All fields from the request body are also returned.*           |

Example Response Body (201):

JSON

```json
{
  "name": "Alice Johnson",
  "email": "alice.johnson@example.com",
  "whatsapp_number": "2348000000000",
  "source": "api",
  "ip": "10.0.0.2",
  "city": "Accra",
  "country": "Ghana",
  "location": "string",
  "latitude": "string",
  "longitude": "string",
  "is_active": true,
  "id": 201,
  "customer_id": "CUST-F7E6D5",
  "time_created": "2025-11-27T09:40:04.612Z",
  "time_updated": "2025-11-27T09:40:04.612Z",
  "organization_id": 42,
  "company_id": 15
}
```

#### 422 Validation Error

Returned if the request body is malformed or contains invalid data.

Content Type: `application/json`

| **Field** | **Type**         | **Description**                     |
| --------- | ---------------- | ----------------------------------- |
| detail    | Array of Objects | A list of validation error objects. |

Example Response Body (422):

JSON

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "email"
      ],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}
```