Contacts V3 Changes and Migration

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.

Email Address

The email_address object defines the user's email address. Differences with the V2 email_addresses array are called out here:

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.

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.

Notes

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.

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.

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.

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

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();

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.

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