Users
List users in a workspace and retrieve full user detail.
Users are the individual people inside your customer accounts. GET /v2/users returns a paginated list for a workspace, and doubles as the lookup: pass match_type and match_value together to find the user matching an external identifier such as email or tracking_id. The response shape doesn't change — you just get a list with zero or one entry.
match_type and match_value must always be supplied together. Sending one without the other returns a 400 with code missing_match_parameter rather than falling back to an unfiltered list.
For the complete metric set — score_yesterday, score_last_period, overall_scored_events, recently_scored_events — and the traits and segments expansions, use GET /v2/users/{id}. Expanding traits requires naming the traits you want with the traits parameter, up to a maximum of 8.
Authorization
BearerAuth 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.
In: header
Query Parameters
The 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 <= valueFilter the list to the user matching a specific external trait.
Common values: email, tracking_id, or any custom trait.
match_type and match_value must be supplied together. Providing
one without the other (or with a blank value) returns 400 with code
missing_match_parameter — it is never treated as an unfiltered
list request.
The exact value to match for the specified match_type. Required
whenever match_type is provided, and must be non-blank.
Sort field.
"score"Value in
- "score"
- "name"
- "last_seen"
- "first_seen"
- "activation_rate"
- "score_change"
- "frequency"
Sort order.
"desc"Value in
- "asc"
- "desc"
Maximum number of results to return.
1 <= value <= 10020Number of results to skip for pagination.
0 <= value0When true, only return users with recent activity.
_meta.total_count reflects the filtered set, so it can be paged
against directly.
falseFilter users by membership in a user-scoped segment in this
workspace. Returns 400 with code invalid_segment_scope if the
segment is account-scoped.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v2/users?workspace_id=1"{ "data": [ { "id": "string", "tracking_id": "string", "email": "string", "name": "string", "display_name": "string", "metrics": { "engagement_score": 0, "raw_score": 0.1, "score_change": 0.1, "activation_rate": 0, "first_seen": "2019-08-24", "last_seen": "2019-08-24", "score_yesterday": 0, "score_last_period": 0, "overall_scored_events": 0, "recently_scored_events": 0 }, "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": { "total_count": 0, "returned_count": 0, "limit": 0, "offset": 0, "workspace_id": 0, "product_id": 0 }, "_links": { "property1": { "href": "string" }, "property2": { "href": "string" } }}Authorization
BearerAuth 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.
In: header
Path Parameters
The internal Accoil user ID.
Query Parameters
The 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 <= valueComma-separated list of optional data blocks to include.
traits: requirestraitsquery param listing trait namessegments: segment membership
Comma-separated list of trait names to include when expand=traits
is specified. Maximum 8 traits.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v2/users/0?workspace_id=1"{ "data": { "id": "string", "tracking_id": "string", "email": "string", "name": "string", "display_name": "string", "metrics": { "engagement_score": 0, "raw_score": 0.1, "score_change": 0.1, "activation_rate": 0, "first_seen": "2019-08-24", "last_seen": "2019-08-24", "score_yesterday": 0, "score_last_period": 0, "overall_scored_events": 0, "recently_scored_events": 0 }, "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" }}