---
title: "Add Contacts to Lists"
method: POST
path: "/activities/add_list_memberships"
tags: ["Bulk Activities"]
---

# Add Contacts to Lists

`POST /activities/add_list_memberships`

Use this method to create an activity that adds contacts to one or more lists. Each contact can be a member of up to 50 lists. Use the properties in the `source` object to specify the contacts you want to add to lists. Use the `list_ids` array to specify which lists you want to add your source contacts to.

## Request body

- ListActivityAddContacts
  - `source` object, required — The <code>source</code> object specifies which contacts you are adding to your targeted lists using one of four mutually exclusive properties.
    - `list_ids` string[] — Specifies which contacts you are adding to lists as an array of up to 50 contact <code>list_id</code> values. This property is mutually exclusive with <code>contact_ids</code>, <code>all_active_contacts</code> (billable), and <code>segment_id</code>.
    - `all_active_contacts` boolean — Adds all active (billable) contacts to your targeted lists. This property is mutually exclusive with <code>contact_ids</code>, <code>list_ids</code>, and <code>segment_id</code>.
    - `contact_ids` string[] — Specifies which contacts (up to 500) you are adding to lists as an array of <code>contact_id</code> values. This property is mutually exclusive with <code>list_ids</code>, <code>all_active_contacts</code> (billable), and <code>segment_id</code>.
    - `tag_ids` string[] — Adds all contacts assigned with the specified <code>tag_id</code>s to your target lists. This property is mutually exclusive with all other <code>source</code> properties.
    - `engagement_level` string — Adds all contacts that meet the selected <code>engagement_level </code> to your target lists. This property is mutually exclusive with all other <code>source</code> properties.
    - `segment_id` integer — Specifies which contacts you are adding to lists as a single <code>segment_id</code> value. This property is mutually exclusive with <code>list_ids</code>, <code>all_active_contacts</code> (billable), and <code>contact_ids</code>.
  - `exclude` object
    - `contact_ids` string[] — Excludes specified contacts (<code>contact_id</code>) from being added to the target list. Applicable if using either the <code>all_active_contacts</code> (billable) or <code>list_ids</code> as the source.
  - `list_ids` string[], required — Specifies which lists (up to 50) you are adding your source contacts to.

## Response `201`

Request successful. Activity queued for processing.

- ActivityListsMembership
  - `activity_id` string, uuid — Unique ID for the activity.
  - `state` string — The state of the request: <p><ul> <li>initialized - request has been received</li> <li>processing - request is being processed</li> <li>completed - job completed</li> <li>cancelled - request was cancelled</li> <li>failed - job failed to complete</li> <li>timed_out - the request timed out before completing"</li> </ul> </p>
  - `started_at` string, date-time — Timestamp showing when we began processing the activity request, in ISO-8601 format.
  - `completed_at` string, date-time — Timestamp showing when we completed processing the activity, in ISO-8601 format.
  - `created_at` string, date-time — Timestamp showing when we created the activity, in ISO-8601 format.
  - `updated_at` string, date-time — Timestamp showing when we last updated the activity, in ISO-8601 format.
  - `percent_done` integer — Shows the percent done for an activity that we are still processing.
  - `activity_errors` string[] — Array of messages describing the errors that occurred.
  - `status` object
    - `items_total_count` integer — Total number of contacts to add to or remove from lists.
    - `items_completed_count` integer — The number of contacts processed.
    - `list_count` integer — The number of lists specified in the request.
  - `_links` ActivityStatusLink
    - `self` object — HATEOS-style link to the activity status (this object).
      - `href` string

## Other responses

- `400` — Bad request. Either the JSON was malformed or there was a data validation error.
- `401` — The Access Token used is invalid.
- `403` — Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
- `429` — Too many requests. You exceeded 1,000 queued activities for this user account.
- `500` — There was a problem with our internal service.
- `503` — Our internal service is temporarily unavailable.

---

[API](https://skmtc.net/cc/apis/appconnect-v3.md) · [All operations](https://skmtc.net/cc/apis/appconnect-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cc/appconnect-v3/versions/4b4a534c818d/schema)