Skip to content

Creating links in bulk ​

The create endpoint always takes an array. One link is an array of one; the maximum is 50 per request.

Batching is also how you stay inside the rate limit: one call creating 50 links costs one write, where fifty calls cost fifty.

Why 50 ​

Each request writes every link plus a campaign counter in a single database transaction, and that transaction has a hard ceiling. Fifty is what fits with room for the counter.

Asking for 51 returns 413 BATCH_TOO_LARGE rather than silently truncating — chunk and repeat.

Matching results to your rows ​

Set reference on each entry — any string of your own, up to 128 characters. It is echoed back on both successes and failures, so you can match results to your rows without trusting array order.

json
{
  "links": [
    { "reference": "crm-8821", "metadata": { "customer_id": "acct_1" } },
    { "reference": "crm-8822", "metadata": { "customer_id": "acct_2" } }
  ]
}

index is returned too, but treat it as a convenience. reference is the one that survives you re-ordering, filtering or retrying a chunk.

One bad row does not fail the batch ​

By default a batch is best-effort. Valid entries are created, invalid ones are reported, and the response is 207 Multi-Status:

json
{
  "created": 1,
  "failed": 1,
  "items": [
    {
      "index": 0,
      "reference": "crm-8821",
      "status": "created",
      "link_id": "0f4c9a2e-1d3b-4a7c-9f21-8b6d5e4c3a10",
      "url": "https://survey.zefi.ai/fc5e5bc7-…/9d1f04b2-…?t=6699146b-…"
    },
    {
      "index": 1,
      "reference": "crm-8822",
      "status": "error",
      "error": {
        "code": "VALIDATION_FAILED",
        "detail": "metadata.author_email: author_email is not a valid email address"
      }
    }
  ]
}

207 is not a failure

Clients that treat anything outside 2xx as an error handle this correctly by accident; clients that check status === 201 do not, and will discard links that were really created. Check status per item.

Read created and failed for the totals, then walk items for the detail:

js
for (const item of items) {
  if (item.status === 'created') send(item.reference, item.url);
  else log.warn(item.reference, item.error.code, item.error.detail);
}

All-or-nothing ​

Send "on_error": "abort" for stricter behaviour: if any entry is invalid the request returns 400 and nothing is created.

json
{ "on_error": "abort", "links": [ … ] }

The default is "continue".

Use abort when a partial batch would be worse than no batch — a nightly job you would rather re-run clean than reconcile.

Retrying a chunk ​

Creating links is not idempotent and there is no idempotency key. A chunk that timed out may or may not have landed.

reference cannot be read back

It is echoed on the create response and nowhere else — it is not stored, so it does not appear on list or retrieve. You cannot reconcile a timed-out chunk by looking your references up afterwards.

What you can do is record the link_id values from every create response as you go, and compare created_at on the campaign's links against the moment the chunk was sent. Blind retries mint duplicates, and because each link is single-use, a duplicate is a second live link to the same person.

Zefi API v1