REST API

The Accoil REST API lets you send user, account, and event data from any backend, script, or platform that can make HTTP requests. All requests are sent to a single base URL and processed asynchronously.

Base URL

https://in.accoil.com

Authentication

Accoil supports two authentication methods. v2 header authentication is recommended for all new integrations.

v2 Authentication (Recommended)

Send your API key in the Authorization header using the Basic scheme:

Authorization: Basic YOUR_API_KEY

v1 Authentication (Legacy)

Include your API key in the JSON request body as api_key. No Authorization header is required. The v1 endpoints use different paths and field naming conventions (snake_case). See the legacy v1 reference for details.

Finding Your API Key

Your API key is available in the Accoil dashboard under Account > General Settings. If you have multiple products configured, each product has its own API key.

Identifying Users

POST /v2/identify

The identify call creates or updates a user in Accoil and records user traits. You should send an identify call whenever a user signs up, logs in, or their profile information changes.

Request Body

Field	Type	Required	Description
`userId`	string	Yes	Unique identifier for the user. Use the same ID as in external platforms (e.g., HubSpot, Intercom).
`traits`	object	No	Key-value pairs describing the user (e.g., `email`, `name`, `createdAt`).
`groupId`	string	No	Associates the user with an account.
`timestamp`	string	No	ISO 8601 formatted date. Defaults to current UTC time if omitted.

Recommended Traits

Trait	Type	Purpose
`email`	string	Primary user identity, displayed in the Accoil UI
`name`	string	Display name in Accoil
`createdAt`	string (ISO 8601)	Enables user tenure tracking
`role`	string	Useful for filtering and segmentation

curl

curl -X POST https://in.accoil.com/v2/identify \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345",
    "groupId": "account_67890",
    "traits": {
      "email": "alex@example.com",
      "name": "Alex Keener",
      "createdAt": "2024-08-01T12:00:00Z",
      "role": "admin"
    }
  }'

JavaScript (fetch)

await fetch("https://in.accoil.com/v2/identify", {
  method: "POST",
  headers: {
    "Authorization": "Basic YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userId: "user_12345",
    groupId: "account_67890",
    traits: {
      email: "alex@example.com",
      name: "Alex Keener",
      createdAt: "2024-08-01T12:00:00Z",
      role: "admin",
    },
  }),
});

Python (requests)

import requests

requests.post(
    "https://in.accoil.com/v2/identify",
    headers={
        "Authorization": "Basic YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "userId": "user_12345",
        "groupId": "account_67890",
        "traits": {
            "email": "alex@example.com",
            "name": "Alex Keener",
            "createdAt": "2024-08-01T12:00:00Z",
            "role": "admin",
        },
    },
)

Identifying Accounts

POST /v2/group

The group call creates or updates an account (group) in Accoil and optionally links a user to it. Use this to track organization-level attributes such as plan, MRR, and status.

Request Body

Field	Type	Required	Description
`groupId`	string	Yes	Unique identifier for the account. Use the same ID as in external systems (e.g., HubSpot, Intercom).
`traits`	object	No	Key-value pairs describing the account.
`userId`	string	No	Links a specific user to this account.
`timestamp`	string	No	ISO 8601 formatted date. Defaults to current UTC time if omitted.

Recommended Traits

Trait	Type	Purpose
`name`	string	Account name displayed in the Accoil UI
`createdAt`	string (ISO 8601)	Enables account tenure tracking
`status`	string	Account state (e.g., `free`, `trial`, `paid`)
`plan`	string	Subscription tier (e.g., `starter`, `pro`, `enterprise`)
`mrr`	integer	Monthly recurring revenue in cents (e.g., `100000` for $1,000)

curl

curl -X POST https://in.accoil.com/v2/group \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "account_67890",
    "userId": "user_12345",
    "traits": {
      "name": "Acme Corp",
      "createdAt": "2023-01-15T12:00:00Z",
      "status": "paid",
      "plan": "enterprise",
      "mrr": 100000
    }
  }'

JavaScript (fetch)

await fetch("https://in.accoil.com/v2/group", {
  method: "POST",
  headers: {
    "Authorization": "Basic YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    groupId: "account_67890",
    userId: "user_12345",
    traits: {
      name: "Acme Corp",
      createdAt: "2023-01-15T12:00:00Z",
      status: "paid",
      plan: "enterprise",
      mrr: 100000,
    },
  }),
});

Python (requests)

import requests

requests.post(
    "https://in.accoil.com/v2/group",
    headers={
        "Authorization": "Basic YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "groupId": "account_67890",
        "userId": "user_12345",
        "traits": {
            "name": "Acme Corp",
            "createdAt": "2023-01-15T12:00:00Z",
            "status": "paid",
            "plan": "enterprise",
            "mrr": 100000,
        },
    },
)

Tracking Events

POST /v2/track

The track call records a user action. Accoil accepts only the event name -- no event properties are stored. Use clear, descriptive event names following a Noun-Verb format (e.g., Report_Created, Dashboard_Viewed).

Request Body

Field	Type	Required	Description
`userId`	string	Yes	The identifier of the user who performed the event. Must match a previously identified user.
`event`	string	Yes	The name of the event.
`timestamp`	string	No	ISO 8601 formatted date. Defaults to current UTC time if omitted.

Event Properties Not Supported

Accoil does not accept or store event properties. Only the event name and timestamp are used for engagement scoring. Send user and account attributes via identify and group calls instead.

curl

curl -X POST https://in.accoil.com/v2/track \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345",
    "event": "Report_Created"
  }'

JavaScript (fetch)

await fetch("https://in.accoil.com/v2/track", {
  method: "POST",
  headers: {
    "Authorization": "Basic YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userId: "user_12345",
    event: "Report_Created",
  }),
});

Python (requests)

import requests

requests.post(
    "https://in.accoil.com/v2/track",
    headers={
        "Authorization": "Basic YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "userId": "user_12345",
        "event": "Report_Created",
    },
)

Response Handling

All endpoints return 202 Accepted on success. This indicates the request has been received and will be processed asynchronously in the background.

Status Code	Meaning
`202 Accepted`	Request received and queued for processing.
`413 Payload Too Large`	The request body exceeds the allowed size.
`503 Service Unavailable`	The service is temporarily unavailable. Retry with exponential backoff.

Important Notes on Error Handling

A 202 response confirms the request was received, but does not guarantee it will be processed successfully. If your API key is invalid, the request may be accepted but silently dropped during async processing.
If events are not appearing in the Accoil dashboard, verify that your Authorization header is correctly formatted as Basic YOUR_API_KEY.
Implement retry logic with exponential backoff for 503 responses.
Ensure all string fields (userId, groupId, event) are non-empty strings.

v1 Legacy Endpoints

The v1 API uses different endpoint paths and passes the API key in the request body instead of a header. These endpoints remain functional but are not recommended for new integrations.

v2 Endpoint	v1 Equivalent
`POST /v2/identify`	`POST /v1/users`
`POST /v2/group`	`POST /v1/groups`
`POST /v2/track`	`POST /v1/events`

Key differences in v1:

Authentication via api_key field in the JSON body (no Authorization header).
Field names use snake_case (user_id, group_id) instead of camelCase.
Timestamps are Unix timestamps in milliseconds (integer) instead of ISO 8601 strings.

Full API Reference

For the complete OpenAPI specification including request schemas and all fields, see the API Reference.

REST API

On this page