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

This information is useful if you are migrating an existing V2 integration to the V3 API.

List Properties Comparison

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

New list_id Format in V3

`list_id` values are formatted as UUIDs (see RFC 4122). The V2 format was string.
V3 List Property V3 Definition V2 Equivalent
list_id
Unique ID for each list resource, in UUID (Universally Unique IDentifier) format, see [RFC 4122](https://tools.ietf.org/html/rfc4122). 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 tools in the V2 and the V3 API provide cross-referenced V2 and V3 IDs for each list in a user’s account.

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. See the V2 documentation for more info.
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. See the V3 API 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

<?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

<?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
    }
    
]