Our v3 API is now available! Learn more by visiting the v3 developer portal . Creating new v2 API keys is no longer supported.

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

Description TOP

Privileges required : contacts: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 Body TOP

{
	"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 Codes TOP

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

Structure TOP

property

type (max length)

description

Example Response TOP

{
    "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"
}