Jelliu API documentation

Computes a report over your call or contact data and returns it in data, synchronously. The shape of data depends on type, and data.type echoes it. Use GET /api/reports/types for the catalog. For raw rows instead of aggregates, use POST /api/exports.

date_from / date_to accept an ISO 8601 datetime (offsets allowed) or a YYYY-MM-DD date, which means midnight UTC at the start of that day. The range is inclusive on both ends and may not exceed 366 days. It is matched against the call’s (or contact’s) created_at.
campaign_ids filters roi_analysis and campaign_comparison. contact_funnel uses only the first id, and cost_per_call and agent_performance ignore it.
period and format are validated but change nothing; the response is always JSON.

How each report counts:

roi_analysis: counts only completed calls with a duration, so successfulCalls always equals totalCalls. Cost is minutes × Jelliu’s internal cost per minute. The human cost is minutes × an hourly human-agent rate ÷ 60.
campaign_comparison / agent_performance: successRate is the percentage of calls in the range with status completed. Rows are ranked by it, highest first. agent_performance credits each call to the agent of its campaign, so calls without a campaign are not counted.
cost_per_call: one point per UTC day with completed calls, oldest first. Days without calls are left out.
contact_funnel: contacts created in the range, grouped by status. The known stages (pending, called, converted, dnc) come first; any other status is appended after them.

Side effects. Read-only on your data. The request is written to the audit log as report.generate.

Idempotency. Safe to retry. Nothing is stored, and the same parameters return the same figures unless new data arrived.

Webhook events. Emits audit.log_recorded to webhooks subscribed to it. See Webhooks.

Access

Required scope: write (it is a POST). Human users need the owner, admin or member role; viewers and billing users are refused.
Rate limit: General API — 120 requests/min per workspace on Starter or with no active plan, 200 on Growth, 300 on Business, 600 on Enterprise. See Rate limits.
Plan: Requires the customReports plan feature. Every plan includes it today, including workspaces without an active plan, so this gate currently refuses nobody.

Computes a report over your call or contact data and returns it in `data`, synchronously. The shape of `data` depends on `type`, and `data.type` echoes it. Use `GET /api/reports/types` for the catalog. For raw rows instead of aggregates, use `POST /api/exports`. - `date_from` / `date_to` accept an ISO 8601 datetime (offsets allowed) or a `YYYY-MM-DD` date, which means midnight UTC at the start of that day. The range is inclusive on both ends and may not exceed 366 days. It is matched against the call's (or contact's) `created_at`. - `campaign_ids` filters `roi_analysis` and `campaign_comparison`. `contact_funnel` uses only the first id, and `cost_per_call` and `agent_performance` ignore it. - `period` and `format` are validated but change nothing; the response is always JSON. How each report counts: - `roi_analysis`: counts only `completed` calls with a duration, so `successfulCalls` always equals `totalCalls`. Cost is minutes × Jelliu's internal cost per minute. The human cost is minutes × an hourly human-agent rate ÷ 60. - `campaign_comparison` / `agent_performance`: `successRate` is the percentage of calls in the range with status `completed`. Rows are ranked by it, highest first. `agent_performance` credits each call to the agent of its campaign, so calls without a campaign are not counted. - `cost_per_call`: one point per UTC day with completed calls, oldest first. Days without calls are left out. - `contact_funnel`: contacts created in the range, grouped by status. The known stages (`pending`, `called`, `converted`, `dnc`) come first; any other status is appended after them. **Side effects.** Read-only on your data. The request is written to the audit log as `report.generate`. **Idempotency.** Safe to retry. Nothing is stored, and the same parameters return the same figures unless new data arrived. **Webhook events.** Emits `audit.log_recorded` to webhooks subscribed to it. See [Webhooks](/webhooks). **Access** - **Required scope:** `write` (it is a `POST`). Human users need the owner, admin or member role; viewers and billing users are refused. - **Rate limit:** General API — 120 requests/min per workspace on Starter or with no active plan, 200 on Growth, 300 on Business, 600 on Enterprise. See [Rate limits](/rate-limits). - **Plan:** Requires the `customReports` plan feature. Every plan includes it today, including workspaces without an active plan, so this gate currently refuses nobody.

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

Request

Unknown keys are ignored.

typeenumRequired

Which report to compute; it decides the shape of data. roi_analysis: cost, savings vs. human agents and ROI. campaign_comparison: campaigns ranked by success rate. cost_per_call: daily cost time series. agent_performance: agents ranked by success rate. contact_funnel: contacts by status and conversion rate.

Which report to compute; it decides the shape of `data`. `roi_analysis`: cost, savings vs. human agents and ROI. `campaign_comparison`: campaigns ranked by success rate. `cost_per_call`: daily cost time series. `agent_performance`: agents ranked by success rate. `contact_funnel`: contacts by status and conversion rate.

Allowed values:

periodenumRequired

Label for the range. Required and validated, but it does not change the computation; only date_from / date_to do. daily, weekly, monthly, quarterly and custom behave identically.

Allowed values:

date_fromstringRequired

Inclusive start. ISO 8601 datetime (offsets allowed) or YYYY-MM-DD (midnight UTC).

date_tostringRequired

Inclusive end. ISO 8601 datetime or YYYY-MM-DD (midnight UTC, so the day itself is excluded). At most 366 days after date_from.

campaign_idslist of stringsOptional

Restrict to these campaigns. Applied by roi_analysis and campaign_comparison. contact_funnel uses only the first id; the other types ignore it. Each item must be a UUID.

formatenumOptionalDefaults to json

Accepted for compatibility. The response is always JSON; pdf is not rendered.

Allowed values:

Response

The computed report. The shape of data depends on type.

dataobject

One of five report shapes, selected by type.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

date_from / date_to accept an ISO 8601 datetime (offsets allowed) or a YYYY-MM-DD date, which means midnight UTC at the start of that day. The range is inclusive on both ends and may not exceed 366 days. It is matched against the call’s (or contact’s) created_at.
campaign_ids filters roi_analysis and campaign_comparison. contact_funnel uses only the first id, and cost_per_call and agent_performance ignore it.
period and format are validated but change nothing; the response is always JSON.

How each report counts:

roi_analysis: counts only completed calls with a duration, so successfulCalls always equals totalCalls. Cost is minutes × Jelliu’s internal cost per minute. The human cost is minutes × an hourly human-agent rate ÷ 60.
campaign_comparison / agent_performance: successRate is the percentage of calls in the range with status completed. Rows are ranked by it, highest first. agent_performance credits each call to the agent of its campaign, so calls without a campaign are not counted.
cost_per_call: one point per UTC day with completed calls, oldest first. Days without calls are left out.
contact_funnel: contacts created in the range, grouped by status. The known stages (pending, called, converted, dnc) come first; any other status is appended after them.

Side effects. Read-only on your data. The request is written to the audit log as report.generate.

Idempotency. Safe to retry. Nothing is stored, and the same parameters return the same figures unless new data arrived.

Webhook events. Emits audit.log_recorded to webhooks subscribed to it. See Webhooks.

Access

Required scope: write (it is a POST). Human users need the owner, admin or member role; viewers and billing users are refused.
Rate limit: General API — 120 requests/min per workspace on Starter or with no active plan, 200 on Growth, 300 on Business, 600 on Enterprise. See Rate limits.
Plan: Requires the customReports plan feature. Every plan includes it today, including workspaces without an active plan, so this gate currently refuses nobody.