Bulk Create Customers

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

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.	"[email protected]"
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:

{
  "customers": [
    {
      "name": "Jane Doe",
      "email": "[email protected]",
      "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": "[email protected]",
      "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

{
  "created": 2,
  "customers": [
    {
      "name": "Jane Doe",
      "email": "[email protected]",
      "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": "[email protected]",
      "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

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