Fundamentals

Cursor pagination

List endpoints use cursor pagination and return data and has_more. The default limit is 25 items and can be set from 1 to 100.

{
  "data": [
    {
      "object": "segment",
      "id": "seg_ckxyz123",
      "name": "VIP customers"
    }
  ],
  "has_more": true
}

To fetch the next page, send the last item’s id as starting_after:

curl --get https://api.bevits.com/v1/segments \
  --header "Authorization: Bearer $BEVITS_API_KEY" \
  --data-urlencode "limit=25" \
  --data-urlencode "starting_after=seg_ckxyz123"

Continue while has_more is true. Do not reuse a cursor from one resource type in a different list.

Public IDs

IDs are opaque strings with a prefix that identifies the resource.

Prefix	Resource
`org_`	Organization
`bak_`	API key
`cus_`	Customer
`seg_`	Segment
`pur_`	Purchase
`tag_`	Tag
`atr_`	Attribute
`flw_`	Flow
`emc_`	Email campaign

Treat IDs as strings. Do not remove the prefix or try to infer their contents.

Filters and dates

Filters are sent as query parameters. Dates use ISO 8601 with an offset; responses are normalized to UTC.

curl --get https://api.bevits.com/v1/customers \
  --header "Authorization: Bearer $BEVITS_API_KEY" \
  --data-urlencode "is_subscribed=true" \
  --data-urlencode "updated_since=2026-07-01T00:00:00Z"

Fields without a value are omitted from responses instead of returning null. Monetary values use cents, such as total_spent_in_cents: 15990.

Errors

Errors are never returned with status 200. The error.type field is stable for automation; message is human-readable; and request_id identifies the request for support.

{
  "error": {
    "type": "validation_error",
    "message": "Invalid input: expected number, received NaN",
    "param": "limit",
    "request_id": "req_07f6cdc3c20249d6afcd90b4"
  }
}

HTTP	`error.type`	Meaning
`400`	`invalid_request`	Invalid route, cursor, or request format.
`401`	`authentication_error`	Missing, invalid, expired, or revoked API key.
`403`	`permission_denied`	The credential does not have the required permission.
`404`	`not_found`	The resource does not exist or belongs to another organization.
`409`	`conflict`	The request conflicts with the resource’s current state.
`422`	`validation_error`	A parameter or value failed validation.
`429`	`rate_limited`	The request limit was exceeded.
`500`	`internal_error`	An unexpected server error occurred.

Rate limit

The initial limit is 600 requests per minute, per API key. Authenticated responses include:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 2026-07-25T21:31:00.000Z

When you receive 429, wait the number of seconds in Retry-After before retrying. Use backoff with jitter in automated integrations.

Conditional caching

Resource responses include an ETag. Send that value in If-None-Match to avoid downloading unchanged content again:

If-None-Match: "v1-4ad31f5efb6b8f35"

When the content is identical, the API returns 304 Not Modified without a response body.

Getting started

Reference

Fundamentals

Public IDs

Filters and dates

Errors

Rate limit

Conditional caching

​Cursor pagination

​Public IDs

​Filters and dates

​Errors

​Rate limit

​Conditional caching

Cursor pagination

Public IDs

Filters and dates

Errors

Rate limit

Conditional caching