Developer Portal & Documentation


webservices

Contacts Collection and Resource

by Administrator on ‎03-25-2011 04:12 PM

Contacts Collection

 

The Contacts collection represents a list of contacts (subscribers) that have been added to an account.  By performing a GET operation, you retrieve a list of contacts.  By performing a POST operation, you can add a new contact.

 

Request Format - Retrieving [the first 50] Contacts

 

GET https://api.constantcontact.com/ws/customers/{user-name}/contacts

 

Response Format

 

<?xml version='1.0' encoding='UTF-8'?>
<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="contacts" />
  <link href="contacts" rel="self" />
  <author>
    <name>joesflowers</name>
  </author>
  <updated>2009-11-19T14:49:21.928Z</updated>
  <link href="/ws/customers/joesflowers/contacts?next=g24umerp-fymhqg" 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/21930" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/21930</id>
    <title type="text">Contact: 1258642119407@example.com</title>
    <updated>2009-11-19T14:49:23.203Z</updated>
    <author>
      <name>Constant Contact</name>
    </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/21930">
        <Status>Active</Status>
        <EmailAddress>1258642119407@example.com</EmailAddress>
        <EmailType>HTML</EmailType>
        <Name>Customer 1</Name>
        <OptInTime>2009-11-19T14:48:41.761Z</OptInTime>
        <OptInSource>ACTION_BY_CONTACT</OptInSource>
      </Contact>
    </content>
  </entry>
  <entry>
    <link href="/ws/customers/joesflowers/contacts/21929" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/21929</id>
    <title type="text">Contact: 1258641848349@example.com</title>
    <updated>2009-11-19T14:49:23.204Z</updated>
    <author>
      <name>Constant Contact</name>
    </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/21929">
        <Status>Active</Status>
        <EmailAddress>1258641848349@example.com</EmailAddress>
        <EmailType>HTML</EmailType>
        <Name>Customer 2</Name>
        <OptInTime>2009-11-19T14:44:10.873Z</OptInTime>
        <OptInSource>ACTION_BY_CONTACT</OptInSource>
      </Contact>
    </content>
  </entry>
</feed>

 

Request Format - Creating a Contact

 

POST https://api.constantcontact.com/ws/customers/{user-name}/contacts

 

<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>test_100@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.

 

Contact Resource

 

The Contact resource represents a contact.  Using the Contact resource, you can get the detailed information about a contact or edit a contact's information, including the list subscription.

 

Request Format - Retrieving a Contact

 

GET https://api.constantcontact.com/ws/customers/{user-name}/contacts/{contact-id}

 

Response Format

 

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/contacts/22199" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/22199</id>
  <title type="text">Contact: joe@example.com</title>
  <updated>2009-11-20T20:41:19.243Z</updated>
  <author>
    <name>Constant Contact</name>
  </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/22199">
      <Status>Active</Status>
      <EmailAddress>joe@example.com</EmailAddress>
      <EmailType>HTML</EmailType>
      <Name>Customer Joe</Name>
      <FirstName>Joe</FirstName>
      <MiddleName></MiddleName>
      <LastName>Smith</LastName>
      <JobTitle></JobTitle>
      <CompanyName></CompanyName>
      <HomePhone></HomePhone>
      <WorkPhone></WorkPhone>
      <Addr1></Addr1>
      <Addr2></Addr2>
      <Addr3></Addr3>
      <City></City>
      <StateCode>MA</StateCode>
      <StateName>Massachusetts</StateName>
      <CountryCode>us</CountryCode>
      <CountryName>United States</CountryName>
      <PostalCode>02154</PostalCode>
      <SubPostalCode>1781</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/3">
          <link xmlns="http://www.w3.org/2005/Atom" href="/ws/customers/joesflowers/lists/3" rel="self" />
          <OptInSource>ACTION_BY_CONTACT</OptInSource>
          <OptInTime>2009-11-20T20:41:06.595Z</OptInTime>
        </ContactList>
      </ContactLists>
      <Confirmed>false</Confirmed>
      <InsertTime>2009-11-20T20:41:06.593Z</InsertTime>
      <LastUpdateTime>2009-11-20T20:41:19.243Z</LastUpdateTime>
    </Contact>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts</id>
    <title type="text">Contacts for Customer: joesflowers</title>
    <link href="contacts" />
    <link href="contacts" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2009-11-20T20:45:44.199Z</updated>
  </source>
</entry>

Request Format - Updating a Contact

 

PUT https://api.constantcontact.com/ws/customers/{user-name}/contacts/{contact-id}

 

The request must be accompanied by an XML body, which should include all elements from a GET operation on a contact

 

 URI Format

 

URI ComponentDescription
user-name

The account owner's Constant Contact user name.
Value must be in lower case.

contacts

You can query contacts using several query parameters.

To find a contact by an email address, use the following format:

contacts?email={email-address}

The email-address must be URL-encoded (i.e. @ is represented as %40).

 

To find contacts based on their last updated date for a particular list type, use the following format:

contacts?updatedsince{time}&listtype={list-type}

 

The supported list types are:

  • active: returns all active contacts (ones in one or more contact lists)
  • removed: returns all contacts that do not belong to any contact list, but have not unsubscribed
  • do-not-mail: returns all contacts who have unsubscribed from receiving your emails

 

To find contacts based on their last updated date for a particular list, use the following format:

contacts?updatedsince{time}&listid={numeric-list-id}

The numeric list-id is obtained by taking the last number out of the list ID given in <id> element of a contact list.

 

The time must be in UTC and follow the Atom specification: {year}-{month}-{day}T{hour}:{minute}:{second}.{milliseconds}Z

contact-id

 Represents an individual contact

It can be obtained from the Location header after creating a new <entry> or from <link> element that has in the rel="edit" attribute in an existing <entry> of Contacts collection.

 

Contact Data Format

 

NameAllowed valuesEditable?Description
Status Active, Unconfirmed, Removed, or Do Not Mail No Describes the current status of the Contact.
EmailAddress string(80) Yes A valid email address
EmailType HTML or Text Yes The preferred type of email
Name string No Read-only concatenation of FirstName and LastName
FirstName string(50) Yes  
MiddleName string(50) Yes  
LastName string(50) Yes  
JobTitle string(50) Yes  
CompanyName string(50) Yes  
HomePhone string(50) Yes  
WorkPhone string(50) Yes  
Addr1 string(50) Yes  
Addr2 string(50) Yes  
Addr3 string(50) Yes  
City string(50) Yes  
StateCode string(2) Yes 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) Yes  
CountryCode string(2) Yes 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) Yes  
PostalCode string(25) Yes  
SubPostalCode string(25) Yes  
Note string(500) Yes Customer notes field. This field should only be visible to the Customer but not to the Contact.
CustomField[1-15] string(50) Yes  
ContactLists 0 or more ContactList elements (see table below) Yes Indicates which lists the Contact belongs to
OptInTime Date/Time No The time the Contact opted-in
OptInSource ACTION_BY_CUSTOMER, ACTION_BY_CONTACT Yes The source of the opt-in
OptOutTime Date/Time No The time the Contact opted-out
OptOutSource ACTION_BY_CUSTOMER, ACTION_BY_CONTACT Yes Source of the opt-out
OptOutReason Text No The time the Contact opted-out, if provided
Confirmed true or false No  
InsertTime Date/Time No  
LastUpdateTime Date/Time No  

 

ContactList Data Format

 

NameAllowed valuesEditableDescription
atom:link   No atom:link identifies the href attribute of this element links to a contact list
OptInTime Date/Time No OptInTime identifies the time the Contact opted-in to this list
OptInSource ACTION_BY_CUSTOMER, ACTION_BY_CONTACT Yes 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".

0 Votes