Accounts
List accounts in a workspace and retrieve full account detail.
Accounts are your customers — the companies whose engagement Accoil scores. GET /v2/accounts returns a paginated list ranked by engagement score, and each entry is a lean view: follow its _links.self to GET /v2/accounts/{id} for the full object.
The single-account endpoint supports expand=insights,traits,segments for AI-generated health analysis, account attributes, and segment membership.
Looking up an account by domain, name, or tracking ID rather than by Accoil ID? That's the legacy GET /v1/accounts lookup.
BearerAuthAuthorizationBearer <token>API Token Authentication
All API requests require authentication via a Bearer token. Provide your API token in the Authorization header of each request.
Example: Authorization: Bearer accoil_YOUR_API_TOKEN
You can create and manage your API token by navigating to: Settings > Product Settings > API Token in the Accoil web app.
⚠️ Note: This API token is used only for reading data from the Accoil API. It is not the same as the
api_keyused for sending (ingesting) event data into Accoil.
workspace_id*integerThe workspace ID used to scope the request. You can find the workspace ID in the app URL:
https://app.accoil.com/48/scores/{workspace_id}/accounts/{id} Example: For the URL https://app.accoil.com/48/scores/123/accounts/154, the workspace_id is 123
Omitting it returns 400 (missing_workspace_id); a value that isn't a
positive integer returns 400 (invalid_workspace_id). A well-formed ID
that doesn't belong to your product returns 404
(workspace_id_not_found).
1 <= valuesort?stringSort field.
"score""score""name""last_seen""first_seen""activation_rate""score_change""active_users""total_users""frequency"order?stringSort order.
"desc""asc""desc"limit?integerMaximum number of results to return.
1 <= value <= 10020offset?integerNumber of results to skip for pagination.
0 <= value0segment_id?integerFilter accounts by membership in an account-scoped segment in this
workspace. Returns 400 with code invalid_segment_scope if the
segment is user-scoped, 404 with code segment_not_found if it
doesn't belong to the workspace.
Accounts retrieved successfully
application/json- response
data*array<>_meta*_links?A collection of hypermedia links keyed by name. The set of available link
names varies by endpoint — self is the canonical URL for the resource,
app (when present) points at the in-app page for the resource on the
active Accoil host (e.g. https://app.accoil.com/...), and additional
named links point at related collections or actions.
curl -X GET 'https://api.accoil.com/v2/accounts?workspace_id=1'{ "data": [ { "id": "456", "name": "TechCorp Solutions", "tracking_id": "ext-12345", "metrics": { "engagement_score": 75.5, "raw_score": 2150, "score_change": 2.5, "activation_rate": 0.85, "first_seen": "2023-01-15", "last_seen": "2025-09-21", "active_users": 12, "total_people_count": 18 }, "_links": { "self": { "href": "/v2/accounts/456?workspace_id=123" } } } ], "_meta": { "total_count": 85, "returned_count": 1, "limit": 20, "offset": 0, "workspace_id": 123 }, "_links": { "self": { "href": "/v2/accounts?workspace_id=123&sort=score&order=desc&limit=20&offset=0" }, "next": { "href": "/v2/accounts?workspace_id=123&sort=score&order=desc&limit=20&offset=20" } }}BearerAuthAuthorizationBearer <token>API Token Authentication
All API requests require authentication via a Bearer token. Provide your API token in the Authorization header of each request.
Example: Authorization: Bearer accoil_YOUR_API_TOKEN
You can create and manage your API token by navigating to: Settings > Product Settings > API Token in the Accoil web app.
⚠️ Note: This API token is used only for reading data from the Accoil API. It is not the same as the
api_keyused for sending (ingesting) event data into Accoil.
id*integerThe internal Accoil account ID.
workspace_id*integerThe workspace ID used to scope the request. You can find the workspace ID in the app URL:
https://app.accoil.com/48/scores/{workspace_id}/accounts/{id} Example: For the URL https://app.accoil.com/48/scores/123/accounts/154, the workspace_id is 123
Omitting it returns 400 (missing_workspace_id); a value that isn't a
positive integer returns 400 (invalid_workspace_id). A well-formed ID
that doesn't belong to your product returns 404
(workspace_id_not_found).
1 <= valueexpand?stringComma-separated list of optional data blocks to include.
insights: AI-generated account health analysistraits: account attributes and custom propertiessegments: segment memberships
Account retrieved successfully
application/json- response
data*_meta?Response-level metadata returned alongside the data payload on show
endpoints. Carries the workspace and product context needed to build
app deep-links (the app URL is also pre-computed on _links.app,
but the IDs are exposed for callers that want to construct their own).
_expansions?curl -X GET 'https://api.accoil.com/v2/accounts/0?workspace_id=1'{ "data": { "id": "string", "name": "string", "domain": "string", "tracking_id": "string", "metrics": { "engagement_score": 0, "raw_score": 0.1, "score_change": 0.1, "owner_name": "string", "first_seen": "2019-08-24", "last_seen": "2019-08-24", "active_users": 0, "activation_rate": 0, "overall_scored_events": 0, "recently_scored_events": 0, "scoring_profile_events": 0, "total_people_count": 0, "total_active_people_count": 0 }, "insights": { "summary": "string" }, "traits": [ { "name": "string", "data_type": "string", "value": "string", "scope": "user" } ], "segments": [ { "id": "string", "name": "string", "default": true } ], "_links": { "property1": { "href": "string" }, "property2": { "href": "string" } } }, "_meta": { "workspace_id": 0, "product_id": 0 }, "_expansions": { "available": [ "string" ], "documentation": "string", "unknown_parameters": [ "string" ], "error": "string" }}