> For the complete documentation index, see [llms.txt](https://developers.coincircuit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.coincircuit.io/customers.md).

# Customers

Manage customer information

## List customers

> Returns all customers.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Customers","description":"Manage customer information"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"CustomersResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"List of customers","type":"array","items":{"$ref":"#/components/schemas/CustomerDto"}},"meta":{"description":"Pagination metadata for list responses","allOf":[{"$ref":"#/components/schemas/PaginationMetaDto"}]}},"required":["success","message","meta"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page (1-based)"},"size":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items available for this query"},"totalPages":{"type":"number","description":"Total number of pages for this query"}},"required":["page","size","total","totalPages"]}}},"paths":{"/api/v1/customers":{"get":{"description":"Returns all customers.","operationId":"CustomersController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"size","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":10,"type":"number"}},{"name":"search","required":false,"in":"query","description":"Search by customer name, email, or phone","schema":{"type":"string"}},{"name":"email","required":false,"in":"query","description":"Filter by exact email address","schema":{"type":"string"}},{"name":"phone","required":false,"in":"query","description":"Filter by exact phone number","schema":{"type":"string"}},{"name":"telegramId","required":false,"in":"query","description":"Filter by exact Telegram ID","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomersResponseDto"}}}}},"summary":"List customers","tags":["Customers"]}}}}
```

## Create customer

> Creates a new customer. If a customer with the same email, phone, or telegram ID already exists, it will be updated instead.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Customers","description":"Manage customer information"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"CreateCustomerRequestDto":{"type":"object","properties":{"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"}}},"CustomerResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Customer data","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]}},"required":["success","message"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]}}},"paths":{"/api/v1/customers":{"post":{"description":"Creates a new customer. If a customer with the same email, phone, or telegram ID already exists, it will be updated instead.","operationId":"CustomersController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerRequestDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponseDto"}}}},"400":{"description":"Invalid input data"}},"summary":"Create customer","tags":["Customers"]}}}}
```

## Retrieve customer

> Returns the customer for the given ID.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Customers","description":"Manage customer information"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"CustomerResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Customer data","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]}},"required":["success","message"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]}}},"paths":{"/api/v1/customers/{id}":{"get":{"description":"Returns the customer for the given ID.","operationId":"CustomersController_findOne","parameters":[{"name":"id","required":true,"in":"path","description":"Customer UUID","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponseDto"}}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{}}}}},"summary":"Retrieve customer","tags":["Customers"]}}}}
```

## Update customer

> Updates the customer.

```json
{"openapi":"3.0.0","info":{"title":"CoinCircuit API","version":"1.0"},"tags":[{"name":"Customers","description":"Manage customer information"}],"servers":[{"url":"https://api.coincircuit.io","description":"Production Server"},{"url":"https://sandbox-api.coincircuit.io","description":"Sandbox Server"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key (obtain from dashboard)"}},"schemas":{"UpdateCustomerDto":{"type":"object","properties":{"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"}}},"CustomerResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","description":"Response message"},"data":{"description":"Customer data","allOf":[{"$ref":"#/components/schemas/CustomerDto"}]}},"required":["success","message"]},"CustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the customer"},"firstName":{"type":"string","description":"First name of the customer"},"lastName":{"type":"string","description":"Last name of the customer"},"email":{"type":"string","description":"Email address of the customer"},"phone":{"type":"string","description":"Phone number of the customer"},"telegramId":{"type":"string","description":"Telegram user ID if customer is linked via Telegram"},"metadata":{"type":"object","description":"Additional metadata for the customer"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the customer was last updated"}},"required":["id","createdAt","updatedAt"]}}},"paths":{"/api/v1/customers/{id}":{"patch":{"description":"Updates the customer.","operationId":"CustomersController_update","parameters":[{"name":"id","required":true,"in":"path","description":"Customer UUID","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponseDto"}}}},"400":{"description":"Invalid input data or duplicate email/phone/telegram ID"},"404":{"description":"Customer not found"}},"summary":"Update customer","tags":["Customers"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.coincircuit.io/customers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.