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

  1. {
  2. "addresses": [
  3. {
  4. "address_type": "BUSINESS",
  5. "city": "Belleville",
  6. "country_code": "CA",
  7. "line1": "47 Shawmut Ave.",
  8. "line2": "Suite 404",
  9. "postal_code": "K8b 5W6",
  10. "state_code": "ON"
  11. }
  12. ],
  13. "lists": [
  14. {
  15. "id": "1"
  16. }
  17. ],
  18. "cell_phone": "555-555-5555",
  19. "company_name": "System Optimzations",
  20. "confirmed": false,
  21. "email_addresses": [
  22. {
  23. "email_address": "username1@example.com"
  24. }
  25. ],
  26. "fax": "555-555-5555",
  27. "first_name": "Ronald",
  28. "home_phone": "555-555-5555",
  29. "job_title": "Systems Analyst 3",
  30. "last_name": "Martone",
  31. "prefix_name": "Mr.",
  32. "work_phone": "555-555-5555"
  33. }

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

  1. {
  2. "id": "2123940120",
  3. "status": "ACTIVE",
  4. "fax": "555-555-5555",
  5. "addresses": [
  6. {
  7. "id": "083d59b0-9b43-11e4-85a6-d4ae529a826e",
  8. "line1": "47 Shawmut Ave.",
  9. "line2": "Suite 404",
  10. "city": "Belleville",
  11. "address_type": "BUSINESS",
  12. "state_code": "ON",
  13. "state": "Ontario",
  14. "country_code": "ca",
  15. "postal_code": "K8bn",
  16. "sub_postal_code": "5W6"
  17. }
  18. ],
  19. "notes": [],
  20. "confirmed": false,
  21. "lists": [
  22. {
  23. "id": "1805463771",
  24. "status": "ACTIVE"
  25. }
  26. ],
  27. "source": "API",
  28. "email_addresses": [
  29. {
  30. "id": "0830d690-9b43-11e4-85a6-d4ae529a826e",
  31. "status": "ACTIVE",
  32. "confirm_status": "NO_CONFIRMATION_REQUIRED",
  33. "opt_in_source": "ACTION_BY_OWNER",
  34. "opt_in_date": "2015-01-13T16:41:33.000Z",
  35. "email_address": "username1@example.com"
  36. }
  37. ],
  38. "prefix_name": "Mr.",
  39. "first_name": "Ronald",
  40. "last_name": "Martone",
  41. "job_title": "Systems Analyst 3",
  42. "company_name": "System Optimzations",
  43. "home_phone": "555-555-5555",
  44. "work_phone": "555-555-5555",
  45. "cell_phone": "555-555-5555",
  46. "custom_fields": [],
  47. "created_date": "2015-01-13T16:41:33.000Z",
  48. "modified_date": "2015-01-13T16:41:33.000Z",
  49. "source_details": "KeynoteTest"
  50. }