> 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/bulk-create-customers.md).

# Bulk Create Customers

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

Bulk create customers (up to 100 at a time).

#### Parameters

* None

#### Request Body

The request body is a JSON object containing an array of customer objects to be created.

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

| Name          | Type             | Description                             |
| ------------- | ---------------- | --------------------------------------- |
| **customers** | Array of Objects | An array of up to 100 customer objects. |

**Customer Object Fields:**

| Field                | Type      | Description                                            | Example              |
| -------------------- | --------- | ------------------------------------------------------ | -------------------- |
| **name**             | `string`  | The customer's full name.                              | `"Jane Doe"`         |
| **email**            | `string`  | The customer's email address.                          | `"user@example.com"` |
| **whatsapp\_number** | `string`  | The customer's WhatsApp contact number.                | `"2348000000000"`    |
| **source**           | `string`  | The origin of the customer data (e.g., lead source).   | `"website_signup"`   |
| **ip**               | `string`  | The customer's IP address.                             | `"192.168.1.1"`      |
| **city**             | `string`  | The city where the customer is located.                | `"Lagos"`            |
| **country**          | `string`  | The country where the customer is located.             | `"Nigeria"`          |
| **location**         | `string`  | A general location description.                        | `"Office Block A"`   |
| **latitude**         | `string`  | The geographical latitude of the customer's location.  | `"6.5244"`           |
| **longitude**        | `string`  | The geographical longitude of the customer's location. | `"3.3792"`           |
| **is\_active**       | `boolean` | Indicates if the customer account is currently active. | `true`               |
| **company\_id**      | `string`  | The ID of the company the customer is associated with. | `"CMP-12345"`        |

**Example Request Body:**

```json
{
  "customers": [
    {
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "whatsapp_number": "2348000000000",
      "source": "website_signup",
      "ip": "192.168.1.1",
      "city": "Lagos",
      "country": "Nigeria",
      "location": "Lekki Phase 1",
      "latitude": "6.45407",
      "longitude": "3.38467",
      "is_active": true,
      "company_id": "CMP-12345"
    },
    {
      "name": "John Smith",
      "email": "john.smith@example.com",
      "whatsapp_number": "2348011111111",
      "source": "referral",
      "ip": "10.0.0.5",
      "city": "Abuja",
      "country": "Nigeria",
      "location": "Wuse 2",
      "latitude": "9.05786",
      "longitude": "7.49508",
      "is_active": true,
      "company_id": "CMP-67890"
    }
  ]
}
```

### Responses

#### 201 Successful Response (Created)

Returns the count of customers created and the list of created customer objects, including generated IDs and timestamps.

Content Type: `application/json`

| **Field** | **Type**         | **Description**                                     |
| --------- | ---------------- | --------------------------------------------------- |
| created   | `integer`        | The total number of customers successfully created. |
| customers | Array of Objects | A list of the newly created customer objects.       |

Created Customer Object Fields:

In addition to the request fields, the response customer objects include:

| **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). |

Example Response Body (201):

JSON

```json
{
  "created": 2,
  "customers": [
    {
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "whatsapp_number": "2348000000000",
      "source": "website_signup",
      "ip": "192.168.1.1",
      "city": "Lagos",
      "country": "Nigeria",
      "location": "Lekki Phase 1",
      "latitude": "6.45407",
      "longitude": "3.38467",
      "is_active": true,
      "id": 101,
      "customer_id": "CUST-A1B2C3",
      "time_created": "2025-11-27T09:36:31.355Z",
      "time_updated": "2025-11-27T09:36:31.355Z",
      "organization_id": 42,
      "company_id": 5
    },
    {
      "name": "John Smith",
      "email": "john.smith@example.com",
      "whatsapp_number": "2348011111111",
      "source": "referral",
      "ip": "10.0.0.5",
      "city": "Abuja",
      "country": "Nigeria",
      "location": "Wuse 2",
      "latitude": "9.05786",
      "longitude": "7.49508",
      "is_active": true,
      "id": 102,
      "customer_id": "CUST-D4E5F6",
      "time_created": "2025-11-27T09:36:32.100Z",
      "time_updated": "2025-11-27T09:36:32.100Z",
      "organization_id": 42,
      "company_id": 10
    }
  ]
}
```

#### 422 Validation Error

Returned if the request body is malformed or contains invalid data (e.g., missing required fields, invalid data types).

Content Type: `application/json`

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

Error Detail Object Fields:

| **Field** | **Type**                      | **Description**                                                                        |
| --------- | ----------------------------- | -------------------------------------------------------------------------------------- |
| loc       | Array of `string` / `integer` | Location of the error in the request body (e.g., `["body", "customers", 0, "email"]`). |
| msg       | `string`                      | A description of the validation error.                                                 |
| type      | `string`                      | The type of validation error (e.g., `value_error.missing`).                            |

Example Response Body (422):

JSON

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "customers",
        0,
        "name"
      ],
      "msg": "Field required",
      "type": "value_error.missing"
    }
  ]
}
```