This topic compares the V3 and V2 contact resource properties, calling out changes developers need to be aware of.

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.

You can have up to 100 custom fields at a time in your account.
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

Notes are not supported in the V3 API, use 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_addesses 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 contact_sequence_numbers 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 contact_sequence_numbers 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.

The V3 Contact ID Xref endpoint is a migration tool designed for limited usage. Developers should use this endpoint to to cross-reference each contact in a user's account just ONCE. It is NOT intended for regular and repeated use.

Example V3 Cross-reference Request

GET https://api.cc.email/contacts/contacts_id_xrefs?contact_sequence_numbers=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/contacts/contacts_id_xrefs');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'contact_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/contacts/contacts_id_xrefs?contact_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/contacts/contacts_id_xrefs?contact_sequence_numbers=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",
      "contact_sequence_number": "12345678"
    },
    {
      "contact_id": "88888888-9999-1111-9f7f-888888888888",
      "contact_sequence_number": "23456789"
    },
    {
      "contact_id": "88888888-9999-1111-4444-888888888888",
      "contact_sequence_number": "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": ""
    }
  ]
}