Home › Constant Contact Web Service APIs › REST API Reference

Contacts Collection (find, create, modify or delete individual contacts)

Thu, 06/26/2008 - 17:42 — Anonymous

The Contacts collection is used to list, create, modify and delete Contacts (also known as subscribers) and to associate and disassociate Contacts and Contact Lists.

The Contacts collection resource is designed to be used only with small sets of contacts (ie. 24 or less). To manage large groups of contacts, use the Activities API resource. (As discussed in the Constant Contact API Terms and Conditions, intentional and unintentional misuse of this discrete API to frequently manage large sets of contacts is subject to API access or account termination).

Retrieving a Collection

To retrieve the collection of contacts for the UserName joesflowers, you perform an HTTP GET on the collection URI, http://api.constantcontact.com/ws/customers/joesflowers/contacts in this example, which returns the following XML document:

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts</id>
  <title type="text">Contacts for Customer joesflowers</title>
  <link href="" />
  <link href="" rel="self" />
  <author>
    <name>joesflowers</name>
  </author>
  <updated>2008-07-15T17:40:28.374Z</updated>
  <link href="/ws/customers/joesflowers/contacts?next=fihuckra" rel="next" />
  <link href="/ws/customers/joesflowers/contacts" rel="first" />
  <link href="/ws/customers/joesflowers/contacts" rel="current" />
  <entry>
    <link href="/ws/customers/joesflowers/contacts/1806" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/1806</id>
    <title type="text">Contact: u92204@example.com</title>
    <updated>2008-07-15T17:40:28.544Z</updated>
    <content type="application/vnd.ctct+xml">
      <Contact xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/1806">
        <Status>Active</Status>
        <EmailAddress>u92204@example.com</EmailAddress>
        <EmailType>HTML</EmailType>
        <Name></Name>
        <OptInTime>2008-07-15T15:14:53.219Z</OptInTime>
        <OptInSource>ACTION_BY_CONTACT</OptInSource>
      </Contact>
    </content>
  </entry>
  <entry>
    <link href="/ws/customers/joesflowers/contacts/1805" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/1805</id>
    <title type="text">Contact: u89439@example.com</title>
    <updated>2008-07-15T17:40:28.548Z</updated>
    <content type="application/vnd.ctct+xml">
      <Contact xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/1805">
        <Status>Active</Status>
        <EmailAddress>u89439@example.com</EmailAddress>
        <EmailType>HTML</EmailType>
        <Name></Name>
        <OptInTime>2008-07-15T15:14:51.172Z</OptInTime>
        <OptInSource>ACTION_BY_CUSTOMER</OptInSource>
      </Contact>
    </content>
  </entry>
</feed>

 

The response is made up of a feed element which contains some metadata about the feed followed by a series of entry elements. Each entry is made up of some metadata followed by a content element. Inside the content element is a Contact element which describes some of the important attributes of a particular contact.

Note that in order to get all the data about a particular contact, you must get the individual entry, which contains the complete entry data.

The structure of the Atom elements is described in detail by RFC 4287. The structure of the Contact element is described below.

 

Querying the Contacts Collection

To find particular Contacts you can query the collection by adding a query parameter to the collection's URI. So to look up the entry for the Contact with email address u89439@example.com, you would GET http://api.constantcontact.com/ws/customers/joesflowers/contacts?email=u89439%40example.com. (Note that the '@' sign in the email address must be properly URL encoded.) If a contact with that email exists, the query will return a feed containing the Contact entry for that email address, including a reference to the URI for the Contact details. If no Contact with that email address exists, the API will return either a 500 error (Server Error) code or will return an empty feed (i.e. a feed with no entries).

You can find multiple contacts with a single query by simply adding additional parameters: http://api.constantcontact.com/ws/customers/joesflowers/contacts?email=u89439%40example.com&email=u10432%40example.com. Just like before, the returned feed will contain entries for any Contacts that are found. Any that don't exist will simply be skipped.

Note that the email must be an exact match, including case! Since all email addresses in Constant Contact are stored in lowercase, please lowercase the email address you use for your query parameter.

The email parameter is the only query currently supported. More query types may be added in the future.

 

Retrieving an Individual Contact

An individual Contact entry may be retrieved by issuing an HTTP GET to the entry's URI. The URI may be obtained from the Location header after creating a new entry or from the link element with rel="edit" attribute in an existing entry.

If you don't have a link to an entry, you can find it by querying the collection.

A typical entry looks like this:

<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/contacts/1454" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/1454</id>
  <title type="text">Contact: u86597@example.com</title>
  <updated>2008-06-23T06:46:30.078Z</updated>
  <content type="application/vnd.ctct+xml">
    <Contact xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/1454">
      <Status>Active</Status>
      <EmailAddress>u86597@example.com</EmailAddress>
      <EmailType>HTML</EmailType>
      <Name>First Last</Name>
      <FirstName>First</FirstName>
      <MiddleName></MiddleName>
      <LastName>Last</LastName>
      <JobTitle></JobTitle>
      <CompanyName></CompanyName>
      <HomePhone></HomePhone>
      <WorkPhone></WorkPhone>
      <Addr1></Addr1>
      <Addr2></Addr2>
      <Addr3></Addr3>
      <City></City>
      <StateCode></StateCode>
      <StateName></StateName>
      <CountryCode></CountryCode>
      <CountryName></CountryName>
      <PostalCode></PostalCode>
      <SubPostalCode></SubPostalCode>
      <Note></Note>
      <CustomField1></CustomField1>
      <CustomField2></CustomField2>
      <CustomField3></CustomField3>
      <CustomField4></CustomField4>
      <CustomField5></CustomField5>
      <CustomField6></CustomField6>
      <CustomField7></CustomField7>
      <CustomField8></CustomField8>
      <CustomField9></CustomField9>
      <CustomField10></CustomField10>
      <CustomField11></CustomField11>
      <CustomField12></CustomField12>
      <CustomField13></CustomField13>
      <CustomField14></CustomField14>
      <CustomField15></CustomField15>
      <ContactLists>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1">
          <link xmlns="http://www.w3.org/2005/Atom" href="http://api.constantcontact.com/ws/customers/joesflowers/lists/1" rel="self" />
          <OptInSource>ACTION_BY_CUSTOMER</OptInSource>
          <OptInTime>2008-06-23T06:46:30.000Z</OptInTime>
        </ContactList>
      </ContactLists>
      <Confirmed>false</Confirmed>
      <InsertTime>2008-06-23T06:46:29.984Z</InsertTime>
      <LastUpdateTime>2008-06-23T06:46:30.078Z</LastUpdateTime>
    </Contact>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts</id>
    <title type="text">Contacts for Customer joesflowers</title>
    <link href="" />
    <link href="" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2008-07-16T16:54:49.524Z</updated>
  </source>
</entry>

 

Creating a New Contact

A new contact is created by making an HTTP POST to the collection URI. The POST body must contain an Atom entry element that includes the content for the new contact. The Content-Type of the request must be set to application/atom+xml.

<entry xmlns="http://www.w3.org/2005/Atom">
  <title type="text"> </title>
  <updated>2008-07-23T14:21:06.407Z</updated>
  <author></author>
  <id>data:,none</id>
  <summary type="text">Contact</summary>
  <content type="application/vnd.ctct+xml">
    <Contact xmlns="http://ws.constantcontact.com/ns/1.0/">
      <EmailAddress>test101@example.com</EmailAddress>
      <FirstName>First</FirstName>
      <LastName>Last</LastName>
      <OptInSource>ACTION_BY_CONTACT</OptInSource>
      <ContactLists>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1" />
      </ContactLists>
    </Contact>
  </content>
</entry>

Note that the id, title, author and updated elements must be present in the XML in order to conform to the Atom specification, even though their values will be replaced by the server. The title and author elements may be empty. The id must contain a URI, but since the value is not used by the server, any URI will work. The server does not check for uniqueness. The updated element must contain a date or date/time value, but again the value is not used by the server.

If the new Contact is created successfully, the server will return an HTTP status of 201 Created. The HTTP Location header in the response will contain the URI of the newly created Contact, and the entity body returned will be the entry for the Contact, including server-generated values like ids and links, with the result being that the returned response looks very much like what would be returned by a GET of the newly created contact's URI. Note that valid State Codes can be found here. State Code and Country must be consistent.

 

Updating a Contact

A Contact is updated by issuing an HTTP PUT to the entry's URI. The PUT body must contain an Atom entry element with the changed content for the contact.  The best way to achieve a successful update is to use the XML from a GET operation on the contact you want to update, modify the contents, and use it as the XML body in your PUT request.

 

Adding or Removing a Contact from a List

Contacts are added to or removed from lists by adding or removing ContactList elements from the ContactLists element, then PUT'ting the entry back to its edit URI. See below an example of the XML required to associate existing contact u86597@example.com with Contact Lists 1, 11, 12 and 14 in the joesflowersaccount. Note that after the PUT, contact u86597@example.com will be on ONLY Contact Lists 1, 11, 12 and 14 and will be removed from any other lists the contact was on previously.

<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/101</id>
  <title type="text">Contact: u86597@example.com</title>
  <updated>2008-04-25T19:29:06.096Z</updated>
  <author> </author>
  <content type="application/vnd.ctct+xml">
    <Contact xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/101">
      <EmailAddress>u86597@example.com</EmailAddress>
      <OptInSource>ACTION_BY_CUSTOMER</OptInSource>
      <ContactLists>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1"></ContactList>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/11"></ContactList>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/12"></ContactList>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/14"></ContactList>
      </ContactLists>
    </Contact>
  </content>
</entry>

Note that the OptInSource element is required, and must be ACTION_BY_CUSTOMER for any Contact List which is not included on the SignUp Form for the Account Owner.

 

Removing a Contact

To remove a contact from all lists, simply remove all of the ContactList elements from the ContactLists element.  Removing a contact does not mean that the contact has unsubscribed or opted out of receiving emails.  It means the contact simply does not belong to any particular contact list, and can be added back to a list by the account owner.  However, this API should not be used if the contact has unsubscribed from receiving all emails.  Instead, you should follow the instructions below in "Opting-out a Contact" section.

Opting-out a Contact

A Contact is opted-out by issuing an HTTP DELETE to the entry's URI. The call will return 204 No Content if it succeeds. This should be used if the contact has decided to unsubscribe from receiving all emails or has asked to stop sending all emails.  Opted-out Contacts become members of the do-not-mail special list.

Opting-in a Contact

Contacts who have opted out of receiving all mails and have been placed on Do-Not-Mail list must opt themselves in.  The account owner cannot add a contact in Do-Not-Mail list back to a different list.  When using the API, that means that the OptInSource must be ACTION_BY_CONTACT. Applications may only use the ACTION_BY_CONTACT OptInSource when the API call is the direct result of an action performed by the Contact (e.g. clicking a Subscribe button in an application). It is a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API in any other way.

Contact Data Format

Name Allowed values Description
Status Active, Unconfirmed, Removed, or Do Not Mail (read-only) Describes the current status of the Contact.
EmailAddress string(80) A valid email address
EmailType HTML or Text The preferred type of email
Name string (read-only) Read-only concatenation of FirstName and LastName
FirstName string(50)  
MiddleName string(50)  
LastName string(50)  
JobTitle string(50)  
CompanyName string(50)  
HomePhone string(50)  
WorkPhone string(50)  
Addr1 string(50)  
Addr2 string(50)  
Addr3 string(50)  
City string(50)  
StateCode string(2) Must be a valid US/Canada State Code and must be consistent with CountryCode. See: http://ui.constantcontact.com/CCSubscriberAddFileFormat.jsp#states.
StateName string(50)  
CountryCode string(2) Must be a valid two character, lower case, Country Code. See: http://constantcontact.custhelp.com/cgi-bin/constantcontact.cfg/php/enduser/std_adp.php?p_faqid=3614
CountryName string(50)  
PostalCode string(25)  
SubPostalCode string(25)  
Note string(500) Customer notes field. This field should only be visible to the Customer but not to the Contact.
CustomField[1-15] string(50)  
ContactLists 0 or more ContactList elements (see table below) Indicates which lists the Contact belongs to
OptInTime Date/Time (read-only) The time the Contact opted-in
OptInSource ACTION_BY_CUSTOMER, ACTION_BY_CONTACT The source of the opt-in
OptOutTime Date/Time (read-only) The time the Contact opted-in
OptOutSource ACTION_BY_CUSTOMER, ACTION_BY_CONTACT Source of the opt-out
OptOutReason Text (read-only) The time the Contact opted-out, if provided
Confirmed true or false (read-only)  
InsertTime Date/Time (read-only)  
LastUpdateTime Date/Time (read-only)  

ContactList Data Format

Name Allowed values Description
atom:link   atom:link identifies the href attribute of this element links to a contact list
OptInTime Date/Time (read-only) OptInTime identifies the time the Contact opted-in to this list
OptInSource ACTION_BY_CUSTOMER, ACTION_BY_CONTACT OptInSource identifies the source of the opt-in to this list as either the "CUSTOMER" (the Account Owner) or the "CONTACT" (the subscriber themself).

Contacts who are added with "ACTION_BY_CUSTOMER" do not receive a welcome email. This value MUST be used whenever the contact is being added by anyone other than the contact themselves. Contacts who are added with "ACTION_BY_CUSTOMER" will receive AutoResponder sequences based on the settings of the list they are being added to. Contacts who are added with "ACTION_BY_CUSTOMER" are not included on your "Visitor Signup Report".

Contacts who are added with "ACTION_BY_CONTACT" receive a welcome email. This value *CAN ONLY* be used if the contact is being added as a direct result of an action by the contact themselves (ie they are adding themselves via a public web form). Contacts who are added with "ACTION_BY_CONTACT" will receive AutoResponder sequences. Contacts who are added with "ACTION_BY_CONTACT" are included on your "Visitor Signup Report".

Invalid values for OptInSource, including providing incorrect case of the constant values (ACTION_BY_CUSTOMER, ACTION_BY_CONTACT) may result in an http response of "500: Server Error".