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

# Customers API

> Customer CRUD, cohorts, LTV analysis, journeys, and attribution lookup

# Customers API

Customer APIs manage workspace-scoped customer identity and analysis. These endpoints are feature-gated behind revenue tracking.

## Feature gate

All `/customers/*` routes require revenue-tracking entitlement on the workspace plan.

## Endpoint matrix

| Method   | Path                             | Purpose                                                             |
| -------- | -------------------------------- | ------------------------------------------------------------------- |
| `GET`    | `/customers`                     | List customers with pagination/search                               |
| `GET`    | `/customers/count`               | Count customers in workspace                                        |
| `GET`    | `/customers/:id`                 | Fetch one customer (`ext_` prefix supported for external ID lookup) |
| `POST`   | `/customers`                     | Create or upsert by `externalId`                                    |
| `PATCH`  | `/customers/:id`                 | Update customer fields                                              |
| `DELETE` | `/customers/:id`                 | Soft-delete + PII scrub                                             |
| `GET`    | `/customers/cohorts`             | Cohort breakdown by time/campaign/source                            |
| `GET`    | `/customers/ltv-cohorts`         | LTV cohorts over N months                                           |
| `POST`   | `/customers/:id/recalculate-ltv` | Force LTV recompute                                                 |
| `GET`    | `/customers/:id/journey`         | Event timeline for customer                                         |
| `GET`    | `/customers/:id/attribution`     | Click/link/campaign attribution record                              |

## List query parameters (`GET /customers`)

| Param       | Type          | Notes                            |
| ----------- | ------------- | -------------------------------- |
| `page`      | `number`      | Default `1`                      |
| `limit`     | `number`      | Default `20`, max `100`          |
| `sortOrder` | `asc \| desc` | Defaults to `desc`               |
| `search`    | `string`      | Matches customer identity fields |

## Cohorts query parameters (`GET /customers/cohorts`)

| Param      | Type                                  | Notes                       |
| ---------- | ------------------------------------- | --------------------------- |
| `group_by` | `week \| month \| campaign \| source` | Invalid values return `400` |
| `start`    | `date`                                | Optional period start       |
| `end`      | `date`                                | Optional period end         |

## Identity model

Customer stitching is strongest when you consistently provide:

* `externalId` (required stable identity)
* `email` (recommended)
* `clickId` (recommended for attribution continuity)

## Delete behavior

Delete is soft-delete oriented for analytics integrity:

* keeps conversion/event history
* scrubs customer PII fields
* marks record state as deleted for normal UI/API listing

## Authorization and permissions

* `GET` endpoints: `links:read` or `analytics:read` depending on route.
* Mutations: `links:create`, `links:update`, `links:delete`.

## Caching behavior

Heavy read routes (`cohorts`, `ltv-cohorts`, `journey`, `attribution`) use short-lived snapshot caching for repeat queries.

## Typical failures

* `404 NOT_FOUND`: missing customer
* `409 DUPLICATE_EXTERNAL_ID`: external ID conflict on update
* `503 SERVICE_UNAVAILABLE`: analytics backend unavailable
* `500 ANALYTICS_ERROR`: analytics query execution failure

Related docs:

* `/api-reference/customers/cohorts-ltv-journey-and-attribution`
* `/user-guides/manual/data/events-and-customers-operations-reference`
* `/user-guides/manual/data/exports-and-operational-checks`