> ## Documentation Index
> Fetch the complete documentation index at: https://developer.clopos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Customer
> Create a new customer with contact information and group assignment
## Purpose
Create a new customer in the Clopos system. This endpoint allows you to register customers with their contact information, assign them to customer groups, and set up their profile details.
## HTTP Request
```http theme={null}
POST https://integrations.clopos.com/open-api/v2/customers
```
This endpoint requires authentication. Include your JWT in the `x-token` header. See [Authentication](/authentication) for how to obtain a token and [Errors](/errors) for error responses.
The fields `code`, `phone`, and `cid` are unique. If you attempt to create a customer with duplicate values for any of these fields, the API will return an error.
## Request Body
Customer's full name. This field is required.
Customer's email address.
Customer's primary phone number. Must be unique across all customers.
Customer code/identifier. Must be unique across all customers.
Customer UUID identifier. Must be unique across all customers. If not provided, the system will generate one automatically.
Additional notes or description about the customer.
ID of the customer group to assign this customer to.
Customer's gender. Use `1` for male, `2` for female, or `null` for unspecified.
Customer's date of birth in `YYYY-MM-DD` format.
## Request Examples
```bash curl theme={null}
curl --location 'https://integrations.clopos.com/open-api/v2/customers' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-token: oauth_example_token' \
--header 'content-type: application/json' \
--data-raw '{
"name": "John Doe",
"email": "john.doe@example.com",
"code": "CUST001",
"cid": "0f9654bc-9520-43d7-8109-317d9820f54c",
"phone": "+15551234567",
"description": "Test Customer",
"group_id": 1,
"gender": 1,
"date_of_birth": "1990-05-15"
}'
```
```javascript javascript theme={null}
const customerData = {
name: "John Doe",
email: "john.doe@example.com",
code: "CUST001",
cid: "0f9654bc-9520-43d7-8109-317d9820f54c",
phone: "+15551234567",
description: "Test Customer",
group_id: 1,
gender: 1,
date_of_birth: "1990-05-15"
};
const response = await fetch('https://integrations.clopos.com/open-api/v2/customers', {
method: 'POST',
headers: {
'x-token': 'oauth_example_token',
'Content-Type': 'application/json'
},
body: JSON.stringify(customerData)
});
const customer = await response.json();
```
```python python theme={null}
import requests
url = "https://integrations.clopos.com/open-api/v2/customers"
headers = {
"x-token": "oauth_example_token",
"Content-Type": "application/json"
}
customer_data = {
"name": "John Doe",
"email": "john.doe@example.com",
"code": "CUST001",
"cid": "0f9654bc-9520-43d7-8109-317d9820f54c",
"phone": "+15551234567",
"description": "Test Customer",
"group_id": 1,
"gender": 1,
"date_of_birth": "1990-05-15"
}
response = requests.post(url, headers=headers, json=customer_data)
customer = response.json()
```
## Response
### 200 OK — Customer created successfully
```json theme={null}
{
"success": true,
"data": {
"id": 14,
"venue_id": 1,
"cid": "0f9654bc-9520-43d7-8109-317d9820f54c",
"group_id": 1,
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+15551234567",
"phones": [],
"address": null,
"address_data": [],
"description": "Test Customer",
"discount": 0,
"spent": 0,
"total_discount": 0,
"total_bonus": 0,
"receipt_count": 0,
"gender": 1,
"date_of_birth": "1990-05-15",
"code": "CUST001",
"source": null,
"reference_id": null,
"status": true,
"can_use_loyalty_system": false,
"is_verified": false,
"created_at": "2025-11-14T08:31:17.000000Z",
"updated_at": "2025-11-14T08:31:17.000000Z"
}
}
```
### 400 Bad Request — Validation error
```json theme={null}
{
"success": false,
"message": "Validation failed",
"error": "The name field is required."
}
```
### 409 Conflict — Duplicate unique field
```json theme={null}
{
"success": false,
"message": "Customer with this phone number already exists",
"error": "duplicate_phone"
}
```
## Field Reference
### Required Fields
| Field | Type | Description |
| ------ | ------ | --------------------- |
| `name` | string | Customer's full name. |
### Optional Fields
| Field | Type | Description |
| --------------- | ------- | -------------------------------------------------------------- |
| `email` | string | Customer's email address. |
| `phone` | string | Primary phone number. Must be unique. |
| `code` | string | Customer code/identifier. Must be unique. |
| `cid` | string | Customer UUID. Must be unique. Auto-generated if not provided. |
| `description` | string | Additional notes about the customer. |
| `group_id` | integer | ID of the customer group. |
| `gender` | integer | Gender: `1` = male, `2` = female, `null` = unspecified. |
| `date_of_birth` | string | Date of birth in `YYYY-MM-DD` format. |
### Response Fields
| Field | Type | Description |
| ------------------------ | ------- | ------------------------------------------------ |
| `id` | integer | Unique customer identifier (auto-assigned). |
| `venue_id` | integer | Venue the customer was created in. |
| `cid` | string | UUID identifier for the customer. |
| `status` | boolean | Account status (defaults to `true`). |
| `can_use_loyalty_system` | boolean | Loyalty enrollment status (defaults to `false`). |
| `is_verified` | boolean | Verification status (defaults to `false`). |
| `created_at` | string | Creation timestamp (ISO 8601). |
| `updated_at` | string | Last update timestamp (ISO 8601). |
## Notes
* The `name` field is required and cannot be empty.
* The fields `code`, `phone`, and `cid` must be unique. Attempting to create a customer with duplicate values will result in a `409 Conflict` error.
* If `cid` is not provided, the system will automatically generate a UUID for the customer.
* The response includes the customer's group information if `group_id` was provided.
* The `can_use_loyalty_system` and `is_verified` fields are set to `false` by default for new customers.