Zulu edm API Handbook

Size: px

Start display at page:

Download "Zulu edm API Handbook"

Carol Leonard
5 years ago
Views:

1 Zulu edm API Handbook Prepared by Wesley Wright 21 st March 2016 Version 1.0 Page 1 of 13

2 CONTENTS OVERVIEW... 3 API ACCESS... 4 API KEY... 4 LOGIN CREDENTIALS... 4 API REQUEST PARAMETER ORDER... 4 GENERIC ERROR RESPONSE CODES... 5 CONTACT OPERATIONS... 6 Contacts.AddContact... 6 Contacts.GetContactsByGroup... 8 GROUP OPERATIONS... 9 Groups.AddContactToGroup... 9 Groups.RemoveContactFromGroup... 9 Groups.GetListing Groups.EditGroup CAMPAIGN OPERATIONS Campaigns.GetSentCampaigns Campaigns.GetCampaignInteractions Page 2 of 13

3 OVERVIEW This document outlines the functions and operations available via the Zulu edm API. The API provides access to some of the data and features of your Zulu edm account via a SOAP based platform. Whilst not all platform data is made available via the API, it is hoped that the available functions will provide some meaningful data endpoints for integrating into your own custom applications. If there is something within the edm platform you specifically need access too that isn t specified within the API documentation, please feel free to contact us to see if we can cater for this through either further API development or a custom integrated solution. *Note: The Zulu edm API is only available on certain versions of the software. Please contact us if you require access to the API to discuss your requirements further. Page 3 of 13

4 API ACCESS The API is accessed via SOAP calls made to various function endpoints (as specified further down in the document). All requests made to the API must include an account API Key as well as valid edm Username and Password credentials belonging to the account you are trying to access. Common apikey Yes String kv97ywef97yhw5efh34876wefar Account API Key user Yes String John!son1 Username of the Administrator making the request pass Yes String sdhagsd&3j# Password of the Administrator making the request API KEY Each edm account is assigned an individual and unique API Key which identifies which edm account to access and execute the functions on at the time of receiving the request. LOGIN CREDENTIALS Login credentials must be provided in each API request and are the same as those used to login to the web application as normal via your web browser. API REQUEST PARAMETER ORDER Please note that for API versions 1.0 ( and 1.1 ( all parameters listed in this document must be specified in the order as they appear. Page 4 of 13

5 GENERIC ERROR RESPONSE CODES API methods will respond with a designated code dependent on the result of the action requested. There are several Generic response codes that can be returned regardless of which API method is called. The details of these response codes are listed below: Code Description 201 API Key 202 Invalid Username provided 203 Invalid Password provided Page 5 of 13

6 CONTACT OPERATIONS Listed below are the methods available to interact with the contacts section of the platform. Contacts.AddContact Endpoint: Description: This function is used to add and edit contacts within the system. (*Note: If an address that exists is provided in the request, the existing contact record is updated) *Please note: All parameters specified below in the request parameter table must be built in an associative array format as displayed below and the $data value passed as the first parameter to the API function. E.g. $data[] = array('field' $data[] = array('field' $data[] = array('field' $data[] = array('field' => 'firstname', 'value' => 'Jason') => 'lastname', 'value' => 'Mc\'Allindon'); => 'country', 'value' => 'Sudan'); => ' ', 'value' => 'test @test .org') /* Add the Contact to the System */ $result = $client-> soapcall('contacts.addcontact', array( )); 'apikey' => $apikey, 'user' => $username, 'pass' => $password, 'data' => $data title No String Mrs Title firstname No String Jason First Name lastname No String Mc Allindon Last Name Yes String test @test .org Address telephone No String (08) Home Phone Number workphone No String Work Phone Number mobilephone No String Mobile Phone Number fax No String Fax Number dateofbirth No String Contacts Date of Birth (YYYY-MM-DD) address1 No String 51 Yellow Street Address Line 1 address2 No String Address Line 2 city No String Murray Bridge City of residence state No String VIC State of residence Page 6 of 13

7 postcode No String 7293 Postcode of residence country No String Sudan Country of residence companyname No String Mc Allindon & Co Pty Ltd The Company this Contact belongs to subscribed No String No subscription status (Yes or No) doubleopted-in No String No Contact double opt-in status (Yes or No) Code Description 401 Address invalid or not provided Sample Code <?php /* API Credentials */ $apiurl = ' $apikey = 'apikey'; $username = 'username'; $password = 'password'; /* Create a SOAP Client Object */ $client = new SoapClient($apiURL, array('trace' => 1, 'cache_wsdl' => WSDL_CACHE_NONE)); /* Setup the Contact Array of Details */ $data[] = array('field' => 'firstname', 'value' => 'First Name'); $data[] = array('field' => 'lastname', 'value' => 'Last Name'); $data[] = array('field' => 'country', 'value' => 'Argentina'); $data[] = array('field' => ' ', 'value' => 'test @ test.com'); $data[] = array('field' => 'telephone', 'value' => ' '); $data[] = array('field' => 'subscribed', 'value' => '1'); $result = null; try { /* Add the Contact to the System */ $result = $client-> soapcall('contacts.addcontact', array( )); 'apikey' => $apikey, 'user' => $username, 'pass' => $password, 'data' => $data if ($result->status === '101') { // Contact Successfully Added/Updated */ /* The contactid variable returned is the primary key of the generated or updated user //$result->contactid Page 7 of 13

$} echo '<pre>'; var_dump($result); echo '</pre>'; } catch (SoapFault $soapfault) { } var_dump($soapfault->faultcode); Sample Response Contacts.GetContactsByGroup Endpoint: https://api.au.zuluedm.$

8 } echo '<pre>'; var_dump($result); echo '</pre>'; } catch (SoapFault $soapfault) { } var_dump($soapfault->faultcode); Sample Response Contacts.GetContactsByGroup Endpoint: Description: This function is used to retrieve contacts within a specified group in the system. key Yes String id The key to base group contact retrieval on (id or name) value Yes String 17 The key value to use to retrieve contacts for the specified group (A number when using ID as the key and a String when using group name as the key) start Yes Integer 0 Starting point for record limiting (same functionality as the first value of an SQL limit clause) limit Yes Integer 100 Limit of records to retrieve (same functionality as the second value of an SQL limit clause) Code Description 207 Invalid record limiting parameters provided 250 Invalid key parameter provided. Only id or name are valid options Page 8 of 13

9 GROUP OPERATIONS Listed below are the methods available to interact with the groups section of the platform. Groups.AddContactToGroup Endpoint: Description: This function is used to add a contact to a group. group_id Yes Integer 17 Group Primary Key people_id Yes Integer 1652 Contact Primary Key Code Description 251 Invalid Group ID specified 402 Invalid Contact ID specified Sample Code <?php /* API Credentials */ $apiurl = ' $apikey = 'apikey'; $username = 'username'; $password = 'password'; /* Create a SOAP Client Object */ $client = new SoapClient($apiURL, array('trace' => 1, 'cache_wsdl' => WSDL_CACHE_NONE)); $result = null; try { /* Add the Contact to the System */ $result = $client-> soapcall('groups.addcontacttogroup', array( )); 'apikey' => $apikey, 'user' => $username, 'pass' => $password, 'group_id' => 3, 'people_id' => 6 if ($result->status === '101') { } // Contact Successfully Added to Group echo '<pre>'; Page 9 of 13

10 var_dump($result); echo '</pre>'; } catch (SoapFault $soapfault) { } var_dump($soapfault); Sample Response Groups.RemoveContactFromGroup Endpoint: Description: This function is used to remove a contact from the specified group. group_id Yes Integer 17 Group Primary Key people_id Yes Integer 1652 Contact Primary Key Code Description 406 Contact is not a member of the given group Groups.GetListing Endpoint: Description: This function is used to retrieve the list of groups within the system. groupcount Yes Boolean 0 Whether to include the count of contacts in the groups (1 or 0) treetype Yes String h Whether to retrieve groups orders by the hierarchy or just alphabetically ( h for hierarchy, a for alphabetical) Code Description Page 10 of 13

11 309 Invalid Tree Type requested. Only h or a are valid options Groups.EditGroup Endpoint: Description: This function is used to create or edit a group. id Yes Integer 17 Group Primary Key. If 0 or a non-existent id is passed, a new group will be created otherwise the group with the given ID will be edited name Yes String My new group The name of the group description Yes String My new group s description The description of the group public Yes Boolean 1 Whether this group will appear as selectable on the subscription dashboard (1 for public group, 0 for nonpublic groups) parent Yes Integer 0 The parent group id for this group (0 is a top level group) Code Description 365 Group Name must be specified Page 11 of 13

12 CAMPAIGN OPERATIONS Listed below are the methods available to interact with the campaigns section of the platform. Campaigns.GetSentCampaigns Endpoint: Description: This function is used to retrieve the list of sent campaigns in a given folder. categoryid Yes Integer 0 The campaign category to retrieve sent campaigns from Code Description Campaigns.GetCampaignInteractions Endpoint: Description: This function is used to retrieve all interactions of the given type for the campaign specified. campaignid Yes Integer 14 The Primary Key of the Campaign interactiontype No String click_throughs The type of interaction to retrieve. click_throughs, opens, unsubscribes, hard_bounces, soft_bounces and bounces are the valid options. opens is the default value Code Description 720 Campaign ID specified doesn t exist Sample Code Page 12 of 13

13 Sample Response Page 13 of 13

Go to SQA Academy the website address is

Go to SQA Academy the website address is Joining a course on the SQA Academy You may find it useful to print out this document for reference. There are two steps to joining an SQA Academy course. First you need an account with the SQA Academy,