Remove tags from a large number of contacts.

Use the POST /activities/contacts_taggings_remove endpoint to create an asynchronous activity used to quickly remove tags from a large numbers of contacts. To specify which contacts to remove tags from, select one of the following options:

  • source - Identifies the contacts from which specified tags are removed. Source options are mutually exclusive:

    • contact_ids - include up to 500 contacts by contact_id (array).
    • list_ids - include all contacts that are members of up to 50 lists by list_id (array).
    • tag_ids - include contacts that are tagged with specific tags by tag_id (array).
    • all_active_contacts - include all active contacts for the user’s account (boolean).
    • new_subscriber - include all new subscribers (boolean).
  • exclude - exclude specific contacts by contact_id (array). Only applicable if the specified source is either all_active_contacts or list_ids.

  • tag_ids - the tags (tag_id) to remove from all contacts meeting the specified source criteria (array).

For example, other than the excluded contact_id, the following request removes tags from all the accounts active contacts tagged with the tag_id equal to 00e4429c-3beb-11eb-9f34-fa163e56c9b9.

{
  "source": {
    "all_active_contacts": "true"
  },
  "exclude": {
    "contact_ids": [
      "71600990-908b-11e6-907f-00166bff25"
    ]
  },
  "tag_ids": [
    "00e4429c-3beb-11eb-9f34-fa163e56c9b9"
  ]
}

Example Requests

POST https://api.cc.email/v3/activities/contacts_taggings_remove

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cc.email/v3/activities/contacts_taggings_remove',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "source": {  
     "list_ids": [
        "c149ae80-cd2e-11e6-9274-00163e3b3e3g"
     ],
     "exclude": [
         "6efe8ad0-08bf-11e6-b381-00163e498a39"
    ]
  },
  "tag_ids": [
    "2c388e8e-24ef-11eb-8ae8-fa163e595592"
  ]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer {access_token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

<?php
curl --location --request POST 'https://api.cc.email/v3/activities/contacts_tagging_remove' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}'\
--data-raw '{
  "source": {  
     "list_ids": [
        "c149ae80-cd2e-11e6-9274-00163e3b3e3g"
     ],
     "exclude": [
         "6efe8ad0-08bf-11e6-b381-00163e498a39"
    ]
  },
  "tag_ids": [
    "2c388e8e-24ef-11eb-8ae8-fa163e595592"
  ]
}'
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"source\": {  \n     \"list_ids\": [\n        \"c149ae80-cd2e-11e6-9274-00163e3b3e3g\"\n     ],\n     \"exclude\": [\n         \"6efe8ad0-08bf-11e6-b381-00163e498a39\"\n    ]\n  },\n  \"tag_ids\": [\n    \"2c388e8e-24ef-11eb-8ae8-fa163e595592\"\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.cc.email/v3/activities/contacts_tagging_remove")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {access_token}")
  .build();
Response response = client.newCall(request).execute();

Example Response

The response includes details about the activity and the href link to use to view the current status of the activity.

{
    "activity_id": "ea6ae88a-88cb-11eb-b512-fa163ef30864",
    "state": "initialized",
    "created_at": "2021-03-19T15:58:15Z",
    "updated_at": "2021-03-19T15:58:15Z",
    "percent_done": 1,
    "activity_errors": [],
    "status": {},
    "_links": {
        "self": {
            "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6z"
        }
    }
}

Checking the Activity Status for Job Complete

Check the activity status and when Constant Contact has completed processing an activity by making a GET call to /activities/{activity_id} using the activity_id located in the _links section of the response.

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

Try it!