Call Ingest API

Send calls from your dialer, meeting tool or call export into Zime. Post each call with its transcript, a link to its recording, or both. Zime adds it to the rep's calls, builds its summary and insights, and maps it to a CRM deal.

https://nodejs-overhaul-prod.zime.ai

Before you start

• An ingest key. A company admin generates it in Zime. It is separate from your REST API key: it can send calls and check their status, and it cannot read calls, transcripts or insights.
• A source. Zime registers a source name for each system that sends calls, such as your dialer, sets its call type (dialer or meeting) and its rules with you, and turns it on. Until then the API answers 422 unknown_source.
• Your reps in Zime. Every rep on your calls must be an active Zime user in your company. Zime matches them by email.

Get your ingest key

curl -G 'https://nodejs-overhaul-prod.zime.ai/api/v1/calls/ingest' \
  -H 'X-API-Key: YOUR_INGEST_KEY' \
  --data-urlencode 'status=failed'

{
  "source": "your_source",
  "external_call_id": "call-0001",
  "started_at": "2026-10-19T09:43:35Z",
  "ended_at": "2026-10-19T09:48:35Z",
  "disposition": "Meeting Set",
  "rep": { "email": "rep@yourcompany.com", "name": "Riley Rep" },
  "participants": [
    { "role": "prospect", "name": "Pat Prospect", "email": "pat@example.com", "phone": "+14155550123" }
  ],
  "transcript": {
    "format": "segments",
    "segments": [
      { "speaker_role": "rep", "speaker_name": "Riley Rep", "start_seconds": 0, "text": "Hi Pat, thanks for taking the call." },
      { "speaker_role": "prospect", "speaker_name": "Pat Prospect", "start_seconds": 4, "end_seconds": 9, "text": "Sure, I have a few minutes." }
    ]
  }
}

curl -X POST 'https://nodejs-overhaul-prod.zime.ai/api/v1/calls/ingest' \
  -H 'X-API-Key: YOUR_INGEST_KEY' \
  -H 'Content-Type: application/json' \
  --data @call.json

"recording": { "audio_url": "https://storage.example.com/calls/call-0001.mp3?signature=..." }

{
  "ingest_id": 1042,
  "external_call_id": "call-0001",
  "status": "queued",
  "received_at": "2026-10-19T09:50:02.000Z"
}

{
  "ingest_id": 1043,
  "external_call_id": "call-0002",
  "status": "skipped",
  "reason": "rule:min_duration_seconds"
}

{
  "ingest_id": 1042,
  "external_call_id": "call-0001",
  "status": "completed",
  "duplicate": true
}

curl 'https://nodejs-overhaul-prod.zime.ai/api/v1/calls/ingest/your_source/call-0001' \
  -H 'X-API-Key: YOUR_INGEST_KEY'

{
  "ingest_id": 1042,
  "source": "your_source",
  "external_call_id": "call-0001",
  "call_type": "dialer",
  "status": "completed",
  "zime_call_id": 212322,
  "started_at": "2026-10-19T09:43:35.000Z",
  "received_at": "2026-10-19T09:50:02.000Z",
  "processed_at": "2026-10-19T09:50:11.000Z"
}

curl -G 'https://nodejs-overhaul-prod.zime.ai/api/v1/calls/ingest' \
  -H 'X-API-Key: YOUR_INGEST_KEY' \
  --data-urlencode 'source=your_source' \
  --data-urlencode 'status=failed' \
  --data-urlencode 'start-date=2026-10-01' \
  --data-urlencode 'end-date=2026-10-31'

{
  "data": [
    {
      "ingest_id": 1044,
      "source": "your_source",
      "external_call_id": "call-0003",
      "call_type": "dialer",
      "status": "failed",
      "error": "Recording fetch got status 404",
      "zime_call_id": 212327,
      "recording_status": "failed",
      "started_at": "2026-10-20T14:02:00.000Z",
      "received_at": "2026-10-20T14:10:41.000Z",
      "processed_at": "2026-10-20T14:11:03.000Z"
    }
  ],
  "pagination": {
    "page_size": 100,
    "returned_count": 1,
    "next_cursor": null,
    "has_more": false
  }
}

Errors

Errors return an error code. A 400 also lists each field that failed and why:

{
  "error": "invalid_payload",
  "errors": [
    { "field": "started_at", "message": "started_at must be ISO 8601 with a zone, for example 2026-10-19T09:43:35Z" }
  ]
}

A call refused with a 4xx error is not stored, so you can fix it and send it again as a new call.

Limits

What happens after you send a call

1. Checked. Zime validates the body, the source and the rep, then applies your source's rules. A call the rules drop is answered skipped and its content is not stored.
2. Queued. Every other new call is answered 202 with status: queued.
3. Processed. In the background Zime creates the call, stores your transcript or downloads and transcribes your recording, and moves the status to completed. The worker picks up queued calls every 30 seconds, up to 5 at a time. Measured in production, a call with a transcript reached completed 9 to 24 seconds after it was sent, and a recording-only call 1 to 3 minutes; these are measured times, not a guarantee. A call that cannot be added ends as failed with an error; resend it once the cause is fixed.
4. Analysed. Zime matches the call to your checklists, builds the summary and insights (within 3 minutes in our tests), and maps the call to a CRM deal about 10 minutes after it is created. The call shows on the rep's Calls page; tick Dialer in the filters to see dialer calls.

Nooks exports in Amazon S3

If you use Nooks and export transcripts to Amazon S3, Zime has a Python sender script that reads those exports and sends each call to this API. It runs in your own AWS account, so your bucket access stays with you. Zime shares the sender script and the setup steps over a secure channel. Your company admin generates the ingest key in Zime under Admin, then APIs; keep it in your secret store and never send it by email or chat in plain text.

Settings

Run it

• AWS permissions, for the Lambda role or the credentials the shell uses: s3:ListBucket on the export bucket and s3:GetObject on its objects, always. With the watermark in the export bucket, add s3:PutObject on the watermark key. With the watermark in a separate bucket, add s3:ListBucket on that bucket, and s3:GetObject and s3:PutObject on the watermark key. s3:ListBucket on the watermark's bucket is required: without it every scheduled run fails before sending anything. A watermark in a local file needs no S3 permission.
• On AWS Lambda: handler nooks_ingest.lambda_handler, timeout 900 seconds, memory 512 MB. Always run it on a schedule, every 15 minutes or once a day after 09:30 UTC: the scheduled run keeps a watermark and stops on a refused key or lasting errors without moving it. An s3:ObjectCreated:* trigger can run beside it for faster delivery, but not alone, because a call an event cannot send is dropped after Lambda's retries.
• Test first: python3 nooks_ingest.py --dry-run sends nothing and reports what it would send. Then send one call with --key and its object key.

What a run reports

A refused key (401, 403), an unknown source, or 429, 5xx, network or S3 read errors that outlast the retries stop the run. A scheduled run saves its watermark on the last call done, so the next run starts with the call that failed; on Lambda the invocation ends in an error, and from the command line the script exits with status 1. An S3 event that fails is retried by Lambda, twice by default, and then dropped; the scheduled run sends that call. A call Zime refuses for itself, such as rep_not_found, does not stop the run: it is logged, and the watermark moves past it. Zime stores nothing for a refused call, so after you fix the cause, resend it with --key and its object key, or resend its window: load the key, then run the scheduled mode once with START_DATE set to the day before the problem began and a watermark file that does not exist yet.

The script reads the key only from the environment. Never type the key into a command, because it would then be saved in the shell history. Load it in one of these ways; the commands below then run without the key.

1. Export it from your secret store.
2. In bash (run it in bash, e.g. start bash first), paste the key at the hidden prompt and press Enter:

read -rs ZIME_INGEST_KEY && export ZIME_INGEST_KEY

3. In any POSIX shell, such as sh or dash, paste the key at the Ingest key prompt and press Enter. The key is not shown on screen and is not saved in the history:

stty -echo; printf 'Ingest key: '; IFS= read -r ZIME_INGEST_KEY; stty echo; printf '\n'; export ZIME_INGEST_KEY

If you press Ctrl-C at the prompt, your typing stays hidden; type stty echo and press Enter to see it again.

NOOKS_BUCKET=<bucket> START_DATE=<YYYY-MM-DD> WATERMARK_URI=nooks_resend_watermark.json python3 nooks_ingest.py

Never point WATERMARK_URI at the watermark of your scheduled run: a run with an existing watermark starts from that watermark, not from START_DATE. Calls Zime already has answer duplicate.

Frequently asked questions