> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hive.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hive.co/_mcp/server.

# How It Works

## Request lifecycle

```
You send data → Hive acknowledges (202) → Data is queued → Processing completes
```

1. **Send a request** with your contact, order, or event data.
2. **The data is scoped to a brand**: the brand linked to the access token you authorize with.
3. **Receive `202 Accepted`** immediately, confirming Hive received your data.
4. **Data is processed** asynchronously in Hive's pipeline.
5. **Data appears in Hive**, typically within minutes (up to 1 hour during beta).

> **Note**
>
> A `202 Accepted` response means your request was received and queued, **not** that processing is
> complete. Don't retry after a `202`.

Some endpoints are synchronous and return their result directly (for example, `200 OK`, `201 Created`, or `204 No Content`): all read endpoints, [custom event property](/docs/events#custom-event-properties) management, and creating or deleting [segments](/docs/segments).

## Idempotent writes

Sending the same record multiple times is safe and doesn't create duplicates. Hive updates the existing record based on its unique identifier, as long as the identifier stays the same:

| Resource | Matched by                |
| -------- | ------------------------- |
| Contacts | `email` or `phone_number` |
| Orders   | `order_id`                |
| Events   | `event_id`                |

## Batch validation

Batch writes use **all-or-nothing validation**. If any item in a batch is invalid, the entire request is rejected with `422 Unprocessable Entity` and no records are written. Fix the invalid record and resubmit the full batch.

Errors are keyed by resource name, then item index, then field path:

```json
{
    "orders": {
        "0": {
            "user": { "email": ["Enter a valid email address."] }
        }
    }
}
```

See [Errors & Status Codes](/docs/errors-status-codes) for every response code.

## Retries

* Retry only on network failures or `5xx` errors.
* Asynchronous data pushes are upserts, so retrying them is safe. `POST /segments/` isn't idempotent: if a retried request's original succeeded, the retry returns `409 Conflict`.
* On `429 Too Many Requests`, back off before retrying. See [Rate Limits](/docs/rate-limits).
* Don't retry other `4xx` responses without first fixing the request.

## Testing

A sandbox environment is coming soon. In the meantime, Hive sets up a dedicated test brand for your integration testing. Contact [api@hive.co](mailto:api@hive.co) to get started.