Developer guide

Feed data into Turnella automatically

Instead of exporting a spreadsheet from your phone system or help desk and uploading it by hand every week, you can have your tools send interval volumes straight into a workstream. Any system that can make an HTTPS request — a help desk, a telephony platform, a script, or an automation tool like Zapier or Make — can push data to a single endpoint.

1. Get an API key

Open Account, find the API keyssection, name a key (e.g. “Zendesk feed”), and click Create key. The key is shown once — copy it somewhere safe. Treat it like a password: anyone with it can write data to your account. Revoke a key any time from the same screen.

2. Find your workstream ID

Open the workstream you want to feed. Its ID is the code in the address bar after /app/ — for example, in /app/ws_abc123/data, the workstream ID is ws_abc123.

3. Send your numbers

Make a POST request to:

POST https://turnella.com/api/v1/observations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

The body lists one entry per interval. volume is the number of contacts in that interval; ahtSeconds (average handle time in seconds) is optional:

{
  "workstreamId": "ws_abc123",
  "observations": [
    { "intervalStart": "2026-07-01T09:00:00Z", "volume": 42, "ahtSeconds": 300 },
    { "intervalStart": "2026-07-01T09:30:00Z", "volume": 51, "ahtSeconds": 295 }
  ]
}

A complete example with curl:

curl -X POST https://turnella.com/api/v1/observations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workstreamId": "ws_abc123",
    "observations": [
      { "intervalStart": "2026-07-01T09:00:00Z", "volume": 42, "ahtSeconds": 300 }
    ]
  }'

A success returns:

{ "accepted": 1, "workstreamId": "ws_abc123", "storedAt": "2026-07-01T09:32:10.000Z" }

The one rule that matters

Send interval totals, not one request per ticket. Re-posting an interval replacesits volume — it does not add to it. A “new ticket → send volume: 1” automation would overwrite the interval with 1 on every ticket, and a 40-contact half hour would show as 1.

The right pattern is a scheduled job(e.g. nightly) that asks your system “how many contacts per interval?” and posts the totals in one batch. Step-by-step recipes for Zapier, Make, Power Automate and scheduled scripts are in the full guide: API & CRM feeds →

Good to know

Safe to resend.Posting the same interval again simply updates it — you won't get duplicates. This makes it safe to re-run a sync or backfill history.
Your data is never overwritten.Intervals you don't include are left exactly as they were.
It shows up on your next visit. Data you push lands in the cloud and appears in the app the next time you open it (or refresh). Then run the forecast as usual.
Timestamps are ISO 8601 (e.g. 2026-07-01T09:00:00Z). Use the start of each interval, on the same interval length your workstream uses.
Limits. Up to 10,000 intervals per request; up to 10 active keys per account.
Errors come back as { "error": "..." } with a 400 (bad request), 401 (bad/missing key), or 404 (workstream not found for that key).

Need a ready-made connector for a specific tool? Tell us at support@turnella.com — this endpoint is the foundation those connectors are built on.