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

# Customers API

> API endpoints for managing customer records

## Overview

The Customers API allows you to create, read, update, and manage customer records. Customers are the foundation for work orders, service contracts, and billing.

***

## Endpoints

### List Customers

Retrieve a list of customers.

```
GET /api/v1/customers
```

**Query Parameters:**

| Parameter       | Type    | Description                 |
| --------------- | ------- | --------------------------- |
| `page`          | integer | Page number                 |
| `per_page`      | integer | Results per page (max: 100) |
| `search`        | string  | Search by name or code      |
| `status`        | string  | Filter by status            |
| `branch_id`     | string  | Filter by branch            |
| `created_after` | date    | Filter by creation date     |

**Example Request:**

```bash theme={null}
curl -X GET "https://api.fentu.io/v1/customers?search=acme&per_page=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Example Response:**

```json theme={null}
{
  "data": [
    {
      "id": "cust-001",
      "name": "Acme Corporation",
      "customer_number": "C-10001",
      "status": "active",
      "email": "contact@acme.com",
      "phone": "+1-555-123-4567",
      "address": {
        "street": "123 Main Street",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
      },
      "created_at": "2023-06-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 10,
    "total_count": 245
  }
}
```

***

### Get Customer

Retrieve a single customer with full details.

```
GET /api/v1/customers/{id}
```

**Example Response:**

```json theme={null}
{
  "data": {
    "id": "cust-001",
    "name": "Acme Corporation",
    "customer_number": "C-10001",
    "status": "active",
    "customer_type": "commercial",
    "email": "contact@acme.com",
    "phone": "+1-555-123-4567",
    "fax": "+1-555-123-4568",
    "website": "https://acme.com",
    "address": {
      "street": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "billing_address": {
      "street": "456 Finance Ave",
      "city": "New York",
      "state": "NY",
      "postal_code": "10002",
      "country": "US"
    },
    "contacts": [
      {
        "id": "contact-001",
        "name": "John Smith",
        "title": "Facilities Manager",
        "email": "jsmith@acme.com",
        "phone": "+1-555-111-2222",
        "is_primary": true
      }
    ],
    "branch": {
      "id": "branch-001",
      "name": "Northeast Region"
    },
    "tax_id": "12-3456789",
    "payment_terms": "net30",
    "notes": "VIP customer - priority service",
    "custom_fields": {
      "industry": "Manufacturing",
      "employee_count": "500+"
    },
    "created_at": "2023-06-15T10:30:00Z",
    "updated_at": "2024-01-20T14:15:00Z"
  }
}
```

***

### Create Customer

Create a new customer record.

```
POST /api/v1/customers
```

**Request Body:**

```json theme={null}
{
  "name": "New Company Inc",
  "customer_type": "commercial",
  "email": "info@newcompany.com",
  "phone": "+1-555-999-8888",
  "address": {
    "street": "789 Business Blvd",
    "city": "Chicago",
    "state": "IL",
    "postal_code": "60601",
    "country": "US"
  },
  "branch_id": "branch-002",
  "payment_terms": "net30"
}
```

**Example Response:**

```json theme={null}
{
  "data": {
    "id": "cust-002",
    "customer_number": "C-10002",
    "name": "New Company Inc",
    "status": "active",
    "created_at": "2024-01-27T16:00:00Z"
  }
}
```

***

### Update Customer

Update an existing customer.

```
PUT /api/v1/customers/{id}
```

**Request Body:**

```json theme={null}
{
  "email": "newemail@company.com",
  "phone": "+1-555-888-7777",
  "notes": "Updated contact information"
}
```

***

### Delete Customer

Delete a customer (moves to trash).

```
DELETE /api/v1/customers/{id}
```

<Warning>
  Customers with active work orders or contracts cannot be deleted. Complete or cancel related records first.
</Warning>

***

## Customer Contacts

### List Contacts

```
GET /api/v1/customers/{customer_id}/contacts
```

### Create Contact

```
POST /api/v1/customers/{customer_id}/contacts
```

**Request Body:**

```json theme={null}
{
  "name": "Jane Doe",
  "title": "Operations Manager",
  "email": "jdoe@company.com",
  "phone": "+1-555-222-3333",
  "is_primary": false
}
```

### Update Contact

```
PUT /api/v1/contacts/{id}
```

### Delete Contact

```
DELETE /api/v1/contacts/{id}
```

***

## Customer Assets

### List Customer Assets

```
GET /api/v1/customers/{customer_id}/assets
```

### Get Asset

```
GET /api/v1/assets/{id}
```

See the [Assets API](/api-reference/endpoints/assets) for full asset management.

***

## Customer Work Orders

### List Customer Work Orders

```
GET /api/v1/customers/{customer_id}/work-orders
```

Returns work orders for the specified customer.

***

## Error Responses

| Code  | Description          |
| ----- | -------------------- |
| `400` | Bad request          |
| `401` | Unauthorized         |
| `403` | Forbidden            |
| `404` | Customer not found   |
| `409` | Conflict (duplicate) |
| `422` | Validation error     |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Assets API" icon="barcode" href="/api-reference/endpoints/assets">
    Asset endpoints
  </Card>

  <Card title="Work Orders API" icon="clipboard-list" href="/api-reference/endpoints/work-orders">
    Work order endpoints
  </Card>

  <Card title="Customers" icon="users" href="/customers/customers">
    Customer user guide
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API authentication
  </Card>
</CardGroup>