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

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][contacts_overview.html#contact-object-and-subresources] about core properties and subresources.

New contact_id Format in V3

contact_id values are formatted as UUIDs (Universally Unique IDentifier) format, 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 (Universally Unique IDentifier) format, see [RFC 4122](https://tools.ietf.org/html/rfc4122). 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; 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
Not used 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 up to 25 custom_fields. An account can have up to 100 total custom fields. The V2 API only supports 15 custom fields total. This section calls out custom_fields-related differences between the V2 and V3 definitions. The V3 API has a separate set of endpoints for managing custom_fields; only a subset of the custom_field object properties are available using the contact endpoints.

V3 Contact Property V3 Definition V2 Equivalent
custom_fields
custom_field_id
The custom_field unique identifier, in UUID format. None
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

`list_id` values are formatted as UUIDs (Universally Unique IDentifier) format, 8-4-4-4-12 for a total of 36 characters (32 alphanumeric characters and four hyphens). The V2 format was string.

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 (Universally Unique IDentifier) format, 8-4-4-4-12 for a total of 36 characters 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 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
A contact can only have one street address in V3. addresses (V2 supports 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 - 2
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 For More Info
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

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

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