Our v3 API is now available! Learn more by visiting the v3 developer portal.

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 requiredcontacts:write

To create a new contact, the contact must have an email address and be assigned to a contact list. No other properties are required. Setting the action_by query parameter to ACTION_BY_VISITOR will trigger an Autoresponder message welcoming the new subscriber to your list. Learn more about Autoresponder.

There are several features of the new contact management system that are not currently supported in the API. Check here for the details.

Code Sample using the PHP SDK

$contact = new Contact();
   $contact->addEmail($_POST['Email']);
   $contact->addList("999999999");
   $contact->first_name = $_POST['Name'];
   $contact->company_name = $_POST['company_name']; 
   $contact->job_title = $_POST['Title'];
   $contact->work_phone = $_POST['Phone'];
   $state = $_POST['State'];
   $contact->addAddress(Address::create( array("address_type"=>"BUSINESS","line1"=>$street,
  "city"=>$city,"state"=>$state,"postal_code"=>$zip)));

Code Sample using Ruby SDK

#gem install constantcontact

require 'yaml'
require 'constantcontact'

class ContactExample

  def initialize()
    cnf = YAML::load(File.open('config/config.yml'))
    @cc = ConstantContact::Api.new(cnf['api_key'], cnf['oauth_token'])
  end

  def add_contact( contact_json )
    @cc.add_contact( contact_json )
  end

  def get_lists
    @cc.get_lists()
  end

end
class AddContactTest
  def do()
    contact_example = ContactExample.new
    contact_list = contact_example.get_lists[0].id
    puts "Add what email address?"
    email_address = gets.chomp
    puts "Adding #{email_address} to Contact List #{contact_list}"

    list_to_add_to = ConstantContact::Components::ContactList.new
    list_to_add_to.id = contact_list

    new_contact = ConstantContact::Components::Contact.new
    new_contact.add_email(ConstantContact::Components::EmailAddress.new(email_address))
    new_contact.add_list(list_to_add_to)
    new_contact.first_name = 'Example'
    new_contact.last_name = 'User'

    #input = "{ 'email_addresses':[{'email_address':'#{email_address}'}], 'lists':[{'id':'#{contact_list}'}], first_name':'Example', 'last_name':'User'}"
    #puts input
    puts new_contact.to_json

    puts contact_example.add_contact( new_contact ).to_json

  rescue RestClient::BadRequest => e
    puts "#{e.http_code} - #{e.http_body}"
  end
end
AddContactTest.new.do

POST: https://api.constantcontact.com/v2/contacts

Test API

name

type

default

description

action_by

query

ACTION_BY_OWNER

Identifies who originated the action of adding the contact:

  • ACTION_BY_OWNER - contact was added by the account and not the subscriber
  • ACTION_BY_VISITOR - contact was added by the contact

api_key

query

REQUIRED; The API key for the application

Example JSON Request BodyTOP

{
	"addresses": [
    {
      "address_type": "BUSINESS",
      "city": "Belleville",
      "country_code": "CA",
      "line1": "47 Shawmut Ave.",
      "line2": "Suite 404",
      "postal_code": "K8b 5W6",
      "state_code": "ON"
    }
	],
	"lists": [
		{
		"id": "1"
		}
	],
	  "cell_phone": "555-555-5555",
	  "company_name": "System Optimzations",
	  "confirmed": false,
	  "email_addresses": [
		{
		"email_address": "username1@example.com"
		}
	],
  "fax": "555-555-5555",
  "first_name": "Ronald",
  "home_phone": "555-555-5555",
  "job_title": "Systems Analyst 3",
  "last_name": "Martone",
  "prefix_name": "Mr.",
  "work_phone": "555-555-5555"
}

Response CodesTOP

code

description

201

Contact was successfully created

400

Either JSON was malformed or there was a data validation error

401

Authentication failure

406

Unsupported Accept Header value, must be application/json

409

The email address provided is already in use

415

Unsupported content-type in the header, use application/json

500

Internal server error occurred

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.

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. (Read Only)

contact_id

string

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

created_date

string

Date & time the contact was added, in ISO 8601 format (Read Only)

+ 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.

+ email_addresses

array

REQUIRED. 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.

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

id

string

Unique ID for the contact (Read Only)

job_title

string (50)

The contact's job title

last_name

string (50)

The contact's last name

+ lists

array

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

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. (Read Only)

+ notes

array

A note associated with the contact.

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. (Read Only)

source_details

string (255)

Name of the application used to add contact, if added using the API (Read Only)

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.
(Read Only)

work_phone

string (50)

The contact's Work phone number

Example ResponseTOP

{
    "id": "2123940120",
    "status": "ACTIVE",
    "fax": "555-555-5555",
    "addresses": [
        {
            "id": "083d59b0-9b43-11e4-85a6-d4ae529a826e",
            "line1": "47 Shawmut Ave.",
            "line2": "Suite 404",
            "city": "Belleville",
            "address_type": "BUSINESS",
            "state_code": "ON",
            "state": "Ontario",
            "country_code": "ca",
            "postal_code": "K8bn",
            "sub_postal_code": "5W6"
        }
    ],
    "notes": [],
    "confirmed": false,
    "lists": [
        {
            "id": "1805463771",
            "status": "ACTIVE"
        }
    ],
    "source": "API",
    "email_addresses": [
        {
            "id": "0830d690-9b43-11e4-85a6-d4ae529a826e",
            "status": "ACTIVE",
            "confirm_status": "NO_CONFIRMATION_REQUIRED",
            "opt_in_source": "ACTION_BY_OWNER",
            "opt_in_date": "2015-01-13T16:41:33.000Z",
            "email_address": "username1@example.com"
        }
    ],
    "prefix_name": "Mr.",
    "first_name": "Ronald",
    "last_name": "Martone",
    "job_title": "Systems Analyst 3",
    "company_name": "System Optimzations",
    "home_phone": "555-555-5555",
    "work_phone": "555-555-5555",
    "cell_phone": "555-555-5555",
    "custom_fields": [],
    "created_date": "2015-01-13T16:41:33.000Z",
    "modified_date": "2015-01-13T16:41:33.000Z",
    "source_details": "KeynoteTest"
}