Get Accounts
Retrieve engagement metrics and insights for a customer account.
The Get Accounts endpoint returns comprehensive data for a customer account, including engagement scores, user activity summaries, AI-generated insights, segment memberships, and account traits.
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
The account trait to match against. Common values include:
domain: Company domain (e.g.,example.com)name: Account or organization nameintercom_id: Intercom company IDsalesforce_id: Salesforce account IDtracking_id: Your external tracking identifier- Or any custom trait you've recorded in Accoil
The exact value to match for the specified match_type.
For example, if match_type=domain, use match_value=example.com.
The internal Accoil account ID.
This is the fastest and most direct way to retrieve engagement data for an account.
You can find the account 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 id is 154
A comma-separated list of optional data blocks to include in the response.
Available options:
insights: AI-generated analysis of account health and engagement, with actionable recommendations.traits: All account attributes, including custom properties.segments: Segmentation and grouping information assigned to the account.
Example: expand=insights,traits
Cache Durations: The following cache/refresh periods apply to expand options
insights: Cached for up to 30 minutes (updates less frequently)traits: Cached for up to 15 minutessegments: Cached for up to 10 minutes (more likely to change often)
Note: Cache durations reflect how often data is refreshed on the server. If you poll the API more frequently than this, you may receive unchanged data.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://api.accoil.com/v1/accounts?workspace_id=string"{
"id": "456",
"name": "TechCorp Solutions",
"domain": "techcorp.com",
"tracking_id": "ext-12345",
"metrics": {
"engagement_score": 75.5,
"raw_score": 2150,
"owner_name": "Sarah Johnson",
"first_seen": "2023-01-15",
"last_seen": "2025-09-21",
"active_users": 12,
"activation_rate": 0.85,
"overall_scored_events": 4520,
"recently_scored_events": 380,
"scoring_profile_events": 95,
"total_people_count": 18,
"total_active_people_count": 12
},
"_expansions": {
"available": [
"traits",
"segments",
"insights"
],
"documentation": "Use expand=option1,option2 to include additional data",
"unknown_parameters": [],
"error": null
},
"_links": {
"self": {
"href": "/v1/accounts?id=456&workspace_id=13"
}
}
}{
"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"
]
}
}
}{
"error": {
"message": "Invalid or expired token",
"status": "unauthorized",
"code": "unauthorized"
}
}{
"error": {
"message": "Resource not found",
"status": "not_found",
"code": "not_found"
}
}