Accoil API

The Accoil API lets you read engagement data back out of Accoil — the counterpart to the Ingress API, which sends data in. All requests are sent to:

https://api.accoil.com

Use it to pull engagement scores, user and account activity, AI-generated insights, and segment membership into your CRM, support tooling, or analytics stack.

Authentication

Include your API token in the Authorization header using Bearer authentication:

Authorization: Bearer accoil_YOUR_API_TOKEN

Your API token is found in the Accoil dashboard under Settings > Product Settings > API Token.

This is not your ingress API key

The API token reads data out of Accoil. It is not the same as the api_key used to send event data in via the Ingress API.

Endpoints

Most endpoints are scoped to a workspace, so you'll typically start at Workspaces to find the workspace_id you want to query.

Endpoint	Description
GET /v2/workspaces	List the workspaces your token can access
GET /v2/workspaces/{id}	Retrieve a single workspace
GET /v2/accounts	List accounts in a workspace, ranked by engagement score
GET /v2/accounts/{id}	Retrieve a single account with its full metric set
GET /v2/users	List users in a workspace, or look one up by email or tracking ID
GET /v2/users/{id}	Retrieve a single user with its full metric set
GET /v2/segments	List segments in a workspace
GET /v2/segments/{id}	Retrieve a single segment
GET /v2/segments/{id}/members	List the members of a segment

The legacy GET /v1/accounts lookup is still supported and documented under Legacy (v1).

Response shape

List endpoints return a data array alongside a _meta block:

{
  "data": [ ... ],
  "_meta": {
    "total_count": 123,
    "returned_count": 20,
    "limit": 20,
    "offset": 0
  },
  "_links": { "next": { "href": "..." } },
  "_expansions": { ... }
}

Single-item endpoints return the resource under data, with _meta and _expansions alongside it rather than nested inside the object.

Resources carry a _links map of related URLs. self is the canonical URL for the resource, app (where present) deep-links to the resource in the Accoil web app, and named links such as users, accounts, and segments point at related collections — so you can follow links rather than assembling URLs yourself.

Pagination

Pass limit and offset to page through list endpoints.

A limit above the endpoint maximum is clamped, not rejected, and limit=0 is served as 1. Read _meta.limit for the value actually applied rather than assuming you got what you asked for.
A negative or non-numeric limit or offset returns a 400.
_meta.total_count reflects the same filters as the rows returned, and _links.next carries those filters forward — so it's safe to page until offset + returned_count >= total_count.

Expansions

Several endpoints accept an expand parameter to include extra data that costs an additional lookup — for example expand=insights,traits,segments on an account:

GET /v2/accounts/456?workspace_id=123&expand=insights,traits,segments

Every response includes an _expansions block listing what's available, what you used, and any parameters that weren't recognised, so you can discover the options from a live response. Expanded blocks are cached independently — insights for up to 30 minutes, traits for 15, segments for 10.

Rate limits

Every response carries the current rate limit state in its headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Errors

Errors return a consistent envelope with a stable, machine-readable code you can branch on:

{
  "error": {
    "message": "At least one lookup parameter is required",
    "status": "bad_request",
    "code": "missing_lookup_parameter",
    "details": { "available_parameters": ["id", "match_type/match_value pairs"] },
    "request_id": "..."
  }
}

Match on code rather than parsing message — the wording may change, the code will not. Include request_id when contacting support about a specific failure.