v1

latestSwagger 2.0Private2026-08-04128286690.5 KB

Bulk Activities

Add Contacts to Lists

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.

post/activities/add_list_memberships

Request body

list_idsstring[] required

Specifies which lists (up to 50) you are adding your source contacts to.

Example request

{
  "source": {
    "list_ids": [
      "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
    ],
    "all_active_contacts": true,
    "contact_ids": [
      "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
    ],
    "tag_ids": [
      "5e88f172-21d1-11ea-b5ae-fa163e56c9b9"
    ],
    "engagement_level": "high",
    "segment_id": 12
  },
  "exclude": {
    "contact_ids": [
      "4d88f172-21d1-11ea-b5ae-fa163e56c9b0"
    ]
  },
  "list_ids": [
    "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
  ]
}

Response

Request successful. Activity queued for processing.

activity_idstring uuid

Unique ID for the activity.

statestring

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_atstring date-time

Timestamp showing when we began processing the activity request, in ISO-8601 format.

completed_atstring date-time

Timestamp showing when we completed processing the activity, in ISO-8601 format.

created_atstring date-time

Timestamp showing when we created the activity, in ISO-8601 format.

updated_atstring date-time

Timestamp showing when we last updated the activity, in ISO-8601 format.

percent_doneinteger

Shows the percent done for an activity that we are still processing.

activity_errorsstring[]

Array of messages describing the errors that occurred.

Example response

{
  "activity_id": "86b90820-cc52-11ea-9dad-fa163e3d9194",
  "state": "initialized",
  "started_at": "2016-01-23T13:48:44.108Z",
  "completed_at": "2016-01-23T13:48:44.108Z",
  "created_at": "2016-01-23T13:48:44.108Z",
  "updated_at": "2016-01-23T13:48:44.108Z",
  "percent_done": 75,
  "activity_errors": [
    "Message describing the error condition."
  ],
  "status": {
    "items_total_count": 2200,
    "items_completed_count": 652,
    "list_count": 3
  },
  "_links": {
    "self": {
      "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
    }
  }
}