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.
API Version | Endpoint | Description | 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 sequence_ids 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.
GET https://api.cc.email/v3/contact_lists/list_id_xrefs?sequence_ids=sequence_number1,sequence_number2,sequence_number3,sequence_number4
Endpoint Requirements
User privileges: contacts:lists:read
Authorization scopes: contact_data
<?php
$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contact_lists/list_id_xrefs');
$request->setMethod(HTTP_METH_GET);
$request->setQueryData(array(
'sequence_ids' => '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/v3/contact_lists/list_id_xrefs?sequence_ids=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/v3/contact_lists/list_id_xrefs?sequence_ids=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",
"sequence_id": "12345678"
},
{
"list_id": "88888888-9999-1111-9f7f-888888888888",
"sequence_id": "23456789"
},
{
"list_id": "88888888-9999-1111-4444-888888888888",
"sequence_id": "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
User privileges: contacts:lists:read
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_list_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_list_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
}
]