# Customer Data API

> Read-only access to a workspace's own orders and conversations, for BI tools, data warehouses and reconciliation jobs.

## Authentication

Create the key in the dashboard under **Settings → API**. Owners and admins can create, replace and revoke it. The key is shown once, when it is created or replaced, so copy it then; if it is lost, replace it. Replacing or revoking stops the old key at once.

Send the key from your server, never from browser or mobile app code:

```bash
curl "https://api.joinhexagon.com/api/v1/customer-data/orders?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

`X-Hexagon-Api-Key: YOUR_API_KEY` is accepted too. Keys look like `hx_live_` followed by 64 lowercase hex characters, and each key reads exactly one workspace.

## Endpoints

| Method and path | What it returns |
| --- | --- |
| `GET /api/v1/customer-data/orders` | Orders, newest first. Filters: `status`, `from_date`, `to_date`, `search` (order references). |
| `GET /api/v1/customer-data/orders/{orderId}` | One order, by id or order number. |
| `GET /api/v1/customer-data/conversations` | Conversations. Filters: `status`, `funnel_stage`, `from_date`, `to_date`, `search` (conversation ids). |
| `GET /api/v1/customer-data/conversations/{conversationId}` | One conversation with its messages. Page messages with `message_limit` (default 100, max 500) and `message_offset`. |

Finance reconciliation and chargeback endpoints exist under `/api/v1/customer-data/finance/`. They are off by default; ask Hexagon support to enable them for your workspace.

## Pagination

List endpoints take `limit` (default 50, max 100) and `offset`, and answer:

```json
{ "success": true, "data": { "orders": [], "pagination": { "limit": 50, "offset": 0, "total": 0, "hasMore": false } } }
```

Keep requesting with `offset + limit` while `hasMore` is true.

## Data you get

- Orders carry stable ids, the merchant order reference, status, payment status, totals, currency, coupon summary, line items and lifecycle timestamps.
- Customers appear as a pseudonymous `customer.id` (the same across orders and conversations) plus the phone number, so you can join records you already own.
- Raw customer names, emails, shipping addresses and payment-provider details are not returned.

## Errors and limits

- `401`: missing, malformed, replaced or revoked key.
- `403`: the API is turned off for this workspace, or the request came from a network outside its allow-list.
- `404`: the record does not exist in this workspace.
- `429`: too many requests. Each key allows 120 requests a minute in total and 60 a minute from any one IP address.

Responses are sent with `Cache-Control: no-store`. Store what you need in your own systems.