Presents the differences between the V3 and V2 list resource model, and instructions on cross-referencing V2 & V3 List IDs.

This topic is intended for developers that are migrating a V2 integration with locally stored list data to the V3 API format.

List Properties Comparison

This section identifies differences between the V2 and V3 list resource properties.

New list_id Format in V3
In the V3 API, list_id values use Universally Unique Identifier (UUID) format. The V2 format was string. For more information, see RFC 4122.
V3 List Property V3 Definition V2 Equivalent
list_id
Unique ID for each list resource, in UUID format, see RFC 4122. V2 format is string. id
name
The list name. name
description
Text describing the list. N/A
favorite
Boolean that indicates if this is one of the user's "favorite" lists. N/A
created_at
System generated date and time that the contact was created, in ISO-8601 format. created_date
updated_at
Date and time that the list was last updated, in ISO-8601 format. modified_date
membership_count
The number of contacts in the list. contact_count
N/A
In V2 identified the list status; no V3 equivalent. status

How to Cross-reference V2 and V3 List IDs

The following V2 and the V3 API endpoints provide cross-referenced V2 and V3 IDs contact lists.

For each V2 campaignId value that you provide, this endpoint returns the corresponding V3 campaign_id and V3 campaign_activity_id value. You can enter up to 500 V2 campaignId values in each request.

API VersionEndpointDescription For More Info
V2 List Collection endpoint Use the include_list_id=true query parameter to have the V3 list_id for each list included in the response payload.For more information, see the V2 API Get Contact List Collection documentation.
V3 Lists ID Xref endpoint This endpoints accepts up to 500 V2 formatted list id values using the list_sequence_numbers query parameter, and returns the V2 and V3 id key-value pairs for each list. This endpoint does not support pagination. For more information, see the V3 API Get Reference endpoint documentation.

Cross-reference List IDs in V3 API

This endpoint accepts up to 500 V2 list sequence IDs, and returns the cross-referenced V2 and V3 ID for each sequence ID submitted.

This endpoint is a migration tool to use to cross-reference each list in a user's account. Developers are expected to use this endpoint sparingly. It is NOT intended for regular and repeated use.

GET https://api.cc.email/contact_lists/lists_id_xrefs?list_sequence_numbers=sequence_number1,sequence_number2,sequence_number3,sequence_number4

Endpoint Requirements

Authorization scopes: contact_data

<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/contact_lists/lists_id_xrefs');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'list_sequence_numbers' => '12345678,23456789,34567891'
));

$request->setHeaders(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer <access_token>',
  'Accept' => 'application/json'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.cc.email/contact_lists/lists_id_xrefs?list_sequence_numbers=12345678,23456789,34567891")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <access_token>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();
curl -X GET \
  'https://api.cc.email/contact_lists/lists_id_xrefs?list_sequence_numbers=12345678,23456789,34567891' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json'

Response

[
    {
      "list_id": "77777777-9999-1111-907f-888888888888",
      "list_sequence_number": "12345678"
    },
    {
      "list_id": "88888888-9999-1111-9f7f-888888888888",
      "list_sequence_number": "23456789"
    },
    {
      "list_id": "88888888-9999-1111-4444-888888888888",
      "list_sequence_number": "34567891"
    }
]

Cross-reference List IDs in V2 API

The V2 list collection endpoint has a include_list_id query parameter for use with the GET method. When set to true (default is false), the response payload includes the V3 list_id in each list object. Use this query parameter to cross-reference V2 and V3 IDs for each list in the user’s account. There is no limit on using this endpoint. View the complete documentation for this endpoint.

Example Request

Here are examples using this endpoint.

GET https://api.constantcontact.com/v2/lists?api_key=<api_key>&include_list_id=true

Endpoint Requirements

Authorization scopes: contact_data

<?php

$request = new HttpRequest();
$request->setUrl('https://api.constantcontact.com/v2/lists');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'api_key' => '<api_key>',
  'include_list_id' => 'true'
));

$request->setHeaders(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer <access_token>',
  'Accept' => 'application/json'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
curl -X GET \
  'https://api.constantcontact.com/v2/contacts?api_key=<api_key>&include_contact_id=true' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.constantcontact.com/v2/contacts?api_key=<api_key>&include_contact_id=true")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <access_token>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

Response

[
    {
        "id": "12345678",
        "list_id":"12345678-1234-1234-1234-123456789012",
        "name": "General Interest",
        "status": "ACTIVE",
        "created_date": "2013-03-11T20:37:28.000Z",
        "modified_date": "2013-03-11T20:41:42.000Z",        
        "contact_count": 143
    },
    {
        "id": "29876543",
        "list_id":"12345678-1234-1234-1234-123456789012",
        "name": "Great News!",
        "status": "ACTIVE",
        "created_date": "2012-12-19T21:33:22.000Z",
        "modified_date": "2013-02-01T17:54:43.000Z",        
        "contact_count": 53
    },
    {
        "id": "34567892",
        "list_id":"12345678-1234-1234-1234-123456789012",
        "name": "Monthly Specials!",
        "status": "ACTIVE",
        "created_date": "2012-12-19T21:33:50.000Z",
        "modified_date": "2013-02-01T17:54:43.000Z",
        "contact_count": 375
    },
    {
        "id": "4",
        "list_id":"12345678-1234-1234-1234-123456789012",
        "name": "Tips, Tricks, & Fun!",
        "status": "HIDDEN",
        "created_date": "2012-12-19T21:33:50.000Z",
        "modified_date": "2013-02-01T17:54:43.000Z",
        "contact_count": 2
    }
    
]