Skip to main content

​
Customers API

Customer APIs manage workspace-scoped customer identity and analysis. These endpoints are feature-gated behind revenue tracking.

​
Feature gate

All /customers/* routes require revenue-tracking entitlement on the workspace plan.

​
Endpoint matrix

​
List query parameters (GET /customers)

​
Cohorts query parameters (GET /customers/cohorts)

​
Identity model

Customer stitching is strongest when you consistently provide:
  • externalId (required stable identity)
  • email (recommended)
  • clickId (recommended for attribution continuity)

​
Delete behavior

Delete is soft-delete oriented for analytics integrity:
  • keeps conversion/event history
  • scrubs customer PII fields
  • marks record state as deleted for normal UI/API listing

​
Authorization and permissions

  • GET endpoints: links:read or analytics:read depending on route.
  • Mutations: links:create, links:update, links:delete.

​
Caching behavior

Heavy read routes (cohorts, ltv-cohorts, journey, attribution) use short-lived snapshot caching for repeat queries.

​
Typical failures

  • 404 NOT_FOUND: missing customer
  • 409 DUPLICATE_EXTERNAL_ID: external ID conflict on update
  • 503 SERVICE_UNAVAILABLE: analytics backend unavailable
  • 500 ANALYTICS_ERROR: analytics query execution failure
Related docs:
  • /api-reference/customers/cohorts-ltv-journey-and-attribution
  • /user-guides/manual/data/events-and-customers-operations-reference
  • /user-guides/manual/data/exports-and-operational-checks