Skip to content

Send leads

Batch post

Send up to 500 aged or unsold leads in one request and reconcile one result per row.

On this page

Batch post is for aged or unsold inventory. Each item has the same shape as a single post. The response has one result per input row, in the same order, so you can always reconcile.

  1. Post the batch

    POST /v1/leads/batch takes 1 to 500 leads. Put is_test: true on any row to store it as a test lead, the same as on a single post.

    curl -X POST https://api.entrovox.com/v1/leads/batch \
      -H "Authorization: ApiKey $ENTROVOX_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "leads": [
          {
            "first_name": "Alex",
            "last_name": "Nguyen",
            "phone": "+14255550001",
            "external_id": "inv-1001"
          },
          {
            "first_name": "Sam",
            "last_name": "Ortiz",
            "phone": "+14255550002",
            "external_id": "inv-1002"
          }
        ]
      }'
  2. Reconcile every row

    200 always means the request was well formed. Partial success lives in items.

    200OK
    {
      "lead_source_id": "c222…",
      "created": 1,
      "replayed": 0,
      "rejected": 1,
      "items": [
        {
          "index": 0,
          "status": "created",
          "external_id": "inv-1001",
          "lead_id": "a111…",
          "status_url": "https://api.entrovox.com/v1/leads/a111…",
          "code": null,
          "message": null
        },
        {
          "index": 1,
          "status": "rejected",
          "external_id": "inv-1002",
          "lead_id": null,
          "status_url": null,
          "code": "DNC_BLOCKED",
          "message": "Phone is on the DNC list, so we did not create a lead. Remove it from your list or pause it; do not retry."
        }
      ]
    }

    Each item's status is one of created, replayed, conflict or rejected. The totals created, replayed and rejected are conveniences. rejected counts rows whose status is rejected or conflict.

  3. Resend only what is safe to resend

    A row with code PROVIDER_UNAVAILABLE created nothing. It is safe to resend in a new batch, and its external_id makes the resend idempotent. Every other rejected row is final for that payload: fix it (a VALIDATION_ERROR row is fixable) or resell it.

Choosing the campaign

The campaign for the whole batch comes from the envelope, next to leads.

lead_source_idstringOptional

The campaign id. Required for an unbound agency key: without it the batch answers 422 with param lead_source_id. A bound partner key may omit it, and naming a different campaign is 403 LEAD_SOURCE_NOT_ALLOWED. A campaign that is not in your organization is 404 LEAD_SOURCE_NOT_FOUND.

leadsarrayRequired

1 to 500 lead objects.

A row-level lead_source_id does not pick the batch's campaign. A row that repeats the batch's campaign is accepted. A row that names a different campaign is rejected as that item, with param lead_source_id, and the rest of the batch continues.

An agency key that is not bound to a campaign posts like this:

curl -X POST https://api.entrovox.com/v1/leads/batch \
  -H "Authorization: ApiKey $ENTROVOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "lead_source_id": "YOUR_CAMPAIGN_ID",
    "leads": [
      {
        "first_name": "Alex",
        "last_name": "Nguyen",
        "phone": "+14255550001",
        "external_id": "inv-1001"
      }
    ]
  }'

Rules that apply to every batch

  • A bad row never fails the batch. DNC, a bad phone, a missing external_id or a paused campaign comes back as a rejected item with its code. The whole request fails only when it is malformed (422: no leads, an empty array, more than 500 rows) or names a campaign your key cannot use (403 LEAD_SOURCE_NOT_ALLOWED, 404 LEAD_SOURCE_NOT_FOUND).
  • Rows that share a phone run in order. Rows run in parallel, except that rows with the same phone (or external_id) run in input order. The first is created; a later one is conflict (LEAD_PHONE_CONFLICT) or replayed.
  • Retrying a whole batch. The batch Idempotency-Key must be a UUID, or the request gets 400 VALIDATION_ERROR. Send the same key and the same body. You get the original response back and no row is processed again.
  • Limits. 500 leads per request and 20 batches per minute on a standard partner key. See Rate limits and volume.

Next steps

Follow each created lead from its status URL, and read Safe retries and idempotency before you automate resends.

Updated Nov 7, 2026