POST /public/v1/leads/batch

Auth	Required
Scope	leads:write
Idempotency-Key	Required

Upserts 1 to 100 leads. Each item follows POST /leads, including the rule of exactly one organization locator.

A nested organization on any item needs organizations:write on the same key. If the scope is missing, that row returns action: "error" and error_code: "insufficient_scope". Sync companies first, then send organization_external_reference, if the lead key should not be allowed to create companies.

Schema errors fail the entire request. Per-row problems (not_found, nested organization validation) return action: "error" and leave the other rows saved.

Response

{
  "results": [
    {
      "index": 0,
      "external_reference": "deal-4421",
      "action": "created",
      "id": "8f0c…",
      "error_code": null,
      "message": null
    }
  ]
}

Successful rows emit lead.upserted after the batch commits.

Try It

Try It calls https://staging-api.appraiserflow.ai/public/v1 with an af_test_ key. The key stays in sessionStorage. af_live_ keys are blocked. Live server calls use https://api.appraiserflow.ai/public/v1 with an af_live_ key kept on your server.

API Key (af_test_…)JSON Body{"items":[{"external_reference":"deal-4421","title":"Acme — 123 Main St","stage":"lead","organization_external_reference":"sf-001"}]}