Contacts Collection | Constant Contact Developer

Contacts Collection Endpoint

Use this endpoint to retrieve (GET) contacts in the user's account, or to create (POST) a new contact.

Methods:

Click a method to view its documentation

GET POST

DescriptionTOP

Privileges: contacts:read

Retrieves one or more contacts in the account, depending on the query parameters used:

All contacts in a user's account (no query parameters used)
A specific contact specified by the email query parameter

URL encode the email address, as with all query parameters values, to ensure proper system response.
The API is not able to return a contact by email address call if a contact's email address has been deleted in the product UI.

Only the contacts that have been modified on or after the date/time specified by the modified_since query parameter. This is useful for syncing contacts across applications.
Only the contacts with a status specified by the status query parameter.

name	type	default	description
GET: https://api.constantcontact.com/v2/contacts
Test API
api_key	query		REQUIRED; The API key for the application
email	query		Optional - specify the EXACT contact by email address to retrieve information for
include_contact_id	query	false	Boolean; `include_contact_id=true` `returns the uuid formatted contact_id property, which is the list unique identifier in the V3 API. Useful for migrating V2 API integrations to the V3 API.`
limit	query	50	Specifies the number of results displayed per page of output, from 1 - 500, default = 50. See Paginated Output for more information on using `limit`.
modified_since	query		Use to retrieve a list of only contacts that have been modified since the date and time specified in ISO-8601 format
status	query	ALL	Use to retrieve a list of contacts with a specific status; status values are: ALL - default, returns all contacts ACTIVE - Contact is an active member of a contact list UNCONFIRMED: Contact has not confirmed their email address yet and the account cannot send campaigns to them until they confirm OPTOUT: Contact has unsubscribed from a mailing list and is on the Do Not Mail list. See Using the Contacts API for information on opting contacts back in REMOVED: Contact has been removed from all contact lists by the account, but can be added back to a contact list

Response CodesTOP

code	description
200	Request was successful
401	Authentication failure
404	Contact not found for specified ID
406	Unsupported Accept Header value, must be application/json
500	Internal server error

StructureTOP

property

type(max length)

description

+ addresses

array

Mail addresses for the contact. API currently supports a maximum of 2 addresses, 1 PERSONAL and 1 BUSINESS. It is possible to create up to 10 physical addresses using the product GUI. The API ignores any additional PERSONAL and BUSINESS addresses, and it ignores any other address_type.

address_type	string	REQUIRED when including an address; Mailing address type, valid values are PERSONAL, BUSINESS
city	string (50)	The city of the contact's address
country_code	string (2)	Standard ISO 3166-1 2-letter country code for the contact
id	string	Unique ID for the physical address
line1	string (50)	Street Address line 1
line2	string (50)	Street Address line 2
postal_code	string (25)	The contact's Postal ZIP code. NOTE: For postal codes that contain white space between characters, the characters after the first white space are broken out into the `sub_postal_code` field.
state	string (50)	This field accepts any state or province name. However, if a valid 2 letter US state or Canadian province is entered in the `state_code` field, the system resolves the code to a state or province and overwrites any name manually entered in this field.
state_code	string (2)	Standard 2 letter abbreviation for contact's state or Canadian province; if state_code is entered, the system overwrites the `state` property with the resolved US state or Canadien province name.
sub_postal_code	string (25)	Use if Contact address has a sub-Postal ZIP code. See NOTE in postal_code about ZIP codes with white spaces.

cell_phone

string (50)

The contact's cell phone number

company_name

string (50)

The contact's company

confirmed

boolean

Confirmed = true if the contact has confirmed their email subscription, and it is false if they have not.

contact_id

string

The uuid formatted contact unique identifier used in the V3 API. Useful for migrating V2 API integrations to the V3 API.

created_date

string

Date & time the contact was added, in ISO 8601 format

+ custom_fields

array

You can create up to 15 custom fields for a contact. The API currently only supports the custom field format described here. If the account uses the new contact management system, it is possible to create custom fields with varying formats. The API ignores custom fields not using the format below.

label	string (50)	This read-only field displays the custom_field name entered using the product GUI, the value is displayed only if it matches the custom_field_n (n=1-15) format.
name	string	You must name each custom field custom_field_1, custom_field_2,...custom_field_15. Only custom fields with values are shown in response to a GET call.
value	string (50)	Content of the custom field

+ email_addresses

array

Array of contact's email addresses, Currently only one email address is supported for each contact. If the account uses the new contact management system, it is possible to create more than 1 email address per contact using the product GUI. The API ignores additional email addresses.

confirm_status	string	Confirmed status of the email address, valid values: CONFIRMED: contact has confirmed their email address and subscription; a CONFIRMED email address cannot be edited NO_CONFIRMATION_REQUIRED: Contact has been added by the account with prior permission UNCONFIRMED: Contact has not yet confirmed their email address and subscription to a list with Constant Contact
email_address	string (80)	Contact's email address, cannot exceed 80 characters
id	string	Unique ID for the email address
opt_in_date	string	The date that the contact was added, in ISO-8601 format
opt_in_source	string	Describes how the contact was added to the account, valid values are: ACTION_BY_VISITOR - the contact added him/herself by clicking a Subscribe button or other action ACTION_BY_OWNER - the account owner or other user authorized on the account added the contact ACTION_BY_SYSTEM - the contact was added by a Constant Contact representative at the request of the account owner or authorized user. NOTE: Do not include OPT_IN_SOURCE=ACTION_BY_SYSTEM when making a PUT call to update a contact that has this setting; Do not use ACTION_BY_SYSTEM with the action_by query parameter, in both cases the API will respond with a 400 error. This value is set automatically when the contact is created, and cannot be edited. It's value must match the `action_by` value; if not set on POST, it takes on value of `action_by` property
opt_out_date	string	If the contact has a status of OPTOUT, this field displays the date the OPTOUT occurred
opt_out_source	string	If the contact has a status of OPTOUT, this field describes who initiated the optout action: ACTION_BY_VISITOR - the contact initiated the OPTOUT ACTION_BY_OWNER - the account owner or user initiated the OPTOUT
status	string	The email address status, valid values: ACTIVE: Contact is an active member of a contact list UNCONFIRMED: Contact has not confirmed their email address yet and the account cannot send campaigns to them until they confirm OPTOUT: Contact has unsubscribed from a contact list and is on the Do Not Mail list; the Constant Contact user cannot add them to a contact list. See Using the Contacts API for information on opting contacts back in. REMOVED: Contact has been taken off all contact lists, the Constant Contact user can add them to a contact list NON_SUBSCRIBER: someone who is not a contact, but has registered for an event the account has created TEMP_HOLD - the account owner has temporarily stopped sending campaigns to subscriber. Learn more here.

fax

string (50)

The contact's fax number

first_name

string (50)

The contact's first name

home_phone

string (50)

The contact's home phone number

string

Unique ID for the contact

job_title

string (50)

The contact's job title

last_name

string (50)

The contact's last name

+ lists

array

Array of the contact lists that the contact is a member of

string

Unique ID of contactlist the contact is a member of, you must include at least 1 list when making a POST.

status

string

Contact list status, valid values:

ACTIVE: List is the current default contactlist
HIDDEN - List is not the default contact list

modified_date

string

Date & time the contact was last updated, in ISO 8601 format; value is the same as created_date if contact has not been updated. Check here for a list of properties that, when changed or added, modify the modified_date value.

+ notes

array

A note associated with the contact.

created_date	string	Date the note was created, in ISO 8601 format
id	string	Unique ID for the note
modified_date	string	Date that the note was last modified, in ISO-8601 format; look here for a list of properties that, when added or modified, update the modified_date value.
note	string (500)	Text of the note

prefix_name

string (4)

Salutation (Mr., Ms., Sir, Mrs., Dr., etc)

source

string (50)

Describes how the contact was added, from an application, web page, etc.

source_details

string (255)

Name of the application used to add contact, if added using the API

status

string

Contact status, valid values are:

ACTIVE: Contact is an active member of a contact list and can receive campaigns
UNCONFIRMED: Contact has not confirmed their email address after subscribing and cannot receive campaigns
OPTOUT: Contact has unsubscribed from the contact list and is on the Do Not Mail list; they cannot be manually added to any contactlist
REMOVED: Contact has been taken off all contactlists, and can be added to a contactlist
NON_SUBSCRIBER: someone who is not a contact, but has registered for one of the account's events
VISITOR: a person who has "liked" one of the account's social campaign pages
TEMP_HOLD - the account owner has temporarily stopped sending campaigns to subscriber. Learn more here.

work_phone

string (50)

The contact's Work phone number

Example ResponseTOP


{
    "meta": {
        "pagination": {
            "next_link": "/v2/contacts?next=c3RhcnRBdD0zJmxpbWl0PTI"
        }
    },
    "results": [
        {
        "id": "196",
        "contact_id": "12345678-1234-1234-1234-123456789012",
        "status": "ACTIVE",
        "fax": "318-978-7575",
        "addresses": [
            {
                "id":"2",
                "line1": "47 Shawmut Ave.",
                "line2": "Suite 404",
                "city": "Boston",
                "address_type": "BUSINESS",
                "state":"Massachusetts",
                "state_code": "MA",
                "country_code": "us",
                "postal_code": "02158",
                "sub_postal_code": ""
            }
        ],
        "notes": [],
        "confirmed": false,
        "lists": [
            {
                "id": "1",
                "status": "ACTIVE"
            }
        ],
        "source": "API",
        "email_addresses": [
            {
                "id":"1",
                "status": "ACTIVE",
                "confirm_status": "NO_CONFIRMATION_REQUIRED",
                "opt_in_source": "ACTION_BY_VISITOR",
                "opt_in_date": "2013-01-23T13:48:44.108Z",
                "opt_out_date": "1969-12-31T19:00:00.000Z",
                "email_address": "rmartone@systems.com"
            }
        ],
        "prefix_name": "Mr.",
        "first_name": "Ronald",
        "last_name": "Martone",
        "job_title": "Systems Analyst 3",
        "company_name": "System Optimzations",
        "home_phone": "617-555-1212",
        "work_phone": "318-978-8896",
        "cell_phone": "448-989-3182",
        "custom_fields": [],
        "source_details": "New Contact Signup App"
		}
]
}