This topic is intended for developers that are migrating a V2 integration with locally stored contact data to the V3 API format.
This information is useful if you are migrating an existing integration from the V2 to the V3 API. You can view a sample contact resource here.
Contact Properties Comparison
Contact Core Properties
The V3 contact resource has core properties and subresources. This section identifies differences between the V2 and V3 core properties. Learn more about core properties and subresources.
New contact_id
Format in V3
In the V3 API, contact_id
values use Universally Unique Identifier format (UUID). The V2 API uses string format. For more information, see RFC 4122.V3 Contact Property | V3 Definition | V2 Equivalent |
---|---|---|
anniversary |
Accepted date formats: MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D, MM-DD-YYYY, M-D-YYYY | None |
birthday_day |
Accepts values from 1-31; must be used with birthday_month |
None |
birthday_month |
Accepts values from 1-12; must be used with birthday_day |
None |
contact_id |
Unique ID for each contact resource in UUID format. The V2 format is string. | id |
created_at |
System generated date and time that the contact was created, in ISO-8601 format. | created_date |
create_source |
Describes who added the contact. Valid values are Contact or Account . |
None |
deleted_at |
For deleted contacts (email_address has both opt_out_source and opt_out_date ), shows the date of deletion. |
None |
N/A | N/A | source_details |
updated_at |
System generated date and time that the contact was last updated, in ISO-8601 format. | modified_date |
update_source |
Identifies who last updated the contact. Valid values are Contact or Account . |
None |
Email Address
The email_address
object defines the user’s email address. Differences with the V2 email_addresses
array are called out here:
V3 Contact Property | V3 Definition | V2 Equivalent |
---|---|---|
email_address |
||
email_address |
object that defines the contact's email address | email_addresses array |
address |
The contact's email address; must be unique for each contact. | email_address |
confirm_status |
V3 values: Pending, Off, or Confirmed. | confirm_status : Unconfirmed, No_confirmation_required, or Confirmed. |
opt_in_source |
V3 values: Contact or Account. | opt_in_source : ACTION_BY_VISITOR, ACTION_BY_OWNER, ACTION_BY_SYSTEM |
opt_out_source |
V3 values: Contact or Account. | opt_out_source : ACTION_BY_VISITOR, ACTION_BY_OWNER |
permission_to_send |
Types of permission: explicit, implicit, deprecate, not_set, pending, temp_hold, unsubscribe | status : active, non_subscriber, visitor, temp_hold, unconfirmed, removed, optout (unsubscribe equivalent) |
Contact Subresources
Custom Fields
custom_fields
is a subresource of the V3 contact resource, expressed as array of custom fields. You can use the V3 API to add up to 25 custom fields to each contact. The V2 API supports up to 15 custom fields in each contact. This section identifies the custom_fields
resource differences between the V2 and V3 definitions. The V3 API has a separate set of endpoints for managing custom_fields. The V3 custom_fields
array in the contact resource only contains the custom_field_id
and value
properties. You can access the other custom_fields
properties through the V3 custom fields endpoints.
V3 Contact Property | V3 Definition | V2 Equivalent |
---|---|---|
custom_fields |
||
custom_field_id |
The custom_field unique identifier, in UUID format. |
None |
value |
The content of the custom field. The value character limit is 255 in the V3 API and in the contact editor UI. |
value (The value character limit in the V2 API is 50). |
Not used | See V3 custom_field endpoints. | name |
Not used | See V3 custom_field endpoints. | label |
List Memberships
list_memberships
is a subresource of the V3 contact resource, expressed as an array of up to 50 list_ids
of which the contact is a member. The list details that are available in the V2 contact resource are available in a set of V3 list management endpoints.
New list_id
Format in V3
In the V3 API, list_id
values use UUID (Universally Unique Identifier) format. The V2 format was string. For more information, see RFC 4122.Notes
custom_fields
instead.Phone Numbers
phone_numbers
is a subresource of the V3 contact resource, expressed as array of up to 2 phone_numbers. This section calls out phone_number
-related differences in V2 and V3.
V3 Contact Property | V3 Definition | V2 Equivalent |
---|---|---|
phone_numbers |
||
created_at |
System generated date and time that the phone_number was created, in ISO-8601 format. |
None |
create_source |
Describes who added the phone_number ; Contact or Account. |
None |
kind |
Describes the type of phone number; valid values are home, work, or other. | None |
phone_number |
The contact's phone number. | cell_phone, fax, home_phone, work_phone . |
phone_number_id |
phone_number unique identifier in UUID format. |
None |
updated_at |
System generated date and time that the phone_number was last updated, in ISO-8601 format. |
None |
update_source |
Identifies who last updated the phone_number ; valid values are Contact or Account. |
None |
Street Addresses
street_addresses
is a subresource of the V3 contact resource, expressed as an array of up to one address. The V2 equivalent is the addresses
array; the differences are described below.
V3 Contact Property | V3 Definition | V2 Equivalent |
---|---|---|
street_addesses |
||
street_addesses |
The V3 API supports up to one address per contact. | addresses (The V2 API supports up to two street addresses per contact) |
created_at |
System generated date and time that the address was created, in ISO-8601 format. | None |
kind |
Describes the kind of street_address (home, work, other). | address_type (personal, business) |
street |
Number and street of the address. | line1 line2 |
country |
Name of the country in the address. | country_code |
state |
Same as V2, however V3 does not support state_code |
state |
postal_code |
Same as V2, however V3 does not support sub_postal_code |
postal_code |
updated_at |
System generated date and time that the address was last updated, in ISO-8601 format. | None |
How to Cross-reference V2 and V3 Contact Identifiers
You will need to cross-reference V2 & V3 contact identifiers if:
- You have developed an existing integration with our V2 API
- Your integrations stores constant contact data locally (contacts, lists, campaigns,etc.)
- You are building a new version of the integration using the V3 API
- You want a seamless transition for existing users
The following tools in the V2 and the V3 API provide cross-referenced V2 and V3 IDs for each contact in a user’s account.
API Version | Endpoint | Description | More Information |
---|---|---|---|
V3 | Contacts ID Xref endpoint | This endpoints accepts V2 formatted contact id values using the sequence_ids query parameter, and returns the V2 and V3 id key-value pairs for each contact. This endpoint cross-references a maximum of 500 ids at a time, and does not support pagination. |
See the V3 API Reference for complete endpoint documentation. |
V2 | Contact Collection endpoint | Use the include_contact_id=true query parameter to have the V3 contact_id for each contact included in the response payload. |
See the V2 documentation for complete endpoint documentation. |
Cross-reference Contact IDs in V3 API
The Contacts ID Xref endpoint in the V3 API accepts V2 API contact ids
using the sequence_ids
query parameter, and returns the V2 and V3 ids for each contact. This endpoint cross-references a maximum of 500 contact ids at a time, and does not support pagination.
Example V3 Cross-reference Request
GET https://api.cc.email/v3/contacts/contacts_id_xrefs?sequence_ids=sequence_number1,sequence_number2,sequence_number3,sequence_number4
Endpoint Requirements
User privileges: contacts:read
Authorization scopes: contact_data
<?php
$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contacts/contacts_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/contacts/contacts_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/contacts/contacts_id_xrefs?sequence_ids=12345678,23456789,34567891' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'
Response
[
{
"contact_id": "77777777-9999-1111-907f-888888888888",
"sequence_id": "12345678"
},
{
"contact_id": "88888888-9999-1111-9f7f-888888888888",
"sequence_id": "23456789"
},
{
"contact_id": "88888888-9999-1111-4444-888888888888",
"sequence_id": "34567891"
}
]
Cross-reference Contact IDs in V2 API
The V2 contact collection endpoint has a include_contact_id
query parameter for use with the GET method. When set to true
(default is false
), the response payload includes the V3 contact_id
in each contact object. Use this query parameter to cross-reference V2 and V3 IDs for each contact. There is no limit on using this endpoint. View the complete documentation for this endpoint.
Example V2 Cross-reference Request
Here are examples using this endpoint in the V2 API.
GET https://api.constantcontact.com/v2/contacts?api_key=<api_key>&include_contact_id=true
Endpoint Requirements
User privileges: contacts:read
Authorization scopes: None
<?php
$request = new HttpRequest();
$request->setUrl('https://api.constantcontact.com/v2/contacts');
$request->setMethod(HTTP_METH_GET);
$request->setQueryData(array(
'api_key' => '<api_key>',
'include_contact_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
{
"results": [
{
"id": "111111111",
"status": "ACTIVE",
"fax": "",
"addresses": [
{
"id": "d55dd3aa-2222-3333-4444-00163e68e976",
"line1": "55 Gale St.",
"line2": "Apt. 23",
"line3": "",
"city": "Nashville",
"address_type": "BUSINESS",
"state_code": "TN",
"state": "Tennessee",
"country_code": "us",
"postal_code": "37207"
}
],
"confirmed": false,
"lists": [],
"source": "Site Owner",
"contact_id": "8888888-4444-4444-4444-012345678910",
"email_addresses": [
{
"id": "11111111-2222-3333-4444-012345678910",
"status": "ACTIVE",
"confirm_status": "NO_CONFIRMATION_REQUIRED",
"opt_in_source": "ACTION_BY_VISITOR",
"opt_in_date": "2013-01-18T21:45:22.000Z",
"email_address": "email@example.com"
}
],
"prefix_name": "",
"first_name": "Riccardo",
"middle_name": "",
"last_name": "Marcuccilli",
"job_title": "Principal Technical Writer",
"company_name": "Constant Contact",
"home_phone": "555-555-5555",
"work_phone": "888-987-2225",
"custom_fields": [],
"created_date": "2013-01-18T21:45:22.000Z",
"modified_date": "2014-09-12T15:42:06.000Z",
"source_details": ""
}
]
}