Bulk ingestion

Past 10,000 records, don’t send an array. Upload a record set — a manifest you push records into in chunks, seal, and then hand to a trigger by id. The records never travel inside the trigger request, so a 1,000,000-row upload is a hundred small POSTs and one trigger call that returns immediately.

When to use it

Volume	Path
Up to 10,000 records	Inline `records` array on the trigger — see Trigger with records
10,001 up to 5,000,000 records	A record set, triggered with `record_set_id`

Inline is simpler and stays the right answer for small loads. Everything on this page is for the case where the array would be too big to send at all.

The three-step flow

POST /data/record-sets — create the manifest. Declares chunk_size and returns the record set’s id.
POST /data/record-sets/{record_set_id}/records — once per chunk, until every record has been sent.
POST /data/record-sets/{record_set_id}/seal — declare expected_count. The API checks it against what it actually staged.

Then trigger the flow with record_set_id. All three upload steps require admin access; reading a record set’s status does not.

There is no GET /data/record-sets list endpoint. A record set is a short-lived upload handle whose id you already hold — read one with GET /data/record-sets/{record_set_id} to check progress.

Step 1 — Create the record set

chunk_size is fixed for the whole upload and defaults to the largest chunk the API accepts (10,000). metadata is free-form and comes back on every read.

curl -X POST https://api.getdialed.ai/v1/data/record-sets \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chunk_size": 10000,
    "metadata": {"campaign": "spring-2026", "source": "crm-export.csv"}
  }'

import os
import httpx

client = httpx.Client(
    base_url="https://api.getdialed.ai/v1/",
    headers={"X-API-Key": os.environ["API_KEY"]},
)

res = client.post(
    "data/record-sets",
    json={
        "chunk_size": 10000,
        "metadata": {"campaign": "spring-2026", "source": "crm-export.csv"},
    },
)
record_set = res.json()
record_set_id = record_set["id"]
chunk_size = record_set["chunk_size"]

const res = await fetch("https://api.getdialed.ai/v1/data/record-sets", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    chunk_size: 10000,
    metadata: { campaign: "spring-2026", source: "crm-export.csv" },
  }),
});
const { id: recordSetId, chunk_size: chunkSize } = await res.json();

Two rules for the Python client, and both bite silently. The base_url must end with a slash and each relative path must start without one — a leading slash makes httpx discard the /v1 base entirely. The relative path must also carry its group segment: data/record-sets, not record-sets. Record sets live in the data group while definitions, batches and jobs live in flows, so a path missing its group returns 404 on an endpoint that plainly exists.

The 201 response is the manifest:

{
  "id": "rs_0123456789abcdef",
  "status": "open",
  "chunk_size": 10000,
  "received_count": 0,
  "chunk_count": 0,
  "expected_count": null,
  "content_hash": null,
  "batch_id": null,
  "metadata": {"campaign": "spring-2026", "source": "crm-export.csv"},
  "created_at": "2026-07-27T12:00:00Z",
  "updated_at": "2026-07-27T12:00:00Z",
  "sealed_at": null,
  "consumed_at": null,
  "staging_expires_at": "2026-08-03T12:00:00Z"
}

status moves open → sealed → consumed. Only an open record set accepts chunks.

Reading CSV files

Parsing is client-side in this release. Chunk bodies are JSON only — there is no text/csv upload. You read the file, turn each row into an object, and POST batches of those objects. Given a CSV like this:

first_name,last_name,phone
Alice,Nguyen,+15555550100
Bob,Marsh,+15555550101
Carla,Diaz,+15555550102

each row becomes one object, and your flow reads its columns through {{input.first_name}}, {{input.last_name}} and {{input.phone}} — exactly as on the inline path. Combining several files into one upload works the same way: the manifest is the “combine files” primitive. Push each file’s rows as additional chunks into the same record set, keeping a single running chunk index across all of them.

import csv

def rows(paths):
    """Yield one dict per row across several CSVs, header-mapped."""
    for path in paths:
        with open(path, newline="") as fh:
            yield from csv.DictReader(fh)

def chunks(iterable, size):
    batch = []
    for item in iterable:
        batch.append(item)
        if len(batch) == size:
            yield batch
            batch = []
    if batch:
        yield batch

Step 2 — Push the chunks

Each chunk carries a client-assigned chunk_index, starting at 0, and the chunk’s records in dial order:

{
  "chunk_index": 0,
  "records": [
    {"first_name": "Alice", "last_name": "Nguyen", "phone": "+15555550100"},
    {"first_name": "Bob", "last_name": "Marsh", "phone": "+15555550101"},
    {"first_name": "Carla", "last_name": "Diaz", "phone": "+15555550102"}
  ]
}

Chunks may be sent in any order. Re-POSTing the same chunk_index with the same rows is a safe no-op: the response reports replay: true and the record set’s counters do not move. That is what makes an interrupted upload recoverable — on any error you do not know whether the chunk landed, so you simply send it again. A row’s position in the set is chunk_index * chunk_size + offset, where offset is its position within the chunk. Keep chunk_size constant for every chunk except the final one. A short chunk in the middle is allowed — it just leaves a harmless gap in the row numbering, because rows are processed by range and sealing validates the totals.

Pacing and `429`

The chunk endpoint has its own rate limit, separate from (and far above) the standard per-principal limit. Even so, honour Retry-After on a 429 and back off — behind multiple API replicas this is the difference between an upload that completes and one that fails intermittently.

import time
import httpx

def post_chunk(client, record_set_id, chunk_index, records, attempts=6):
    """POST one chunk, honouring Retry-After on 429 and retrying safely.

    Retrying is safe at any point: the same chunk_index with the same rows is
    recognised as a replay and inserts nothing.
    """
    backoff = 1.0
    for attempt in range(attempts):
        res = client.post(
            f"data/record-sets/{record_set_id}/records",
            json={"chunk_index": chunk_index, "records": records},
        )
        if res.status_code == 429:
            wait = float(res.headers.get("Retry-After", backoff))
            time.sleep(wait)
            backoff = min(backoff * 2, 60)
            continue
        res.raise_for_status()
        return res.json()
    raise RuntimeError(f"chunk {chunk_index} did not complete after {attempts} attempts")


total = 0
for index, batch in enumerate(chunks(rows(["a.csv", "b.csv"]), chunk_size)):
    body = post_chunk(client, record_set_id, index, batch)
    total = body["received_count"]
    print(f"chunk {index}: +{body['inserted']} replay={body['replay']} total={total}")

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function postChunk(recordSetId, chunkIndex, records, attempts = 6) {
  let backoff = 1000;
  for (let attempt = 0; attempt < attempts; attempt++) {
    const res = await fetch(
      `https://api.getdialed.ai/v1/data/record-sets/${recordSetId}/records`,
      {
        method: "POST",
        headers: {
          "X-API-Key": process.env.API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ chunk_index: chunkIndex, records }),
      },
    );
    if (res.status === 429) {
      const retryAfter = res.headers.get("Retry-After");
      await sleep(retryAfter ? Number(retryAfter) * 1000 : backoff);
      backoff = Math.min(backoff * 2, 60000);
      continue;
    }
    if (!res.ok) throw new Error(`chunk ${chunkIndex} failed: ${res.status}`);
    return res.json();
  }
  throw new Error(`chunk ${chunkIndex} did not complete`);
}

Each chunk responds with its own outcome:

{
  "record_set_id": "rs_0123456789abcdef",
  "chunk_index": 0,
  "records_received": 10000,
  "inserted": 10000,
  "replay": false,
  "received_count": 10000
}

received_count is the running total across the whole record set. The value from your last chunk is what you pass as expected_count when you seal.

Status	Meaning
`200`	Chunk staged, or recognised as a replay (`replay: true`)
`404`	Unknown record set — also returned for another tenant’s record set, never `403`
`409`	The record set is no longer `open`, so it cannot accept records
`413`	Request body too large — split the upload into more chunks
`422`	More records than the manifest’s `chunk_size`, or a record over the per-record size limit
`429`	Chunk rate limit exceeded — back off per `Retry-After`

An oversized-record 422 names the offending row index, never the row itself. No error body ever echoes your record data back.

Step 3 — Seal

expected_count is the total number of records you sent. The API compares it with the number it actually staged and refuses the seal if they disagree — this is how a chunk that was silently lost in transit is caught, before anything is dialled. You don’t need the total up front, only at seal time, which is what lets you stream several files in without counting them first.

curl -X POST "https://api.getdialed.ai/v1/data/record-sets/rs_0123456789abcdef/seal" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expected_count": 1000000}'

res = client.post(
    f"data/record-sets/{record_set_id}/seal",
    json={"expected_count": total},
)
res.raise_for_status()
sealed = res.json()

{
  "id": "rs_0123456789abcdef",
  "status": "sealed",
  "chunk_size": 10000,
  "received_count": 1000000,
  "chunk_count": 100,
  "expected_count": 1000000,
  "content_hash": "9f2c4e1b7a35d80c6e4f1a92b3c7d5e08f6a1b2c3d4e5f60718293a4b5c6d7e8",
  "batch_id": null,
  "metadata": {"campaign": "spring-2026"},
  "created_at": "2026-07-27T12:00:00Z",
  "updated_at": "2026-07-27T12:04:31Z",
  "sealed_at": "2026-07-27T12:04:31Z",
  "consumed_at": null,
  "staging_expires_at": "2026-08-03T12:00:00Z"
}

A 409 on seal names both numbers — what you expected and what was staged — so a missing chunk is distinguishable from a duplicate seal. Re-sealing with the same expected_count returns the same result, so the call is safe to retry.

Step 4 — Trigger the flow

Pass record_set_id where you would have passed records:

curl -X POST "https://api.getdialed.ai/v1/flows/definitions/def_a1b2c3d4/trigger" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "crm_export",
    "record_set_id": "rs_0123456789abcdef"
  }'

res = client.post(
    "flows/definitions/def_a1b2c3d4/trigger",
    json={"source": "crm_export", "record_set_id": record_set_id},
)
batch = res.json()

{
  "batch_id": "batch_55667788",
  "definition_id": "def_a1b2c3d4",
  "status": "pending",
  "deduplicated": false,
  "estimate": {
    "bucket": "Upload",
    "records": 1000000,
    "calls": 20,
    "max_records_per_call": 50000,
    "day_remaining_calls": 1100,
    "pct_of_remaining_day": 1.8,
    "queued_estimated_calls": 0,
    "spills_past_day_cap": false,
    "warning": null,
    "as_of": "2026-08-14T18:00:00Z"
  }
}

records and record_set_id are mutually exclusive — sending both is a 422.

What the `estimate` tells you

The response carries what this upload will cost against your Domain’s provider budget: calls is how many provider calls the rows come to at max_records_per_call, and pct_of_remaining_day is that as a share of today’s remaining budget. It is null when the flow does not dispatch through a rate-limited platform budget. spills_past_day_cap: true means the work needs more calls than today’s remaining budget — and it is informational, never a refusal. The trigger was accepted; the overflow is delivered at your Domain’s permitted rate and continues into the following day, which is how the platform is meant to absorb a large upload. Note that the verdict also counts work already queued ahead of you, so a modest upload can read as a small percentage and still be flagged as spilling. If you would rather it did not run, the brake is cancelling the batch — not a blocked trigger. To see the figures before committing, call POST /platforms/five9/domains/{tenancy_id}/estimate with a record_set_id or a record_count; it commits nothing and uses the same estimator. That dry run is also how you price a batch started by a schedule, a webhook or an event, since those paths have no response for an inline estimate to ride on. Quota and progress is the full model.

The definition must use batched delivery. A definition with per-record (direct-delivery) steps refuses a record set with 422, pointing you back at the inline records path (up to 10,000), which works today. There is no silent coercion between the two delivery modes.

A record set is single-use — exactly one trigger consumes it. The two 409s here are distinct and mean different things:

Status	Meaning
`404`	Unknown record set, or another tenant’s — never `403`
`409`	The record set is still `open` — seal it first
`409`	The record set is already `consumed` — a trigger has claimed it
`422`	Both `records` and `record_set_id` supplied, or the definition uses per-record steps

Idempotency

Identical content re-submitted within 7 days is not ingested twice. The second call returns 200 with deduplicated: true and the original batch_id:

{
  "batch_id": "batch_55667788",
  "definition_id": "def_a1b2c3d4",
  "status": "queued",
  "deduplicated": true
}

A deduplicated submission is a 200, not an error. A client that treats any non-fresh response as a failure will mis-handle it. The batch_id you get back is a usable handle to the original batch — poll it as normal.

Content identity is computed by the server from the sealed records and the definition, so uploading the same rows against a different definition is not a duplicate. To deliberately re-run identical content — a genuine second dial of the same list — supply an Idempotency-Key header on the trigger, which forces a new batch:

curl -X POST "https://api.getdialed.ai/v1/flows/definitions/def_a1b2c3d4/trigger" \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: redial-2026-07-27-morning" \
  -H "Content-Type: application/json" \
  -d '{"record_set_id": "rs_fedcba9876543210"}'

The key must be non-blank and at most 255 characters. It applies to the record-set path only and is ignored on the inline records path. After 7 days the window closes and identical content is accepted again without a key.

What happens next

The trigger returns as soon as the batch is minted — the per-record work happens after the response, which is why the call is fast regardless of record count. Every uploaded row becomes one job and one execution. The batch is pending while its rows are being bound, and reaches queued once every row has a job and an execution. Watch it with GET /flows/batches/{batch_id}.

Nothing is sent to your platform during ingestion. Staging and sealing write nothing outbound — dispatch begins only after you trigger, and from queued it is paced against your Domain’s rate budget rather than fired all at once. Uploading is safe to do ahead of time.

Read the individual rows with GET /flows/jobs?batch_id=<batch_id>, exactly as for an inline trigger.

Step 5 — Watch the outcomes

Ingestion is only half the story. As rows are delivered, your platform answers per row, and each row ends at that answer: accepted, rejected, unprocessed (never sent, because you cancelled) or unresolved (the outcome could not be determined). Import outcomes is the full model; the short version is what you need here. The batch keeps a running count of where its rows stand — total, queued, dispatched, accepted, rejected, unprocessed, unresolved and parked — and they always sum to total, so nothing can quietly vanish mid-import. The full breakdown arrives with the batch’s terminal frame on GET /flows/batches/{batch_id}/stream; while the import is running, list rows by status to see what is in each state:

curl "https://api.getdialed.ai/v1/flows/jobs?batch_id=batch_55667788&status=rejected" \
  -H "X-API-Key: $API_KEY"

Where the batch lands says what happened overall:

Terminal state	Meaning
`completed`	Everything the platform answered for was accepted.
`completed_with_errors`	Mostly worked — some rows rejected or unresolved, at least one accepted.
`failed`	Nothing was accepted. Almost always one structural mistake: the wrong list, a bad column mapping, a header that did not match.
`cancelled`	You stopped it.

To turn the refused slice into a corrected re-upload, see Export failed rows.

Stopping a bad upload

POST /flows/batches/{batch_id}/cancel stops all future sends. Any key for your own organization can do it — it is the brake for your own bad upload, not an admin operation. Cancelling does not rewrite the past: records already handed to your platform are not recalled, and their results are still collected, so the final counts tell you exactly what got through before you stopped it. Everything not yet sent settles as unprocessed, with nothing left in limbo — on a large batch those counts land a few seconds after the response rather than inside it, because settling a million rows is real work and the call returns as soon as the sends have stopped. A batch that has already finished returns 409.

Releasing held work

When a send goes out and no confirmation comes back, those records are held rather than resent — an automatic retry could dial the same person twice. They show up as parked in the counters and as needs_reconcile rows. POST /flows/batches/{batch_id}/requeue is how a person releases that held work once they have decided it is safe. It never runs automatically, and held work waits indefinitely until someone asks:

curl -X POST "https://api.getdialed.ai/v1/flows/batches/batch_55667788/requeue" \
  -H "X-API-Key: $API_KEY"

{ "requeued": 2, "rows": 41823, "items": ["dq_9f2c1a4b", "dq_9f2c1a4c"] }

Requeueing the same batch again is safe — the second call reports requeued: 0 because nothing is left held. Two refusals are both 409:

The batch was cancelled (or has otherwise settled). Cancel stops all future sends, and a re-drive is unambiguously a future send.
Held work was sent in the same provider call as another batch’s records — which the platform does deliberately, to use your provider’s budget well. The whole request is refused and the response names the other batches, because releasing it would re-send records outside the batch you asked about. Nothing is requeued; the decision is yours.

Retention

What	Reclaimed when
An uploaded row (its job)	30 days after the job reaches a terminal state, or your account’s configured retention
An unsealed or never-triggered record set, and its staged rows	Automatically, 7 days after the record set was created

The second row is the important one for abandoned uploads: a record set you create and never trigger does not sit around holding contact data indefinitely.

Changing an account’s retention affects future batches only. Rows already staged keep the retention that was in force when their batch was created.

Limits

Limit	Value
Inline `records` per trigger	10,000
Records per chunk	10,000
Records per record set	5,000,000
Per-record size	8 KB
Chunk request body	16 MB

Records per chunk and chunk body size bind independently — at roughly 300 bytes per record the 16 MB body ceiling is reached well above the 10,000-record chunk cap, so the record count is normally the binding limit.

Next steps

Trigger with records

The inline path for loads up to 10,000 records.

Import outcomes

What each row’s answer means, the counters, and where a batch settles.

Export failed rows

Turn the refused slice into a corrected re-upload.

Batches, jobs, and executions

Every status in the chain, including staged and queued.

Getting Started

Core Concepts

Building Flows

Triggers & Streaming

When to use it

The three-step flow

Step 1 — Create the record set

Reading CSV files

Step 2 — Push the chunks

Pacing and `429`

Step 3 — Seal

Step 4 — Trigger the flow

What the `estimate` tells you

Idempotency

What happens next

Step 5 — Watch the outcomes

Stopping a bad upload

Releasing held work

Retention

Limits

Next steps

Trigger with records

Import outcomes

Export failed rows

Batches, jobs, and executions

​When to use it

​The three-step flow

​Step 1 — Create the record set

​Reading CSV files

​Step 2 — Push the chunks

​Pacing and 429

​Step 3 — Seal

​Step 4 — Trigger the flow

​What the estimate tells you

​Idempotency

​What happens next

​Step 5 — Watch the outcomes

​Stopping a bad upload

​Releasing held work

​Retention

​Limits

​Next steps

Trigger with records

Import outcomes

Export failed rows

Batches, jobs, and executions

When to use it

The three-step flow

Step 1 — Create the record set

Reading CSV files

Step 2 — Push the chunks

Pacing and `429`

Step 3 — Seal

Step 4 — Trigger the flow

What the `estimate` tells you

Idempotency

What happens next

Step 5 — Watch the outcomes

Stopping a bad upload

Releasing held work

Retention

Limits

Next steps