How It Works | Hive API | Documentation

Request lifecycle

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

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

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 management, and creating or deleting 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:

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

See 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.
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 to get started.