---
title: "Add subscribers to list"
method: POST
path: "/api/lists/subscribe"
tags: ["lists"]
---

# Add subscribers to list

`POST /api/lists/subscribe`

Add specific subscribers to a list.<br/><br/>Learn about <a href="https://support.iterable.com/hc/articles/29156459027348">identifying users by <code>userId</code> and <code>email</code></a>.

## Request body

- SubscribeRequest
  - `listId` integer, required
  - `subscribers` OptionalApiUser[], required
    - `dataFields` object
    - `email` string — An email address that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
    - `mergeNestedObjects` boolean — Merge top-level objects instead of overwriting them. Defaults to <code>false</code>. For example, if a user profile has data <code>{"mySettings":{"mobile":true}}</code> and the request has data <code>{"mySettings":{"email":true}}</code>, merging results in <code>{"mySettings":{"mobile":true,"email":true}}</code>.
    - `preferUserId` boolean — Whether or not a new user should be created if the request includes a <code>userId</code> that doesn't yet exist in the Iterable project. Defaults to <code>false</code>. Only respected in API calls for <a href="https://support.iterable.com/hc/articles/29156459027348">email-based projects</a>.
    - `userId` string — A user ID that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
  - `updateExistingUsersOnly` boolean — Whether to skip operation when the request includes a <code>userId</code> or <code>email</code> that doesn't yet exist in the Iterable project. When <code>true</code>, Iterable ignores requests with unknown userIds and email addresses. When <code>false</code>, Iterable creates new users. Defaults to <code>false</code>. Only respected in API calls for <a href="https://support.iterable.com/hc/articles/29156459027348">userID-based and hybrid projects</a>.

## Response `200`

successful operation

## Other responses

- `400` — Invalid parameters
- `401` — Invalid API key

---

[API](https://skmtc.net/iterable/apis/iterable-api.md) · [All operations](https://skmtc.net/iterable/apis/iterable-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/iterable/iterable-api/revisions/afaab604b58c/schema)