Jelliu API documentation

curl -G https://api.jelliu.co/api/analytics/overview \
     -H "Authorization: Bearer <token>" \
     -d agentId=2f2d8b4d-aa6f-41e0-9d3e-4d61e1b07a11 \
     -d campaignId=0f3c8b52-6d1a-4e2f-9b7c-4a5e6d7f8a90 \
     -d days=30 \
     -d direction=outbound

{
  "data": {
    "totalInteractions": 412,
    "completedInteractions": 356,
    "successes": 97,
    "successRate": 27.25,
    "avgDurationSeconds": 184,
    "avgSentiment": 0.34,
    "sentimentCallCount": 298,
    "totalAgents": 4,
    "totalCampaigns": 7,
    "activeCampaigns": 3,
    "totalContacts": 2850,
    "convertedContacts": 214,
    "dncContacts": 37,
    "channelBreakdown": [
      {
        "channel": "voice",
        "category": "sales",
        "interactions": 268,
        "completed": 231,
        "successes": 71,
        "successRate": 30.74,
        "successRateLabel": "conversionRate",
        "avgDurationSeconds": 201,
        "excludedMetrics": []
      },
      {
        "channel": "voice",
        "category": "scheduling",
        "interactions": 96,
        "completed": 88,
        "successes": 22,
        "successRate": 25,
        "successRateLabel": "bookingRate",
        "avgDurationSeconds": 142,
        "excludedMetrics": [
          "conversionRate"
        ]
      }
    ],
    "outcomeBreakdown": {
      "appointment_booked": 22,
      "follow_up_needed": 33,
      "info_provided": 17,
      "no_answer": 41,
      "rejected": 64,
      "sale_closed": 58,
      "voicemail": 29
    }
  }
}

Filters. days sets the window (rolling, ending now; missing or out-of-range values silently become 30). direction, campaignId and agentId narrow every call-activity number, including outcomeBreakdown and channelBreakdown. The entity counts (totalAgents, totalCampaigns, activeCampaigns, totalContacts, convertedContacts, dncContacts) are never windowed or filtered: they answer “how much do you have”, not “what happened”. timezone is accepted but not used (a value longer than 50 characters is still a 400).

What counts as a success. A completed call whose outcome is a success outcome of any campaign category (sale_closed, appointment_booked, info_provided, issue_resolved, callback_scheduled, payment_promised, …). For the stricter, category-specific definition of one campaign, use GET /api/analytics/campaigns/{campaignId}. channelBreakdown only includes calls that belong to a campaign; manual and unassigned inbound calls count in the totals only.

No data. Counts and successRate are 0; avgSentiment is null when no call in the window was scored (sentimentCallCount is 0). avgDurationSeconds is null when the breakdown has no voice campaign, and 0 when it does but no call completed.

Idempotency. Safe to retry: this is a read.

Consistency. Cached for 120 seconds, then served stale for up to 15 minutes while a background refresh runs. The response carries a weak ETag; send it back in If-None-Match to get 304 Not Modified when the numbers have not changed.

Access

Required scope: read. Signed-in users need the owner, admin, member or viewer role.
Rate limit: Analytics — 30 requests/min per workspace, in addition to the general API budget of your plan. See Rate limits.
Plan: Available on every plan. A workspace without an active subscription (active, trialing or past due) gets 403 BILLING_ERROR.

Returns the headline call KPIs for a rolling window: interactions, completed calls, successes, success rate, average duration, average sentiment (with its sample size), per-outcome counts and a breakdown by campaign channel and category, plus workspace-wide totals of agents, campaigns and contacts. **Filters.** `days` sets the window (rolling, ending now; missing or out-of-range values silently become 30). `direction`, `campaignId` and `agentId` narrow every call-activity number, including `outcomeBreakdown` and `channelBreakdown`. The entity counts (`totalAgents`, `totalCampaigns`, `activeCampaigns`, `totalContacts`, `convertedContacts`, `dncContacts`) are never windowed or filtered: they answer "how much do you have", not "what happened". `timezone` is accepted but not used (a value longer than 50 characters is still a `400`). **What counts as a success.** A completed call whose outcome is a success outcome of any campaign category (`sale_closed`, `appointment_booked`, `info_provided`, `issue_resolved`, `callback_scheduled`, `payment_promised`, ...). For the stricter, category-specific definition of one campaign, use `GET /api/analytics/campaigns/{campaignId}`. `channelBreakdown` only includes calls that belong to a campaign; manual and unassigned inbound calls count in the totals only. **No data.** Counts and `successRate` are `0`; `avgSentiment` is `null` when no call in the window was scored (`sentimentCallCount` is `0`). `avgDurationSeconds` is `null` when the breakdown has no voice campaign, and `0` when it does but no call completed. **Idempotency.** Safe to retry: this is a read. **Consistency.** Cached for 120 seconds, then served stale for up to 15 minutes while a background refresh runs. The response carries a weak `ETag`; send it back in `If-None-Match` to get `304 Not Modified` when the numbers have not changed. **Access** - **Required scope:** `read`. Signed-in users need the owner, admin, member or viewer role. - **Rate limit:** Analytics — 30 requests/min per workspace, in addition to the general API budget of your plan. See [Rate limits](/rate-limits). - **Plan:** Available on every plan. A workspace without an active subscription (active, trialing or past due) gets `403 BILLING_ERROR`.

Authentication

AuthorizationBearer

Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.

Scope	GET / HEAD	POST / PUT / PATCH / DELETE	Admin-only routes
`read`	Yes	No	No
`write`	Yes	Yes	No
`full`	Yes	Yes	Yes

Operations restricted to admins or owners reject keys without the full scope with 403, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See Authentication.

Workspace API key: `jl_` followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (**Settings → API Keys**) and sent as `Authorization: Bearer jl_...`. The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys. | Scope | GET / HEAD | POST / PUT / PATCH / DELETE | Admin-only routes | | --- | --- | --- | --- | | `read` | Yes | No | No | | `write` | Yes | Yes | No | | `full` | Yes | Yes | Yes | Operations restricted to admins or owners reject keys without the `full` scope with `403`, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See [Authentication](/authentication).

Query parameters

daysintegerOptional1-365Defaults to 30

Size of the reporting window in days, ending now. On most analytics routes a missing or out-of-range value falls back to 30 instead of being rejected; the operation says when it is strict.

directionenumOptionalDefaults to all

Which calls to count: inbound (calls the agent answered), outbound (calls the agent placed) or all (both).

Allowed values:

campaignIdstringOptionalformat: "uuid"

Scope every number to one campaign of the workspace. Omit it to aggregate across all campaigns and manual calls.

agentIdstringOptionalformat: "uuid"

Scope every number to one agent — the agent that served each call, so manual (campaign-less) calls count. Omit it to aggregate across agents.

Response headers

ETagstringOptional

Weak entity tag of the body. Send it in If-None-Match on the next request.

Response

The overview for the requested window.

dataobjectOptional

Headline call KPIs. Call-activity numbers (interactions, outcomes, sentiment, duration, channel breakdown) cover the requested window and filters. Entity counts (agents, campaigns, contacts) are workspace-wide totals that ignore the window and every filter. Counts and rates are 0 when there is no data; averages are null.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

Idempotency. Safe to retry: this is a read.

Access

Required scope: read. Signed-in users need the owner, admin, member or viewer role.
Rate limit: Analytics — 30 requests/min per workspace, in addition to the general API budget of your plan. See Rate limits.
Plan: Available on every plan. A workspace without an active subscription (active, trialing or past due) gets 403 BILLING_ERROR.