> For the complete documentation index, see [llms.txt](https://docs.customer-alliance.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.customer-alliance.com/introduction.md).

# Introduction

## Customer Alliance API

Review management, surveys, and feedback for hospitality, as an API. Pull your reviews, surveys and responses, analytics and AI insights; push in guests, and reviews and survey responses from platforms Customer Alliance has no connector for; and subscribe to events with outbound webhooks.

### What you can do

* **Reviews** — list and fetch collected reviews and your published replies, and push in reviews from other platforms (see [Pushing reviews and survey responses](https://docs.customer-alliance.com/pushing-reviews-and-survey-responses)).
* **Surveys** — read published surveys, their responses and answers (PII-free), and push in responses from other survey tools.
* **Analytics** — aggregate reputation and rating scores for any part of your hierarchy.
* **Insights** — AI recommendations, topic mentions and the topic taxonomy.
* **Guests** — create or update guests, with their stays, at a property (write-only).
* **Nodes** — discover the business-unit / property hierarchy your key can see, and the property attributes (brand, operating model, region…) that group your properties, to rebuild the same groups in a BI tool (see [Property attributes](https://docs.customer-alliance.com/property-attributes)).
* **Webhooks** — register endpoints and receive signed event deliveries.

### Base URL

All endpoints are relative to:

`https://app.customer-alliance.com/api/v4`

### Authentication

Every request needs your API key as a Bearer token. Create and scope keys in the Customer Alliance dashboard under **Settings → API** — the key (`ca_live_…`) is shown once, so store it somewhere safe.

```bash
curl https://app.customer-alliance.com/api/v4/reviews \
  -H "Authorization: Bearer ca_live_your_key_here"
```

### Your first request

Call `/whoami` to confirm your key resolves to the account, node and scopes you expect:

```bash
curl https://app.customer-alliance.com/api/v4/whoami \
  -H "Authorization: Bearer ca_live_your_key_here"
```

```json
{
  "account_id": "a1b2c3d4-…",
  "node_id": "e5f6a7b8-…",
  "scopes": ["reviews:read", "surveys:read", "webhooks:manage"]
}
```

### Scopes

Each key holds only the scopes you grant it — `reviews:read`, `surveys:read`, `analytics:read`, `insights:read`, `nodes:read`, `webhooks:manage`, `guests:write`, `reviews:write`, `surveys:write`. A request missing its scope returns `403`.

### Pagination

List endpoints are cursor-paginated. Pass the previous response's `next_cursor` as `?cursor=`, up to `?limit=` (max 100), and stop when `has_more` is `false`.

### Rate limits

Requests are rate-limited per key. If you exceed the limit you'll get a `429` with a `Retry-After` header — wait that many seconds before retrying.

### Webhooks

Rather than polling, register a webhook endpoint and we'll POST signed events to you — new reviews, completed survey responses, alerts and more. See **Webhook Events** for every payload, and verify the `X-CA-Signature` header on each delivery. Manage endpoints under **Webhooks**.

### Need help?

Email <info@customer-alliance.com> or visit [customer-alliance.com](https://www.customer-alliance.com/).