Frequently Asked Questions

The OAuth 2.0 Authorization Code Flow with PKCE. It’s required for all integrations; the Client Credentials Flow isn’t supported. See Authentication & Authorization.

No. tour_id appeared in earlier documentation but isn’t required. The authorization request only needs response_type, client_id, redirect_uri, scope, code_challenge, and code_challenge_method.

Yes. Refresh tokens are single-use. Each refresh returns a new access token and a new refresh token, and you must store the new refresh token from every response.

You can lose access in two ways: breaking the rotation chain (for example, failing to store the new refresh token), or leaving a refresh token unused for 90 days. Since every refresh issues a new refresh token, the 90-day limit only affects integrations that have been inactive that long. Refresh tokens aren’t affected by the access token expiring.

Nothing is lost. Use your stored refresh token to get a new access token any time within 90 days of that refresh token being issued. Re-authorization is only needed if you no longer hold a valid refresh token.

Refresh proactively using the expires_in value rather than waiting for a 401. If your integration is seasonal or low-traffic, run a scheduled refresh (at least monthly) so the 90-day window never lapses.

Securely on your backend. Never expose access_token, refresh_token, or client_secret client-side.

Your OAuth application client ID, scoped to your organization. It’s required on every API request alongside Authorization: Bearer <access_token>.

Not yet; it’s coming soon. Beta partners test against production using a dedicated test brand. Contact api@hive.co to get one set up.

A status page is planned at api.hive.co/status but isn’t live yet. This documentation will be updated once it is.

Write endpoints are asynchronous. 202 means your request was received and queued, not that processing is complete. Data typically appears in Hive within minutes, though during beta it can take up to an hour. See How It Works.

No. 202 is a success response. Only retry on network failures or 5xx errors, and don’t retry 4xx responses without first fixing the request. Asynchronous data pushes are upserts, so retrying them is safe. POST /segments/ isn’t idempotent: a retry after a 5xx can return 409 Conflict if the first request created the segment.

Hive uses all-or-nothing validation. If any item fails validation, the entire request is rejected with 422 and no records are written. For batch writes, the error response includes the index of the failing item and a field-level message. Fix the invalid record and resubmit the full batch.

1 request per second sustained (60 per minute) and 2 per second burst (120 per minute). Batches are limited to 50 items and 1 MB per request. Exceeding the rate limit returns 429 Too Many Requests. See Rate Limits.

Send as few requests as possible, with as many records per request as the batch limit allows (up to 50). One request of 50 records is better than 50 requests of 1 record.

No. An order is scoped to a single event. If a purchaser bought tickets to multiple events in one transaction, send a separate order object for each, each with its own event_id.

Send them as separate events for now. A dedicated event series concept is planned for a future API version.

No. POST /contacts/ handles both creates and updates. If a contact with the same email or phone number already exists, it’s updated.

No. Contact deletion is intentionally not supported, to preserve historical ticketing and engagement data. You can delete custom properties from contacts.

Currently yes: submitting an order can create the contact if one doesn’t already exist. However, this behavior isn’t guaranteed. Request both contacts:write and orders:write, and make sure the contact exists before submitting its orders.

No. Messaging is configured and triggered inside Hive. You can, however, add contacts to segments through the API to trigger segment-based automations.

Yes, for email, SMS, and Meta ad campaigns. Each channel has a list endpoint plus single campaign and aggregate stats endpoints. See Campaign Reporting. Raw per-recipient open and click events aren’t available; manual CSV export from Hive is the workaround.

Only where a read endpoint exists: segments and segment users, custom event property definitions, and email, SMS, and ad campaign lists and stats. There’s no bulk export of contacts, orders, or raw engagement events, and that isn’t on the near-term roadmap.

Use the API for server-side integrations: pushing ticketing, order, and contact data from your backend. Use the JS SDK for browser-side tracking, such as page views and form submissions. The JS SDK isn’t designed to run server-side.