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

# Avalex Customers API — Create, Read, Update, Delete

> Create, read, update, and delete customer records in Avalex. Manage contact details, social media handles, and internal staff notes via REST.

The `/customers` resource lets you manage the individuals and organizations that purchase your software. You can create new customer records, look up existing ones by ID, update contact details, and remove customers that are no longer needed. All requests must be authenticated with a JWT Bearer token or HTTP Basic credentials.

## Required Permissions

| Action                    | Permission         |
| ------------------------- | ------------------ |
| List / retrieve customers | `customers:read`   |
| Create / update customers | `customers:write`  |
| Delete customers          | `customers:delete` |

***

## List All Customers

<ParamField header="Authorization" type="string" required>
  Bearer `<token>` or Basic credentials.
</ParamField>

Retrieve an array of all customer records in your Avalex account.

```bash theme={null}
curl http://localhost:8080/customers \
  -H "Authorization: Bearer <token>"
```

**Response — 200 OK**

```json theme={null}
[
  {
    "id": "cust_123",
    "name": "Acme Corp",
    "email": "contact@acme.com",
    "socials": {
      "twitter": "@acme",
      "linkedin": "acmecorp"
    },
    "note": "VIP Client",
    "createdAtEpochMillis": 1723140000000
  }
]
```

***

## Create a Customer

<ParamField header="Authorization" type="string" required>
  Bearer `<token>` or Basic credentials.
</ParamField>

<ParamField body="name" type="string" required>
  Full name or company name of the customer.
</ParamField>

<ParamField body="email" type="string" required>
  Primary contact email address.
</ParamField>

<ParamField body="socials" type="object">
  Optional social media handles.
</ParamField>

<ParamField body="note" type="string">
  Internal note visible only to staff.
</ParamField>

Creates a new customer record and returns it with a server-generated ID.

```bash theme={null}
curl -X POST http://localhost:8080/customers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "contact@acme.com",
    "socials": {
      "twitter": "@acme",
      "linkedin": "acmecorp"
    },
    "note": "VIP Client"
  }'
```

**Response — 201 Created**

```json theme={null}
{
  "id": "cust_123",
  "name": "Acme Corp",
  "email": "contact@acme.com",
  "socials": {
    "twitter": "@acme",
    "linkedin": "acmecorp"
  },
  "note": "VIP Client",
  "createdAtEpochMillis": 1723140000000
}
```

***

## Get a Customer by ID

<ParamField path="id" type="string" required>
  The unique customer ID (e.g. `cust_123`).
</ParamField>

Returns a single customer record. Responds with `404 Not Found` if no customer with that ID exists.

```bash theme={null}
curl http://localhost:8080/customers/cust_123 \
  -H "Authorization: Bearer <token>"
```

**Response — 200 OK**

```json theme={null}
{
  "id": "cust_123",
  "name": "Acme Corp",
  "email": "contact@acme.com",
  "socials": {
    "twitter": "@acme",
    "linkedin": "acmecorp"
  },
  "note": "VIP Client",
  "createdAtEpochMillis": 1723140000000
}
```

***

## Update a Customer

<ParamField path="id" type="string" required>
  The unique customer ID.
</ParamField>

Performs a full replacement of the customer record. You must supply all fields — omitted fields will be cleared. Returns `404 Not Found` if the customer does not exist.

<Note>
  This is a full replacement (`PUT`). If you omit `socials` or `note`, those fields will be unset on the stored record. Include all existing values you want to retain.
</Note>

```bash theme={null}
curl -X PUT http://localhost:8080/customers/cust_123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "new-contact@acme.com",
    "socials": {
      "twitter": "@acme",
      "linkedin": "acmecorp"
    },
    "note": "VIP Client — renewed 2024"
  }'
```

**Response — 200 OK**

```json theme={null}
{
  "id": "cust_123",
  "name": "Acme Corp",
  "email": "new-contact@acme.com",
  "socials": {
    "twitter": "@acme",
    "linkedin": "acmecorp"
  },
  "note": "VIP Client — renewed 2024",
  "createdAtEpochMillis": 1723140000000
}
```

***

## Delete a Customer

<ParamField path="id" type="string" required>
  The unique customer ID.
</ParamField>

Permanently removes the customer record. Returns `204 No Content` on success and `404 Not Found` if the ID does not exist.

```bash theme={null}
curl -X DELETE http://localhost:8080/customers/cust_123 \
  -H "Authorization: Bearer <token>"
```

**Response — 204 No Content**

***

## Customer Schema

The following fields are returned on every Customer object.

<Expandable title="Customer fields">
  <ResponseField name="id" type="string">
    Unique identifier for the customer, assigned by Avalex on creation (e.g. `cust_123`).
  </ResponseField>

  <ResponseField name="name" type="string">
    Full name or company name of the customer.
  </ResponseField>

  <ResponseField name="email" type="string">
    Primary contact email address for the customer.
  </ResponseField>

  <ResponseField name="socials.twitter" type="string">
    Twitter / X handle associated with the customer (e.g. `@acme`).
  </ResponseField>

  <ResponseField name="socials.linkedin" type="string">
    LinkedIn profile slug or company page identifier (e.g. `acmecorp`).
  </ResponseField>

  <ResponseField name="note" type="string">
    Free-text internal note visible only to staff. Not exposed to the customer.
  </ResponseField>

  <ResponseField name="createdAtEpochMillis" type="number">
    Unix timestamp in milliseconds representing when this customer record was created.
  </ResponseField>
</Expandable>

### Full Schema Example

```json theme={null}
{
  "id": "cust_123",
  "name": "Acme Corp",
  "email": "contact@acme.com",
  "socials": {
    "twitter": "@acme",
    "linkedin": "acmecorp"
  },
  "note": "VIP Client",
  "createdAtEpochMillis": 1723140000000
}
```