# Push leads into a list

`POST https://app.whatsetter.com/api/v1/lists/{id}/leads`

The CRM-integration primitive: add up to 500 leads per call. Phones are
deduplicated (within the batch and against the list). Imported leads go
through WhatSetter's normal verification and anti-ban sending pipeline.

Per-row rules: `phone` must be an international number (8–15 digits,
`+` optional); `name` and `email` are truncated at 255 characters,
never rejected; `custom_variables` must be an object whose JSON is at
most 2000 characters. A row that breaks a rule lands in `rejected` with
its `index` and a `reason` — `invalid_phone: …`, `duplicate_in_batch`,
`custom_variables must be an object`, `custom_variables exceeds 2000
characters`, or the storage error message on a rare write failure —
while the valid rows are still imported. A phone already in the list
is counted in `duplicates_in_list`, not rejected. When no row is
importable the call answers `422`. Requires scope `lists:write`.

Pushing into a list whose campaign has already written to everyone
reopens it, as the dashboard's import does: with `keep_open` it sends
again at once (`list_status: processing`), otherwise it waits for
**Resume** (`list_status: paused`). A list paused by hand, or still
sending, is left as it is.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `leads` | array | yes |  |

```json
{
  "leads": [
    {
      "phone": "+33612345678",
      "name": "Marie Dupont",
      "email": "marie@acme.fr",
      "custom_variables": {
        "offre": "Pack Pro",
        "ville": "Lyon"
      }
    },
    {
      "phone": "not a phone"
    }
  ]
}
```

## Example request

```bash
curl --request POST \
  --url 'https://app.whatsetter.com/api/v1/lists/{id}/leads' \
  --header 'Authorization: Bearer ws_live_…'
  --header 'Content-Type: application/json' \
  --data '{"leads":[{"phone":"+33612345678","name":"Marie Dupont","email":"marie@acme.fr","custom_variables":{"offre":"Pack Pro","ville":"Lyon"}},{"phone":"not a phone"}]}'
```

## Responses

### 201: Import result (valid rows imported, the rest listed in `rejected`)

```json
{
  "data": {
    "imported": 1,
    "duplicates_in_list": 0,
    "rejected": [
      {
        "index": 1,
        "reason": "invalid_phone: expected international format, e.g. +33612345678"
      }
    ],
    "lead_ids": [
      "68f0aa11bb22cc33dd44ee55"
    ],
    "list_status": "processing"
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 404: Resource not found in this workspace

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 422: `leads` is not an array of 1–500 objects, or no row is importable

```json
{
  "error": {
    "code": "validation_error",
    "message": "No importable lead in the batch (2 rejected). First reason: duplicate_in_batch."
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/importleads/
