Getting Started with the icontact API

Transcription

1 Getting Started with the icontact API Contents - Introduction URIs, URLs, Resources, and Supported Actions Contacts Category... 3 Messages Category... 4 Track Category... 4 GET... 5 POST... 5 PUT... 5 DELETE Creating a Sandbox Account Register and Enable Your Application API Headers Account ID & Client Folder ID Some Common Examples Create a List Create a Contact Subscribe a Contact Create a Message Support for the icontact API P age

2 - Introduction - The purpose of this document is to give a step by step process on how to get started with using the icontact API as well as give some basic examples of calls you can make to it for various information. It should be stated ahead of time that to use the API, we recommend strong working knowledge of a web programming language such as PHP. icontact does not provide project management services at this time, so many of our API users will find it necessary to hire a developer to work on their API project. First we need to start with some basic information that will help with understanding what the API is, what can be done with it, and the policies concerning it. - API stands for Application Programming Interface and is defined as a particular set of rules ( code ) and specifications that software programs can follow to communicate with each other. In this case the software programs in question are the one(s) you are developing/using and the icontact application. - Communication to and from the icontact API can be in only two different programming languages XML (Extensible Markup Language) and JSON (JavaScript Object Notation). - The API is most commonly used for Contact, List and Subscription Management purposes (adding, deleting, and modifying Contacts). However, it can also be used to create messages and view message statistics. - Sandbox accounts can be opened for testing your application without affecting any real data in your production account. The Sandbox is merely a testing environment. NOTE: Sandbox accounts are only available to paid customers even though the API itself is available to all customers, Paid, Trial, and Free. - To use the icontact API, you must adhere to icontact s Terms and Conditions 1. In addition, you must also adhere to the icontact API s request limiting and throttling limits (see next note). Failure to adhere to these conditions may cause icontact to revoke your AppId or to disable your icontact account. - The request limit for the icontact API is 75,000 requests in a 24 hour period, with a maximum of 10,000 requests per hour. If you exceed the 75,000 requests per 24 hour period, you should wait 1 minute before making another API request. If you exceed 10,000 requests per hour, you should wait at least 1 second before making another API request. NOTE: If you exceed the request limit, we will respond with a 503 error code for any additional requests P age

3 - URIs, URLs, Resources, and Supported Actions - When the acronyms URI or URL are used in reference to the API they are referring to the web addresses that requests (or calls ) are sent to. Once all of the necessary access information is gathered (see steps below) you will use the appropriate URI/URL for the action you desire to take through the API. The URIs/URLs vary based on which Resource you are making a call to. There are seventeen Resources that fall under three main categories that you can make calls to: Contacts Category 1) Client Folders Resource ( - The client folders resource allows access to information in the client folders within an account. Every icontact account contains at least one client folder, however some accounts contain multiple client folders. The client folder contains all information regarding a specific client, including messages, lists, sends, segments, subscribers, etc. 2) Contacts Resource ( - Use the contacts resource to create and view contacts, edit information about individual contacts, and edit information about multiple contacts. 3) Custom Fields Resource ( - Custom fields allow an icontact user to store contact information other than the standard fields provided by the system. For example, you might include a region custom field that describes the geographical region in which a contact resides. 4) Subscriptions Resource ( - Subscriptions map the relationship between a contact and a list. 5) Uploads Resource ( - Use this resource to upload a list of contacts that exist in a.csv or.xls file. 6) Segments Resource ( - Segments define a saved search of contacts on a given list, allowing you to send to just the subscribers in that saved search. Use the segments resource to create, edit, and delete segments. 7) Segment Criteria Resource ( - Get and modify criteria for segments. 8) Lists Resource ( - Use the lists resource to modify subscriber lists. 3 P age

4 Messages Category 1) Sends Resource ( - The sends resource defines an event: the date and time on which an is sent through icontact. This includes s that are scheduled to be sent in the future. 2) Campaigns Resource ( - Campaigns allow you to modify users sending profile and the address to their blogs and archives. 3) Messages Resource ( - A message is any marketing communication created within icontact. Track Category 1) Message Bounces Resource ( - Gather tracking data on how often specific s are bouncing. 2) Message Clicks Resource ( - Use the message clicks resource to gather data on how many usersclicked the links in your s, and also who clicked the links. 3) Message Opens Resource ( - This resource tracks the number of times an was opened by subscribers. 4) Statistics Resource ( - Use the statistics resource to gather data on specific s, including: bounces, clicks, forwards, delivered, unsubscribed, opens, comments, complaints 5) Unsubscribes Resource ( - Provides data on who unsubscribed from a list. 6) Contact History Resource ( - Use this resource to access data contained on the Contact History pages. As mentioned above there are URIs/URLs associated with each of the seventeen Resources above. There are only four different actions that can be performed in the icontact API, though. Not all actions can be performed in all seventeen Resources 2. The four supported actions (also known as requests or calls ) are: 2 For information on which actions each Resource supports click on the link next to the Resource Name above to be taken to those pages in the icontact Developer Portal. 4 P age

5 GET Used primarily to retrieve general or specific information from your account using one of the supported Resources. Examples included retrieving lists of contacts, specific contacts, messages, subscriptions, etc. POST Used primarily to add new data to your account. Examples include adding new contacts, modifying subscriptions, creating new messages, and initiating message sends. PUT Used primarily to overwrite existing data. Examples include moving contacts from one list to another list or uploading a list of contacts. DELETE Used to delete information from the account. Now that you are familiar with the basics of understanding and using the icontact API we can move on to how to start using it. All of the screenshots below are going to be either of the icontact application and/or website itself, or of an application called RESTClient, which is available from 3. The responses received by the icontact API are displayed in XML and therefore may appear differently if you are using a program that uses JSON. 3 (The version used is under the Downloads section to the left P age

6 - Creating a Sandbox Account - As mentioned in the Introduction above, Sandbox accounts are only available to paid customers. Trial and Free Edition customers are free to use the API itself but cannot open a Sandbox account. If you are not a paid customer you can skip the steps in this section and move on to the Register Your Application section below. Follow these steps to create an icontact Sandbox account: (1) Visit the icontact Developer Portal at and click on the Sandbox Login link: 6 P age

7 (2) On the following page click on the link that says If you need a Sandbox login, Sign Up : (3) On the following page enter in your icontact Username and Password for your paid account into the spaces provided. You will also need to read and agree to icontact's Sandbox Terms of Service 4. When you have finished entering this information click the Proceed to the next step button: P age

8 (4) On the following page you will enter in your desired Sandbox login information. This includes a Sandbox Username, Password, and Magic Recipient Address 5. When you have finished entering this information click the Sign Up button : You have successfully set up your icontact Sandbox account! Proceed to the next section to acquire the necessary information to access the icontact API. - Register and Enable Your Application - Each application that attempts to access the icontact API needs to have a unique identifier known as the Application ID or Application Key. To acquire this Application ID you must register your application with icontact. Use the following steps to register your application: (1) Visit (This is for your main Production account. For a Sandbox account visit instead. The subsequent steps are the same. To retrieve your Application ID at any time after generating it you will visit these same links.) 5 The Magic Recipient Address is where all broadcast messages sent from the Sandbox account will be sent to no matter how many contacts or which list(s) you choose. 8 P age

9 (2) On the following page enter in your desired Application Name and Description. Both of these are required fields. (NOTE: The Application Name and Description cannot be changed once entered) When you have finished entering that information click the Get App ID button. (NOTE: There can only be one AppId per account): (3) The following page will repeat your Application Name and Description and give you the option to choose between API 2.0 and 1.0 (make sure 2.0 is selected). It also has your 32-character API-AppId under the heading API 2.0 Authentication. Write down this information somewhere and save it for future use: 9 P age

10 (4) After you have written down your application information click on the link that says enable this AppId for your account : (5) Enabling your AppId for your account entails setting up a password that is specific to that AppId. Type your desired password into the space provided and click the Save button. 10 P age

11 You have successfully generated and enabled an Application ID (AppId/Key) for your account! - API Headers - If you have completed all of the steps above you have most of the information you need to start communicating with the icontact API. To initiate a connection with the icontact API you must provide valid headers. The necessary header information is as follows: Accept: [this value can be either text/xml (for XML) or application/json (for JSON)] Content-Type: [this value can be either text/xml (for XML) or application/json (for JSON)] API-Version: [this value can be either 2.0, 2.1, or 2.2] API-AppId: [this value is the 32-Character Application ID you generated and enabled above] API-Username: [this value is your Production account username (or your Sandbox account username if you are making calls to your Sandbox account)] API-Password: [this value is the password you created when enabling your Application ID above not your Production or Sandbox account password] Here is a sample set of header information: Accept: text/xml Content-Type: text/xml API-Version: 2.2 API-AppId: VDRXdzy2IkS35Ma4GVS6I5HGjlfUl88X API-Username: icontactisawesome API-Password: mysupersecurepassword With all of this information you can now initiate a connection with icontact via the API. [IMPORTANT NOTE: If you are attempting to make calls to your Production account and are getting an Invalid Username error make sure to check the case of the characters in your username. When accessing your Production account via the API the API-Username in your headers is case-sensitive. It is not case-sensitive when you are trying to access the Sandbox. If you need to verify the case of your Username send a request to api@icontact.com and API Support will you the accurate information.] - Account ID & Client Folder ID - Using the accurate header information you can now retrieve the last two necessary pieces of information to govern your account via the API. Each account in icontact is assigned its own Account ID. Within each account there can be one or more Client Folders, each of which has their own ID. Standard accounts have one 11 P age

12 Client Folder ID whereas Agency accounts can have multiple IDs. Use the following steps to retrieve your Account and Client Folder IDs: (1) Account ID a. For Sandbox account make a GET call to and the response will contain a tag with your accountid. The response from the RESTClient below is in xml: b. For Production account make a GET call to and the response will contain a tag with your accountid. The only thing that changes is the URI/URL that you make the call to. The response will be formatted the same (except with different information): 12 P age

13 (2) Client Folder ID Using the accountid you can now acquire the clientfolderid: a. For Sandbox account make a GET call to and the response will contain a tag with your clientfolderid. The response from the RESTClient below is in xml: b. For Production account make a GET call to and the response will contain a tag with your clientfolderid. The only thing that changes is the URI/URL that you make the call to. The response will look the same (except with different information): 13 P age

14 Now that you have your accountid and clientfolderid numbers you have the full URI/URL necessary to use all Resources in the icontact API: For Sandbox accounts: For Production accounts: Fill in the {accountid} and {clientfolderid} sections in the URIs/URLs above with the information you retrieved when making the GET calls and you are good to go! - Some Common Examples - The most common uses of the icontact API is to create lists, create new contacts, subscribe those contacts to a list or lists, and create messages. Below are examples of how to do each in both XML and JSON (in blue font). These examples are considered the Body of text passed through the API. Obviously the text contained in each example would need to be modified to match your specific contacts information. For information on what each of the fields mean, click on the name of the corresponding resource above to find the information in the icontact Developer Portal. Create a List XML: <lists> <list> <name>list NAME HERE</name> <description>list DESCRIPTION HERE</description> < owneronchange>1</ owneronchange> <welcomeonmanualadd>1</welcomeonmanualadd> <welcomeonsignupadd>0</welcomeonsignupadd> <welcomemessageid>desired WELCOME MESSAGE ID HERE</welcomeMessageId> </list> </lists> 14 P age JSON: [ { "name":"list NAME HERE", "description":"list DESCRIPTION HERE", " owneronchange":1, "welcomeonmanualadd":1, "welcomeonsignupadd":0, "welcomemessageid":desired WELCOME MESSAGE ID HERE } ]

15 Create a Contact (NOTE: a Subscriptions request is still necessary after creating a contact to add them to a particular list or lists.) XML: <contacts> <contact> < >j.contact@ .com</ > <prefix> </prefix> <firstname>joe</firstname> <lastname>contact</lastname> <suffix></suffix> <street>123 Main St.</street> <city>somewhere</city> <state>ny</state> <postalcode>999999</postalcode> <phone> </phone> <business>icontact</business> <status>normal</status> </contact> </contacts> JSON: [ { " ":"j.contact@ .com", "prefix":"", "firstname":"joe", "lastname":"contact", "suffix":"", "street":"123 Main St.", "city":"somewhere", "state":"ny", "postalcode":99999, "phone": , "business":"icontact", "status":"normal" } ] 15 P age

16 Subscribe a Contact XML: <subscriptions> <subscription> <contactid>contact ID HERE</contactId> <listid>list ID HERE</listId> <status>normal</status> </subscription> </subscriptions> JSON [ { "contactid":contact ID HERE, "listid":list ID HERE, "status":"normal" } ] Create a Message XML: <messages> <message> <campaignid>campaign ID HERE</campaignId> <subject>message SUBJECT HERE</subject> <messagetype>normal</messagetype> <messagename>message NAME HERE</messageName> <htmlbody><![cdata[<p>html CONTENT HERE </p>]]></htmlbody> <textbody>text CONTENT HERE</textBody> </message> </messages> 16 P age JSON: { "messages":[ { "campaignid":campaign ID HERE, "subject":"message SUBJECT HERE", "messagetype":"normal", "messagename":"message NAME HERE", "htmlbody":"html CONTENT HERE", "textbody":"text CONTENT HERE"

17 } ] } - Support for the icontact API - For more information on the icontact API you can visit If you cannot find the answer(s) to your question(s) there you may contact api@icontact.com or call and our trained Technical Specialists will provide you with our award-winning Customer Support. Thank you for choosing icontact for your and Social Marketing Provider, and thank you for using the icontact API! 17 P age