---
title: "Add up to 100 contacts to a list"
method: POST
path: "/lists/list/{listId}/contacts/batch"
tags: ["List contacts"]
---

# Add up to 100 contacts to a list

`POST /lists/list/{listId}/contacts/batch`

## Request

- Base URL: `https://api.emelia.io`
- URL: `https://api.emelia.io/lists/list/{listId}/contacts/batch`
- Auth: API key in header `Authorization`

Adds 1 to 100 contacts in one call. Each item of `contacts` is the same flat object as in `POST /lists/list/{listId}/contacts`, with the same key resolution, custom variable creation, duplicate rules and `updateIfExists` behaviour (read that endpoint first).

Rows are processed one after the other and independently: a failing row is reported in `results` with its `index` and an `error` message and does not stop the others. A row repeating an email or LinkedIn URL already seen earlier in the same batch is counted as a duplicate of that earlier row and is never updated, even with `updateIfExists=true`.

Counters: `created + duplicates + failed = total`, and `updated` is a subset of `duplicates`. The body must be an object with a `contacts` array, not a bare array. Split larger loads into several calls of 100.

## Path parameters

- `listId` string, required

## Query parameters

- `updateIfExists` 'true' | 'false'

## Request body

- object
  - `contacts` ListsContactFields[], required

## Response `200`

Batch processed. Read `results` for the outcome of each row.

- ListsBatchResult
  - `success` true, required: True even when some rows failed.
  - `total` integer, required
  - `created` integer, required
  - `duplicates` integer, required: Includes the updated duplicates.
  - `updated` integer, required
  - `failed` integer, required
  - `results` ListsBatchRowResult[], required: One entry per input row, in input order.
    - `index` integer, required: Position of the row in `contacts`, starting at 0.
    - `leadId` string
    - `companyId` string, nullable
    - `duplicate` boolean
    - `updated` boolean
    - `error` string
  - `createdCustomVariables` ListsCreatedCustomVariable[], required
    - `technicalName` string, required
    - `displayName` string, required: The key as sent.
    - `schema` 'lead' | 'company', required: Always `lead` for variables created by the contact routes.

## Other responses

- `400`: The list id is not a valid ObjectId.
- `401`: Missing, unknown or disabled API key, or the account of the key no longer exists. Note the body shape: `error` and `code`, not `message`.
- `404`: The list does not exist or belongs to another account.
- `413`: JSON body larger than 5 MB.
- `422`: `contacts` missing, not an array, empty or longer than 100.
- `500`: Unexpected server error. `error`, when present, is a raw internal message: do not parse it. Retry later.

---

[API](https://skmtc.dev/emelia/apis/emelia-api.md) · [All operations](https://skmtc.dev/emelia/apis/emelia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/emelia/apis/emelia-api/revisions/8c0cb435f2c4?raw)