> ## Documentation Index
> Fetch the complete documentation index at: https://docs.g-tateth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

Manage customer profiles in your CRM. Customers represent individuals or companies that interact with your business.

## List Customers

<Endpoint method="GET" path="/api/v1/customers">
  List all customers for your tenant
</Endpoint>

<ParamField query="search" type="string" optional>
  Search by name, email, phone, or company
</ParamField>

<ParamField query="tier" type="string" optional>
  Filter by customer tier: `bronze`, `silver`, `gold`, `platinum`
</ParamField>

<ParamField query="status" type="string" optional>
  Filter by status: `active`, `inactive`, `archived`
</ParamField>

<ParamField query="tags" type="array" optional>
  Filter by tags (array of strings)
</ParamField>

<ParamField query="page" type="integer" optional>
  Page number (default: 1)
</ParamField>

<ParamField query="limit" type="integer" optional>
  Items per page (default: 20, max: 100)
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data" type="array">
  Array of customer objects
</ResponseField>

<ResponseField name="pagination.total" type="number">
  Total number of customers
</ResponseField>

<ResponseField name="pagination.page" type="number">
  Current page number
</ResponseField>

<ResponseField name="pagination.limit" type="number">
  Items per page
</ResponseField>

<ResponseField name="pagination.totalPages" type="number">
  Total number of pages
</ResponseField>

### Example Request

```bash theme={null}
curl -X GET "https://api.g-tateth.com/api/v1/customers?search=john&tier=gold&page=1&limit=20" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "profile": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "phone": "+1234567890",
        "company": "Acme Corp"
      },
      "tier": "gold",
      "status": "active",
      "tags": ["vip", "enterprise"],
      "createdAt": "2024-01-01T12:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}
```

## Get Customer

<Endpoint method="GET" path="/api/v1/customers/:id">
  Get details of a specific customer
</Endpoint>

<ParamField path="id" type="string" required>
  Customer ID
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data._id" type="string">
  Customer ID
</ResponseField>

<ResponseField name="data.profile.firstName" type="string">
  Customer first name
</ResponseField>

<ResponseField name="data.profile.lastName" type="string">
  Customer last name
</ResponseField>

<ResponseField name="data.profile.email" type="string">
  Customer email address
</ResponseField>

<ResponseField name="data.profile.phone" type="string">
  Customer phone number
</ResponseField>

<ResponseField name="data.profile.company" type="string">
  Company name
</ResponseField>

<ResponseField name="data.tier" type="string">
  Customer tier: `bronze`, `silver`, `gold`, `platinum`
</ResponseField>

<ResponseField name="data.status" type="string">
  Status: `active`, `inactive`, `archived`
</ResponseField>

<ResponseField name="data.tags" type="array">
  Array of tag strings
</ResponseField>

<ResponseField name="data.createdAt" type="string">
  ISO 8601 timestamp of creation
</ResponseField>

<ResponseField name="data.updatedAt" type="string">
  ISO 8601 timestamp of last update
</ResponseField>

### Example Request

```bash theme={null}
curl -X GET "https://api.g-tateth.com/api/v1/customers/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "tenantId": "507f191e810c19729de860ea",
    "profile": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "company": "Acme Corp"
    },
    "tier": "gold",
    "status": "active",
    "tags": ["vip", "enterprise"],
    "createdAt": "2024-01-01T12:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}
```

## Create Customer

<Endpoint method="POST" path="/api/v1/customers">
  Create a new customer
</Endpoint>

<ParamField body="firstName" type="body" optional>
  Customer first name
</ParamField>

<ParamField body="lastName" type="body" optional>
  Customer last name
</ParamField>

<ParamField body="email" type="body" optional>
  Customer email address
</ParamField>

<ParamField body="phone" type="body" optional>
  Customer phone number
</ParamField>

<ParamField body="company" type="body" optional>
  Company name
</ParamField>

<ParamField body="jobTitle" type="body" optional>
  Job title
</ParamField>

<ParamField body="tier" type="body" optional>
  Customer tier: `bronze`, `silver`, `gold`, `platinum` (default: `standard`)
</ParamField>

<ParamField body="tags" type="body" optional>
  Array of tag strings
</ParamField>

<ParamField body="customFields" type="body" optional>
  Custom fields object
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data" type="object">
  Created customer object
</ResponseField>

<Note>
  At least one of `firstName`, `lastName`, `email`, or `phone` is required.
</Note>

## Update Customer

<Endpoint method="PUT" path="/api/v1/customers/:id">
  Update a customer
</Endpoint>

<ParamField path="id" type="string" required>
  Customer ID
</ParamField>

<ParamField body="firstName" type="body" optional>
  Update first name
</ParamField>

<ParamField body="lastName" type="body" optional>
  Update last name
</ParamField>

<ParamField body="email" type="body" optional>
  Update email address
</ParamField>

<ParamField body="phone" type="body" optional>
  Update phone number
</ParamField>

<ParamField body="company" type="body" optional>
  Update company name
</ParamField>

<ParamField body="jobTitle" type="body" optional>
  Update job title
</ParamField>

<ParamField body="tier" type="body" optional>
  Update customer tier
</ParamField>

<ParamField body="status" type="body" optional>
  Update status: `active`, `inactive`, `archived`
</ParamField>

<ParamField body="tags" type="body" optional>
  Update tags array
</ParamField>

<ParamField body="customFields" type="body" optional>
  Update custom fields
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data" type="object">
  Updated customer object
</ResponseField>

## Delete Customer

<Endpoint method="DELETE" path="/api/v1/customers/:id">
  Delete a customer
</Endpoint>

<ParamField path="id" type="string" required>
  Customer ID
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<Warning>
  This action cannot be undone! Deleting a customer will permanently remove them and their data.
</Warning>

## Required Permissions

* `read:customers` - Required for GET requests
* `write:customers` - Required for POST, PUT, DELETE requests