AccoilAccoil Developer Docs
Accoil API

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.

GET
/v2/accounts

Authorization

BearerAuth
AuthorizationBearer <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_key used for sending (ingesting) event data into Accoil.

In: header

Query Parameters

workspace_id*integer

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).

Range1 <= value
sort?string

Sort field.

Default"score"

Value in

  • "score"
  • "name"
  • "last_seen"
  • "first_seen"
  • "activation_rate"
  • "score_change"
  • "active_users"
  • "total_users"
  • "frequency"
order?string

Sort order.

Default"desc"

Value in

  • "asc"
  • "desc"
limit?integer

Maximum number of results to return.

Range1 <= value <= 100
Default20
offset?integer

Number of results to skip for pagination.

Range0 <= value
Default0
segment_id?integer

Filter 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.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.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"    }  }}
GET
/v2/accounts/{id}

Authorization

BearerAuth
AuthorizationBearer <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_key used for sending (ingesting) event data into Accoil.

In: header

Path Parameters

id*integer

The internal Accoil account ID.

Query Parameters

workspace_id*integer

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).

Range1 <= value
expand?string

Comma-separated list of optional data blocks to include.

  • insights: AI-generated account health analysis
  • traits: account attributes and custom properties
  • segments: segment memberships

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.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"  }}

Workspaces

List and retrieve the scoring workspaces your token can access.

Users

List users in a workspace and retrieve full user detail.