> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Members

> Add one or more people to a marketing list.

## Method

`POST` `/v1/comms/lists/:id/members`

## Path Parameters

<ParamField path="id" type="string" required>The list ID.</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>Bearer token (requires `comms:write`).</ParamField>
<ParamField header="Content-Type" type="string" required>`application/json`</ParamField>

## Body Parameters (Single Member)

<ParamField body="personId" type="string" required>The person ID to add.</ParamField>
<ParamField body="source" type="string">How the member was added: `manual`, `import`, `api`, `form`. Defaults to `api` when using the API.</ParamField>

## Body Parameters (Batch Add)

<ParamField body="personIds" type="string[]" required>Array of person IDs to add.</ParamField>
<ParamField body="source" type="string">How the members were added. Defaults to `api`.</ParamField>

## Request Example

<RequestExample>
  ```bash cURL (Single) theme={null}
  curl -X POST "https://api.voyantcloud.com/v1/comms/lists/lists_01J0CBFPXW7SP2N8A9Q7T2048Q/members" \
    -H "Authorization: Bearer $VOYANT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "personId": "people_01HZYPM2QF2R8X9SZQ0J9SYBCN"
    }'
  ```

  ```bash cURL (Batch) theme={null}
  curl -X POST "https://api.voyantcloud.com/v1/comms/lists/lists_01J0CBFPXW7SP2N8A9Q7T2048Q/members" \
    -H "Authorization: Bearer $VOYANT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "personIds": [
        "people_01HZYPM2QF2R8X9SZQ0J9SYBCN",
        "people_02ABCDE3FG4HI5JK6LM7N8O9PQ"
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const listId = "lists_01J0CBFPXW7SP2N8A9Q7T2048Q"

  // Add single member
  const res = await fetch(
    `https://api.voyantcloud.com/v1/comms/lists/${listId}/members`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.VOYANT_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        personId: "people_01HZYPM2QF2R8X9SZQ0J9SYBCN",
      }),
    }
  )

  // Add multiple members
  const batchRes = await fetch(
    `https://api.voyantcloud.com/v1/comms/lists/${listId}/members`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.VOYANT_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        personIds: [
          "people_01HZYPM2QF2R8X9SZQ0J9SYBCN",
          "people_02ABCDE3FG4HI5JK6LM7N8O9PQ",
        ],
      }),
    }
  )
  ```

  ```python Python theme={null}
  import os, requests

  list_id = "lists_01J0CBFPXW7SP2N8A9Q7T2048Q"

  # Add single member
  resp = requests.post(
    f"https://api.voyantcloud.com/v1/comms/lists/{list_id}/members",
    json={"personId": "people_01HZYPM2QF2R8X9SZQ0J9SYBCN"},
    headers={"Authorization": f"Bearer {os.environ['VOYANT_API_KEY']}"},
  )

  # Add multiple members
  resp = requests.post(
    f"https://api.voyantcloud.com/v1/comms/lists/{list_id}/members",
    json={
      "personIds": [
        "people_01HZYPM2QF2R8X9SZQ0J9SYBCN",
        "people_02ABCDE3FG4HI5JK6LM7N8O9PQ",
      ]
    },
    headers={"Authorization": f"Bearer {os.environ['VOYANT_API_KEY']}"},
  )
  ```
</RequestExample>

## Response Example (Single)

<ResponseExample>
  ```json 201 Created (Single) theme={null}
  {
    "id": "list_members_01J0CBFPXW7SP2N8A9Q7T2048Q",
    "list_id": "lists_01J0CBFPXW7SP2N8A9Q7T2048Q",
    "person_id": "people_01HZYPM2QF2R8X9SZQ0J9SYBCN",
    "status": "subscribed",
    "source": "api",
    "subscribed_at": "2025-01-08T10:22:31.000Z",
    "unsubscribed_at": null,
    "created_at": "2025-01-08T10:22:31.000Z",
    "person": null
  }
  ```

  ```json 201 Created (Batch) theme={null}
  {
    "data": {
      "added": 2
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "List not found"
  }
  ```
</ResponseExample>

<Tip>
  Use batch add (`personIds`) when adding multiple members for better performance. Duplicate person IDs are handled gracefully (existing members are skipped).
</Tip>