Skip to main content

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.

​
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

POST https://integrations.clopos.com/open-api/v2/customers
This endpoint requires authentication. Include your JWT in the x-token header. See Authentication for how to obtain a token and 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

​
name
string
required
Customer’s full name. This field is required.
​
email
string
Customer’s email address.
​
phone
string
Customer’s primary phone number. Must be unique across all customers.
​
code
string
Customer code/identifier. Must be unique across all customers.
​
cid
string
Customer UUID identifier. Must be unique across all customers. If not provided, the system will generate one automatically.
​
description
string
Additional notes or description about the customer.
​
group_id
integer
ID of the customer group to assign this customer to.
​
gender
integer
Customer’s gender. Use 1 for male, 2 for female, or null for unspecified.
​
date_of_birth
string
Customer’s date of birth in YYYY-MM-DD format.

​
Request Examples

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"
}'

​
Response

​
200 OK — Customer created successfully

{
  "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

{
    "success": false,
    "message": "Validation failed",
    "error": "The name field is required."
}

​
409 Conflict — Duplicate unique field

{
    "success": false,
    "message": "Customer with this phone number already exists",
    "error": "duplicate_phone"
}

​
Field Reference

​
Required Fields

FieldTypeDescription
namestringCustomer’s full name.

​
Optional Fields

FieldTypeDescription
emailstringCustomer’s email address.
phonestringPrimary phone number. Must be unique.
codestringCustomer code/identifier. Must be unique.
cidstringCustomer UUID. Must be unique. Auto-generated if not provided.
descriptionstringAdditional notes about the customer.
group_idintegerID of the customer group.
genderintegerGender: 1 = male, 2 = female, null = unspecified.
date_of_birthstringDate of birth in YYYY-MM-DD format.

​
Response Fields

FieldTypeDescription
idintegerUnique customer identifier (auto-assigned).
venue_idintegerVenue the customer was created in.
cidstringUUID identifier for the customer.
statusbooleanAccount status (defaults to true).
can_use_loyalty_systembooleanLoyalty enrollment status (defaults to false).
is_verifiedbooleanVerification status (defaults to false).
created_atstringCreation timestamp (ISO 8601).
updated_atstringLast 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.