Add one or more tags too multiple contacts.

To quickly add tags to a large numbers of contacts, use the POST /activities/contacts_taggings_add endpoint.

The request body includes the following schema:

  • source - Identifies the contacts to which tags are added. 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 - add tags by tag_id to all contacts meeting the specified source criteria (array).

The following example adds a tag to all active contacts in the account with a single contact excluded.

{
  "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_add

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_add',
  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_taggings_add' \
--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_taggings_add")
  .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!