Traction API Reference Version Date Created. 23 March Page 1 of 106, Prepared 23 March 2009

Transcription

1 Traction API Reference Version 3.51 Date Created 23 March 2009 Page 1 of 106, Prepared 23 March 2009

2 Contents 1. Introduction to the Traction API Overview Supported Languages NET Developers Pack The Basics Functions and Their Uses Traction Accounts Traction Customer Records Customer Attributes Customer Matching & De-duplication Customer Interactions Matching Key Conflicts Customer Record Merging Implementing the API Installation Requirements Posting Method API Results API Security API Testing Customer Search Adding/Updating Customer Data Conflicts When Updating Customers TEXTAREA Attributes Customer Record Merging List A CUSTOMERTYPE Parameters Notes on Date and Time Formats Dates Times Notes on Mobile Phone Formats Regional Accounts International Accounts Dashes, Spaces, and Plus Signs Multilingual (Double-Byte) Issues Posting Multilingual Data to Traction Retrieving Multilingual Data from Traction Retrieving Multilingual TEXTAREA Attributes Add Customer API Summary Traction Requirements System Functionality Business Rules...23 Page 2 of 106, Prepared 23 March 2009

3 3.5 API Base References URL How It Works List A Post Parameters List B Result Codes List C Response Headers Retrieve Customer API Summary Traction Requirements Business Rules API Base References URL How It Works List A1 Post Parameters List A2 Post Parameter Values for ATTRID1..ATRIDn List B Result Codes List C Response Headers Customer Interaction API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works List A Post Parameters List B Result Codes List C Response Headers Customer Login API Summary System Functionality Business Rules API Base References URL How It Works List A1 Post Parameters List A2 Post Parameter Values for ATTRID1..ATRIDn List B Result Codes List C Response Headers Multiple Subscription API Summary Traction Requirements...37 Page 3 of 106, Prepared 23 March 2009

4 7.3 System Functionality Business Rules API Base References URL How It Works List A Post Parameters List B Result Codes List C Response Headers Prize Pool API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works List A Post Parameters List B Result Codes List C Response Headers Promotion API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works List A Post Parameters List B Result Codes List C Response Headers Promotion Group Report API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works List A Post Parameters List B Result Codes List C Response Headers Returned XML...50 Page 4 of 106, Prepared 23 March 2009

5 11. Send to a Friend API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works List A Post Parameters List B Result Codes List C Response Headers SMS Gateway API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works Returned XML List A Post Parameters List B Result Codes List C Response Headers Subscription API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works List A Post Parameters List B Result Codes List C Response Headers Survey API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works List A Post Parameters...63 Page 5 of 106, Prepared 23 March 2009

6 List B Result Codes List C Response Headers Voting API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works List A Post Parameters List B Result Codes List C Response Headers RSS Update API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works List A Post Parameters List B Result Codes List C Response Headers Broadcast Trigger API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works List A Post Parameters List B Result Codes List C Response Headers Snippet Upload API Summary Traction Requirements System Functionality Business Rules API Base References URL...74 Page 6 of 106, Prepared 23 March 2009

7 18.7 How It Works List A Post Parameters List B Result Codes List C Response Headers Snippet XML Schema Snippet XML Example Batch Customer Transfer API Suite File Upload API Summary Traction Requirements System Functionality Business Rules API Base References URL Typical API Workflow Diagram How It Works File Export API Summary Traction Requirements System Functionality Business Rules API Base References URL Typical API Workflow Diagram How It Works File Status API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works File Request API Summary Traction Requirements System Functionality Business Rules API Base References URL How It Works File Download API Summary...94 Page 7 of 106, Prepared 23 March 2009

8 Traction Requirements System Functionality Business Rules API Base References URL How It Works Appendix A Result Codes...96 Page 8 of 106, Prepared 23 March 2009

9 1. Introduction to the Traction API 1.1 Overview The Traction platform combines a customer database and digital campaign execution into a single platform. The platform supports web, mobile, and as digital channels, which can be combined to make engaging and innovative digital campaigns. The Traction API allows an application to interact with both of these parts of the platform. For example: Online newsletter registration forms, Online customer profile update forms, Online customer surveys, Online and SMS-based competitions, Online and SMS-based votes or instant polls, Combo online/sms campaigns, Custom SMS applications (although many SMS applications can be configured in the Traction interface without the need for the API). Because Traction is multi-channel, it is possible to combine the channels in a single campaign, e.g.: Web-to- , Web-to-SMS, SMS-to- . This allows for a variety of primary and auxiliary campaign functions such as: Online competition entries with an confirmation, Forgotten password reminder s, Arbitrary , SMS, or WAP notifications, Double-opt in loops for newsletter subscriptions. 1.2 Supported Languages The Traction API is uses standard HTTP web request/response pairs, meaning that any suitable development language may be used NET Developers Pack A.NET-specific wrapper known as the Traction.NET Developers Pack is also available, allowing development in managed VB or C# code. You can view the.net documentation and download the DLL and sample files here: Page 9 of 106, Prepared 23 March 2009

10 1.3 The Basics A typical API call consists of a function and a set of customer s details. There is a different API for different types of functions. There is typically a one-to-one relationship between an API and a type of Traction function, as shown in the following table: API Traction Function Notes Promotion API Promotion Voting API Vote Survey API Survey SMS Gateway API SMS Gateway Multi Subscription API Single Subscription API Subscription Prize Pool API Promotion Specialised version of Promotion API for returning instant prize win/lose statuses Add Customer API -- none -- For when no function is required There are also two APIs for retrieving a customer s details from Traction. API Traction Function Notes Retrieve Customer API -- none -- Customer Login API -- none -- Variant of Retrieve Customer has customer password validation Page 10 of 106, Prepared 23 March 2009

11 1.4 Functions and Their Uses The following table shows some of the uses for Traction functions. This list is by no means limiting. Some capabilities are available from the API and others via the interface (noted as appropriate in the table). Function Uses Technical Capabilities API Promotion Games of chance (competitions) Instant message responses Forgotten password Double-opt in confirmation Vote Votes Instant polls Games of skill (select the right answer for a chance to win) Survey Surveys Games of skill (e.g. 25-words-or-less) Receive entry from web Receive entry from SMS Trigger to entrant Trigger SMS to entrant Trigger WAP to entrant Mixed channels (web/sms/ ) Check entry code against uploaded list (multi-use or single use) Attach one or more prize pools (manual draw or instant win) For instant win, return winning status Update customer details Receive vote from web Receive vote from SMS Trigger to voter Trigger SMS to voter Trigger WAP to voter Attach one or more prize pools (manual draw or instant win) - attach at vote level or individual candidate level Update customer details For web, return vote tally Report on vote tally in interface Receive survey responses from web Report on response tally in interface Export responses via interface Update customer details Promotion API Prize Pool API (for instant win competitions) Voting API Survey API Subscription A subscription represents a channel of opt status (permission to contact). There are two opt models in Traction check with your Traction account manager for confirmation. Subscribe Unsubscribe Report on subscription growth via interface Update customer details Single Subscription API Multiple Subscription API Page 11 of 106, Prepared 23 March 2009

12 Function Uses Technical Capabilities API SMS Gateway Custom SMS campaigns Receive incoming SMS messages as XML Send outgoing SMS messages Your own business logic for processing incoming messages Update customer details SMS Gateway API Broadcast Bulk broadcasting Send to friend messaging Auto-triggered messaging Bulk broadcasting via interface or triggered by API Send individual from sender to any number of friends Send to Friend API Broadcast Trigger API RSS Update API Push RSS content into Traction for inclusion in s Update sender/recipient details SMS Broadcast Bulk SMS broadcasting Send to friend messaging Auto-triggered messaging RSS feed-triggered messaging Bulk SMS broadcasting via interface Send individual SMS from sender to any number of friends Send to Friend API RSS Update API Push RSS content into Traction and trigger SMS blast Update sender/recipient details WAP Broadcast Bulk WAP broadcasting Send to friend messaging Auto-triggered messaging Bulk WAP broadcasting via interface Send individual WAP from sender to any number of friends Send to Friend API Update sender/recipient details 1.5 Traction Accounts A Traction account is a database of customer records and associated functions. Typically you will have access to two accounts: a test account and a live (production) account. It is usual to do all testing in a test account and, once satisfied, reproduce the final functions in the live account. NOTE: Traction uses numeric ID values to reference customers, customer attributes, and functions. The IDs in a test account will be different to the IDs in a live account. TRACTION ACCOUNT = CUSTOMER DATABASE Page 12 of 106, Prepared 23 March 2009

13 1.6 Traction Customer Records Customer Attributes A customer record in Traction is stored as a series of customer attributes. Each Traction account can have a different set of attributes, although some attributes are set by default and available in all accounts. All attributes have a unique ID. Default attributes are referenced by a fixed code which is the same regardless of account for example FIRSTNAME for the default First Name attribute. See section on page 19 for a list of default attributes. New attributes can be defined on-the-fly in the Traction interface. They can be text, numeric, Boolean, dates, or pre-defined lists. When you update an existing customer record in Traction, old attribute values are replaced by the new ones. The old values are lost. TRACTION ATTRIBUTE = CUSTOMER DATA FIELD Customer Matching & De-duplication A customer may be identified in a Traction account by one of three unique attributes: address Mobile number External ID (e.g. a username or a URN from another database) Only one matching identifier is required for any one customer, and different records may use different identifiers in the same account. Whenever you supply a customer s details to Traction via an API call, you specify a matching key and a matching value. Traction will perform one or more actions: If the match value cannot be found, a new record is created. If the match value is found, that record s attributes are updated no new record is made. In both cases, the API will return the internal Traction ID for this customer. This field may be stored external to Traction for referential purposes if desired, and can also be used as a matching value for further updates to existing customers. (You cannot define an internal customer ID for creating a new customer). Rules on Updating Attributes: 1. You can add or update all attributes for a customer, just some attributes, or no attributes at all. 2. If an attribute definition is not passed to Traction, the attribute value for that customer is left as is. If the attribute definition is passed with no data, the attribute is blanked Customer Interactions As well as attributes, a customer record also stores an ever-growing list of interactions or events that describe how and when the customer has participated in marketing campaigns. For example: Page 13 of 106, Prepared 23 March 2009

14 Customer 1 12/08/ :25 Sent August newsletter 13/08/ :09 Opened August newsletter 13/08/ :10 Clicked link Website homepage In Traction, you can define your own types of interactions and add them to a customer record. This provides a mechanism for storing custom event information, e.g. product purchases, offline activities, linking to key web pages, attendance at events, and so on. For example (custom interactions shown in red): Customer 1 12/08/ :25 Sent August newsletter 13/08/ :09 Opened August newsletter 13/08/ :10 Clicked link Website homepage 13/08/ :20 Visited page Buy T-shirt 13/08/ :22 Completed purchase of T-shirt Interactions vs. Attributes Interactions describe events that have happened to the customer. They accrue over time for a customer. Attributes describe properties of the customer, for example their name, address, postal code, or gender. Attribute values are overwritten whenever the customer is updated Matching Key Conflicts , mobile, and external ID must be unique for every customer in a single Traction account. There is the possibility of conflicts if two customers attempt to claim the same value for one of these attributes. If a customer has values for two of the matchable attributes, it is possible that an update will result in a conflict between two customer records. In this scenario, the update will fail and the Traction API will return an error code. For example, say the following two customer records already exist in one account: Customer 1 Address @ .com Mobile Phone Customer An API call tries to send the following information to Traction: Matching key = Matching value = @ .com Update attribute Mobile to Traction locates Customer 1 because of the matching value, and tries to update it. However this results in a clash on the Mobile attribute, because it is already claimed by Customer 2 all matching attributes must be unique in a single account. To resolve this conflict, the clashing data may be stored into a regular attribute reserved for this purpose, e.g. you could make a Mobile2 attribute. See section on page 18 for more information. Page 14 of 106, Prepared 23 March 2009

15 1.6.5 Customer Record Merging Traction has some ability to merge a customer record if otherwise two would be created. For example, say the following customer exists in a Traction account: Address Mobile Phone Customer An API call tries to send the following information to Traction: Matching key = Matching value = @ .com Update attribute Mobile to Traction cannot locate a Traction customer because no such customer exists with @ .com as their address. However, because another primary identifier was supplied, Traction does a secondary search on mobile phone and identifies customer 3 this record is updated with the new details. Page 15 of 106, Prepared 23 March 2009

16 2. Implementing the API 2.1 Installation Requirements ASP developers may need to enable post/response connectivity with any servers that need to communicate with Traction. To test if you can connect from a given server, try using a web browser to if your browser returns a 405 Method Not Allowed response then you are able to post to Traction without any further setup. If you cannot, you will need to install an HTTP server. One such tool is CSHTTP.EXE. 2.2 Posting Method APIs accept only HTTP or HTTPS POST submissions from websites. All APIs live at API Results Results are returned to the website as Response Headers. All headers are prefixed with TRAC- All APIs return a TRAC-RESULT header which contains an integer result code for the submission. This integer represents the success or failure of the submission. If the TRAC-RESULT is 0 the API succeeded; if greater than 0 the API failed and if less than 0 the API succeeded with warnings. Result codes exist as a global list across all APIs; each API implements a subset of these codes which are relevant to their functionality. This ensures that no result code has duplicate meaning. If the Result code is greater than 0 an additional header called TRAC-ERROR is returned containing a human readable description of the error. If the API returns XML, this is streamed back to the website as the Response body. 2.4 API Security All APIs require a Web Endpoint to be specified to allow the website to access Traction. This must be configured in Traction and submitted with each post. The Web Endpoint consists of three pieces of information as follows. The first 3 parameters listed in all APIs validate the endpoint and are mandatory for all APIs: o USERID Web Endpoint username o PASSWORD Web Endpoint password o ENDPOINTID Web Endpoint ID The ENDPOINTID, USERID and PASSWORD are checked first before processing can continue. The username and password must match the username and password for the endpoint. If something is wrong with the credentials an error code of 1 (INVALID_LOGIN) is returned. NB. Error code 2 (ACCESS_DENIED) is now deprecated. Parameter Type Description USERID Text (50) Traction Web Endpoint Username PASSWORD Text (50) Traction Web Endpoint Password ENDPOINTID Integer Traction Web Endpoint ID 2.5 API Testing All APIs support a TEST parameter. If the TEST parameter is submitted with a value the API will process the submission and return the relevant result code without updating Traction. This is used to see if the API integration works without affecting data stored in Traction. For the data to be stored this parameter cannot be present. Page 16 of 106, Prepared 23 March 2009

17 2.6 Customer Search For an API to interact with a Traction Customer, a MATCHKEY and MATCHVALUE are required. The API uses the MATCHKEY and MATCHVALUE to determine if the Customer already exists within the Traction account or whether it is a new Customer. MATCHKEY values represent the 4 unique attributes of a customer. These unique attributes with the exception of CUSTOMERID are only unique at the account level. Possible MATCHKEY values are listed below: MATCHKEY E M X C MATCHVALUE Address Mobile Number External User ID Traction internal ID can only be used to update existing customers. The internal ID is returned in most API responses. If the MATCHVALUE is not found and the API allows Customer additions then a new customer is created in the account. The exception to this is if a MATCHKEY of C is used, in this case a CUSTOMER_NOT_FOUND error is returned. 2.7 Adding/Updating Customer Data When wanting to add or modify a customer, a CUSTOMERTYPE parameter must be used. A CUSTOMERTYPE field can contain multiple parameters. Each parameter has 2 parts the attribute name and the value separated by a pipe ( ). Each parameter pair must end with a CHR(31) character E.g. FIRSTNAME Bob + CHR(31) Custom Customer Attributes which have been added to an account can also be updated. To do this, use the custom attribute ID instead of the fixed attribute name. Custom Attribute IDs are listed in Traction, under Customer Attributes. For example, if you want to add a customer called Bob Jones whose Street Name is Wentworth Ave, determine the Traction ID of your custom Street Name attribute. If the value is 123, then a typical CUSTOMERTYPE string would be: FIRSTNAME Bob + CHR(31) + LASTNAME Jones + CHR(31) Wentworth Ave + CHR(31) For List type attributes, the attribute value should be the actual list text, e.g. Red. For Multilist attributes, the attribute value should be all selected list text strings separated by semicolons, e.g. Red;Blue. For Boolean attributes, the attribute value should be T for True and F for False. For all date/time attribute types, the date format must match that configured in your Traction account, e.g. if your account is configured for DD/MM/YYYY then send, e.g. 28/02/2006. Times must be represented in the time zone that is configured in your Traction account. Dates and times must always be provided as strings, e.g. 28/02/2006 or 28/02/ :30. To clear a value, include it in the parameter string but provide no value. If you don t want to overwrite an attribute s existing value DO NOT list it in the CUSTOMERTYPE string. If any of the Customer Data is invalid, you will receive a result code 6 (INVALID_CUSTOMER_DATA) and the entire submission will be rejected. Page 17 of 106, Prepared 23 March 2009

18 Fixed customer attribute IDs are provided in List A Conflicts When Updating Customers The , MOBILE, and EXTUSERID attributes are all primary customer identifiers in a Traction account, as these are the three primary ways in which a customer may be identified and matched by when posting customer details to Traction. This means that for every customer in an account, the , MOBILE, and EXTUSERID attributes have to be unique (or blank). Because of this, it is possible that conflicts will arise when updating customers. For instance, if you attempt to update the mobile of a customer (matching on their address) and another customer record already has that mobile number, a conflict will arise because two records cannot have the same mobile number. This conflict is represented as an error condition (codes 9, 10, or 11 see Appendix A on page 96 or the result codes list for an individual API). The reason for these constraints is due to the interactive nature of the Traction platform. For example, if a Traction account was able to have multiple records with the same address, you could not tell which customer record to update when a web submission was posted to Traction. With SMS entries the problem is more pronounced due to the limited information available in the submission. Because Traction has the ability to enter customers into competitions and win (potentially major) prizes, the need for uniqueness becomes apparent. A strategy for avoiding conflicts is to understand which communications channels have priority in your database, i.e. are you predominantly an or SMS broadcaster? In the case of priority, for instance, you can create a text attribute called Mobile2 and, in the case of a conflict, store the mobile number into this field. This way you collect the majority of mobile numbers into the default MOBILE field and collect them into Mobile2 only when a conflict occurs. This method will require two posts in the case of a conflict (one to detect the conflict and one to do the alternative post). Steps: 1. Attempt to post the data to Traction per normal, e.g. address in the attribute and mobile number in the MOBILE attribute. 2. If Traction returns a result code of 9, 10, or, 11, a conflict has occurred. Repost the customer s record keeping the address the same but using the Mobile2 attribute (you ll need its unique ID from Traction) TEXTAREA Attributes TEXTAREA attributes may store control characters such as linefeeds and carriage returns Posting to Traction It is recommended that you collect TEXTAREA data using a <textarea> web element. Data collected in this element will be stored correctly in Traction Retrieving from Traction Because Traction returns attribute values in response headers, extended characters such as carriage returns and multi-byte characters will be URL encoded in the response string. Ensure that you URL unencode any response strings from TEXTAREA attributes. For multi-byte characters, see also Multilingual (Double-Byte) Issues on page 21. Page 18 of 106, Prepared 23 March 2009

19 2.7.3 Customer Record Merging In some situations, Traction will identify a customer record as being a match even if you are not matching on that particular attribute. For instance, if you have an existing customer record with just a mobile number (no address), but then you post a customer to Traction matching on with the same mobile number, Traction will detect this and merge the details together in a single record. To elaborate: 1. Traction has a mobile-only record ( is blank). 2. You post a record to Traction, = something@somewhere.com, mobile = , matching on Traction will not see this as a conflict but will merge the data into a single record with the and mobile values. Traction will only merge records where there is no danger of data loss. Merging works with any combination of , MOBILE, and EXTUSERID fields List A CUSTOMERTYPE Parameters Fixed Attribute IDs Type Required Description FIRSTNAME Text (50) No Customer s First name LASTNAME Text (50) No Customer s Family name Text (100) No address of the Customer MOBILE Text (15) No Customer s Mobile phone number TITLE Text (5) No Customer s Title e.g. Mr., Ms. OPT Text (1) No Whether the Customer will be set for opt-in or opt-out. Must be I to receive s. Possible Values: I = opt-in O = opt-out B = opt-out blocked U = undefined (default) SMSOPT Text (1) No Whether the Customer will be set for opt-in or opt-out. Must be I to receive SMS messages. Possible Values: I = opt-in O = opt-out B = opt-out blocked U = undefined (default) EXTUSERID Text (50) No External identification code for Customer Page 19 of 106, Prepared 23 March 2009

20 Fixed Attribute IDs Type Required Description ACTIVE Text (1) No Whether the Customer is active in Traction Possible values: T active F not active PASSWORD Text (50) No External password for the Customer this is not a Traction password. 2.8 Notes on Date and Time Formats Dates When providing dates and times to Traction, you need to know the date format for which your Traction account is enabled. Typically it will be the same as your local time format, e.g. mm/dd/yyyy for North America, dd/mm/yyyy for Europe, Australia, New Zealand, and Asia. Contact your Traction administrator if you are unsure of the date format for your Traction account Times Times should be expressed in 24-hour time, e.g. 18:00 for 6:00 pm. Midnight (00:00) means the beginning, not the end, of a day the last minute in a day is 23: Notes on Mobile Phone Formats Your Traction account may be configured to be either a regional account or an international account. Please contact your Traction administrator if you are unsure of your account s setup Regional Accounts Accounts with a default region allow you to provide mobile numbers in local format, for example: UK region Australian region US region Traction will assume that any mobile number that starts with a zero is local, and will replace zero with the default country code. For example, in a UK-region account, will be stored as If the mobile number does not start with a zero, Traction assumes that the number includes the country code International Accounts International accounts have no default region. All mobile numbers provided to Traction must include the country code. Any number starting with a zero will be rejected if the mobile phone is the match value, error code 16 will be returned if the mobile phone forms part of the customer s profile data, error code 67 will be returned. (See Appendix A Result Codes on page 96 for more information). Page 20 of 106, Prepared 23 March 2009

21 2.9.3 Dashes, Spaces, and Plus Signs Non-numeric characters such as dashes, spaces, and plus signs are ignored by Traction. Providing them in mobile numbers will have no effect. For example, will be stripped by Traction and stored as Multilingual (Double-Byte) Issues The Traction database stores data in UTF-8 encoding which means that the majority of the world s languages and symbol sets can be stored as attribute data Posting Multilingual Data to Traction The encoding of all web forms that post multilingual data to Traction should be UTF-8, per the following example: <meta http-equiv="content-type" content="text/html; charset=utf-8"> If the character set is not UTF-8, Traction may misinterpret the encoding and store incorrect information Retrieving Multilingual Data from Traction Traction returns all information as web response headers, which are limited to the US-ASCII character set. In order to retrieve multilingual data, it is necessary to tell Traction to encode the response. Each API contains an ENCODE parameter which will, when included in the request, MIME encode the headers in accordance with RFC 1522 as a base-64 string. For example, if you request a customer s first name (stored as Fred ) with the ENCODE parameter, the response header value will be: =?UTF-8?B?RnJlZA==?= In accordance with RFC 1522, this string includes the encoding method as well as the data. The data itself is shown here in underline: =?UTF-8?B?RnJlZA==?= The UTF-8 decoding of this base-64 string will result in the text Fred. ALL parameters, including error codes and IDs, will be base-64 encoded if the ENCODE option is used. Page 21 of 106, Prepared 23 March 2009

22 Retrieving Multilingual TEXTAREA Attributes Because TEXTAREA attributes can also contain control characters such as line breaks, TEXTAREA values are always URL encoded to preserve these characters. When using the ENCODE parameter to retrieve customer data from TEXTAREAs, you will also have to URL decode the resulting string. See TEXTAREA Attributes on page 18 for more information. Page 22 of 106, Prepared 23 March 2009

23 3. Add Customer API 3.1 Summary The Customer API allows 3 rd party websites to add or update Traction Customers. 3.2 Traction Requirements Customer Attribute IDs for attributes being added/updated. A valid Web Endpoint 3.3 System Functionality Authentication: Checks that web endpoint exists in account and that username and password are correct Add Customer to Traction Updates Existing Customer Details 3.4 Business Rules Must have valid Web Endpoint Username and password must match endpoint details Customer details must be valid Customer must be identified by using a MATCH KEY/VALUE pair If customer doesn t exist add him/her to the account Only 1 customer can be submitted at a time. 3.5 API Base References Authorisation See section 2.4 for information on authorization requirements. Customer Data See section 2.7 for information on Customer Data requirements. 3.6 URL How It Works A 3rd party web site will gather the customer information and will pass that information to the Traction Add Customer API for recording. See List A for a full list of variables to pass. The Add Customer API will verify that the endpoint details are correct before continuing otherwise it will return an error. The API then searches for an existing customer in Traction using the MATCHKEY/VALUE details. If a customer is found that customer is updated with the details submitted in the CUSTOMER parameter. If not found a new customer is added to the Traction account. See List B for a full list of result codes. Page 23 of 106, Prepared 23 March 2009

24 3.7.1 List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID MATCHKEY Text (1) Yes Determines the type of data in the MatchValue parameter : E , M mobile, X external user ID, C customer ID MATCHVALUE Text (100) Yes The identifier for the customer type is determined by the matchkey, e.g.: Matchkey = E Matchvalue = somebody@company.com.au Matchkey = C Matchvalue = 9 Matchkey = M Matchvalue = 614XXXXXXXX CUSTOMER CUSTOMERTYPE (see section 2.7) No Collection of customer Attributes which need to be added/updated for the Customer ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result 0 Completed Success 1 Incorrect Login credentials Failed 5 Missing Required Data (ie. one of the required parameters in List A was missing Failed or empty) 6 Invalid Customer Data Failed 7 Customer Not Found Failed 9 Duplicate Customer (the address clashes with an existing customer Failed in Traction) 10 Duplicate Customer Mobile (the mobile number clashes with an existing Failed customer in Traction) 11 Duplicate Customer External User Id (the external user Id clashes with an Failed existing customer in Traction) 14 Invalid MatchKey Failed 15 Invalid Matchvalue Failed 16 Invalid Matchvalue Mobile Failed 17 Invalid Matchvalue External User Id Failed 18 Invalid Matchvalue CustomerId Failed 40 Invalid Customer Attribute Failed 41 Customer Data Error Length Failed Page 24 of 106, Prepared 23 March 2009

25 42 Customer Data Error Type Failed 43 Customer Data Error Item not Found Failed 44 Customer Data Error Mandatory Failed 67 Invalid Mobile Number Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if API submission has failed for any reason TRAC-CUSTOMERID Integer On success Returns the ID of the customer that has been created/updated TRAC-ATTR Text (100) On Customer Failure Returns the Attribute ID of the attribute which failed customer validation Page 25 of 106, Prepared 23 March 2009

26 4. Retrieve Customer API 4.1 Summary The Retrieve Customer API allows 3 rd party websites to retrieve a customer record from Traction, including attribute values and optionally the set of Subscriptions to which they are subscribed. Customer records may be retrieved by supplying a Traction Customer ID, mobile number, address or external ID. This API cannot automatically authenticate a customer. For automatic customer authentication using their external ID and password attributes, use the Customer Login API (see page 33). 4.2 Traction Requirements Check if customer exists Retrieve the values of attributes requested Optionally retrieve all Subscriptions that the customer is currently subscribed to 4.3 Business Rules Customer must be identified by using MATCH KEY/VALUE pair. Must have valid Web Endpoint, username and password must match endpoint details Customers are returned regardless of their ACTIVE flag. Any number of attributes may be requested, but the parameters must be numbered sequentially beginning with ATTRID1. Attribute values will be returned with the corresponding number, such as TRAC-ATTRVAL1. If the customer does not have a value for the attribute in Traction, the parameter will be returned with no value. If an error occurred retrieving an attribute value, a Warning message with the same number will be returned and no value parameter will be returned. If there are several warning messages, the Result code value will reflect the last message. The Customer ID will be returned on a successful request regardless of warnings issued. 4.4 API Base References Authorisation See section 2.4 for information on authorization requirements. Customer Searching - See section 2.6 for information on Customer searching requirements. 4.5 URL How It Works This API is used to retrieve a Traction customer s details, including selected attributes. The SUBSCRIPTIONS parameter determines whether the customer s current subscription status should also be returned. If set to TRUE, a comma-delimited list of Subscriptions is returned the list contains all currently live Subscriptions to which the customer is subscribed. If the customer is not subscribed to a Subscription, or if that Subscription is not live, it will not be included in the list List A1 Post Parameters Page 26 of 106, Prepared 23 March 2009

27 USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID MATCHKEY Text (1) Yes Determines the type of data in the MatchValue parameter : E , M mobile, X external user ID, C customer ID MATCHVALUE Text (100) Yes The identifier for customer type is determined by the matchkey, e.g.: Matchkey = E Matchvalue = somebody@company.com.au Matchkey = C Matchvalue = 9 Matchkey = M Matchvalue = 614XXXXXXXX ATTRID1 Varies See List A2 No Attribute ID 1 The Traction customer attribute ID of the requested attribute. ATTRIDn Varies No Attribute ID n See List A2 SUBSCRIPTIONS Boolean No Defaults to False. If TRUE, a comma-delimited list of Subscription IDs is returned which includes all live Subscriptions to which the customer is currently subscribed. ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No Supported but has no effect since the Traction database is not being modified List A2 Post Parameter Values for ATTRID1..ATRIDn Parameter Value FIRSTNAME LASTNAME TITLE MOBILE PASSWORD SMSOPT OPT EXTUSERID ACTIVE Description Customer s First name Customer s Family name Customer s Title e.g. Mr., Ms. Customer s Mobile phone number address of the Customer Password for the Customer SMS opt status for this customer. opt status for this customer. External identification code for Customer Whether the Customer is active in Traction Page 27 of 106, Prepared 23 March 2009

28 Parameter Value XXXX Description The numeric Attribute ID of the Custom Attribute which is to be returned List B Result Codes Result code Reason Result -4 WARNING - Multi list item not found for attribute Success -3 WARNING - List item not found for attribute Success -2 WARNING - Attribute not found in this account Success 0 Completed successfully Success 1 Incorrect Login credentials Failed 5 Missing Required Data Failed 7 Customer Not Found Failed 14 Invalid Match Key Failed 15 Invalid Match Value Failed 16 Invalid Match Value Mobile Failed 17 Invalid Match Value External User ID Failed 18 Invalid Match Value Customer ID Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers Parameter Type Returned Description TRAC-RESULT Integer Yes Result code see list B TRAC-ERROR Text (1000) On error Error Description TRAC- Integer On success Customer ID CUSTOMERID TRAC-ATTRVAL1 Text (500) On attribute success Value of Attribute ID 1 TRAC-ATTRVALn Text (500) On attribute success Value of Attribute ID n TRAC- SUBSCRIPTIONS Text (500) If SUBSCRIPTIONS parameter is TRUE Comma-delimited list of live Subscription IDs to which the customer is currently subscribed. TRAC-WARN1 Text (1000) On attribute error Warning message if unable to return TRAC-ATTRVAL1. TRAC-WARNn Text (1000) On attribute error Warning message if unable to return TRAC-ATTRVALn. Page 28 of 106, Prepared 23 March 2009

29 5. Customer Interaction API 5.1 Summary The Customer Interaction API allows 3 rd party websites to record interactions for Traction Customers. 5.2 Traction Requirements Existing Customer A valid Web Endpoint Customer Interaction Definitions 5.3 System Functionality Authentication: Checks that web endpoint exists in account and that username and password are correct Can add and or update one or more Customers in Traction Can add one or more interactions to each customer submitted 5.4 Business Rules Must have valid Web Endpoint Username and password must match endpoint details Customer details must be valid Customer must be identified by using a MATCH KEY/VALUE pair If customer doesn t exist add him/her to the account Only Custom Interactions can be added, not system interactions. Custom Interaction Id s must belong to the same account as the web endpoint and customer Optionally additional information can be passed for each interaction, this is then stored in the string parameter field and as part of the description. Optionally a specific function can be passed for each interaction, the interaction is then linked to that function which can have any status at this time. If no function is required users must pass 0 and the interaction will be linked to the default INTERNAL function Optionally an interaction date/time can be supplied use the timezone as defined in your Traction account. If omitted, the current date/time is used. 5.5 API Base References 5.6 URL Authorisation See section 2.4 for information on authorization requirements. Customer Data See section 2.7 for information on Customer Data requirements How It Works A 3rd party web site will gather the customer Information and will pass that information to the Traction Customer Interaction API for recording. See List A for a full list of variables to pass. The API will verify that the web endpoints details are correct before continuing otherwise it will return an error. See List B for a full list of result codes. Page 29 of 106, Prepared 23 March 2009

30 Users may pass in as many interactions as they would like; there is no restriction. Each interaction has 3 parts. FUNCTIONID INTERACTIONID EXTRAINFO So for example if the interaction with an ID of is to be attached to function 6268 with no extra information the interaction would be: INTERACTION1= If no specific function is required then 0 must be passed instead and the interaction will then be attached to the default INTERNAL function, i.e.: INTERACTION2= my extra information The FUNCTIONID (if not 0) must be valid but does not need to be approved; interactions can be added to functions with any status including Preliminary. If one interaction fails then all interactions fail. If a matchvalue, customer or interaction parameter value is invalid for any reason, an additional response header will be returned called TRAC-PARAMETER which will contain the parameter name of the invalid item. E.g. If INTERACTION2 contained asdf which is not a valid interaction TRAC-PARAMETER would equal INTERACTION List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID MATCHKEY Text (1) Yes Determines the type of data in the MatchValue parameter : E , M mobile, X external user ID, C customer ID MATCHVALUE1 Text (100) Yes The identifier for customer 1 type is determined by the matchkey, e.g.: Matchkey = E Matchvalue = somebody@company.com.au Matchkey = C Matchvalue = 9 Matchkey = M Matchvalue = 614XXXXXXXX MATCHVALUEn Text (100) Yes The identifier for customer n type is determined by the matchkey, e.g.: Matchkey = E Matchvalue = somebody@company.com.au Matchkey = C Matchvalue = 9 Matchkey = M Matchvalue = 614XXXXXXXX CUSTOMER1 CUSTOMERTYPE (see section 2.7) No Collection of customer Attributes which need to be added/updated for the Customer 1 CUSTOMERn CUSTOMERTYPE (see section 2.7) No Collection of customer Attributes which need to be added/updated for the Customer n Page 30 of 106, Prepared 23 March 2009

31 INTERACTION1 Text (100) Yes Contains the FunctionID (0 if not specific) Customer Interaction ID Additional String Value (optional max 50 chars) Eg whichpage/a.html called at 10am INTERACTIONn Text (100) Yes Contains the FunctionID (0 if not specific) Customer Interaction ID Additional String Value (optional max 50 chars) Eg whichpage/a.html called at 10am INTERACTIONDATE No An optional date and time for the interaction. The format is DATE TIME, where: DATE = date in Traction account format (DD/MM/YYYY or MM/DD/YYYY) TIME = time in 24-hour clock HH:MM or HH:MM:SS For example: 12/01/ :12:59 If time not present, 00:00 is used. Time is always local timezone per Traction account. If this parameter is blank, the current date/time is used. ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result 0 Completed Success 1 Incorrect Login credentials Failed 5 Missing Required Data (ie. one of the required parameters in List A was missing Failed or empty) 6 Invalid Customer Data Failed 7 Customer Not Found Failed 9 Duplicate Customer (the address clashes with an existing customer Failed in Traction) 10 Duplicate Customer Mobile (the mobile number clashes with an existing Failed customer in Traction) 11 Duplicate Customer External User Id (the external user Id clashes with an Failed existing customer in Traction) 14 Invalid MatchKey Failed 15 Invalid Matchvalue Failed 16 Invalid Matchvalue Mobile Failed Page 31 of 106, Prepared 23 March 2009

32 Result code Reason Result 17 Invalid Matchvalue External User Id Failed 18 Invalid Matchvalue CustomerId Failed 37 Invalid FunctionId Failed 38 Invalid InteractionId Failed 39 Invalid Extra Info string too long max 50chars Failed 40 Invalid Customer Attribute Failed 41 Customer Data Error Length Failed 42 Customer Data Error Type Failed 43 Customer Data Error Item not Found Failed 44 Customer Data Error Mandatory Failed 67 Invalid Mobile Number Failed 68 Invalid date/time format Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if the API has failed for any reason TRAC- CUSTOMERID1 TRAC- CUSTOMERIDn Integer On success Returns the ID of the first customer that has been created/updated Integer On success Returns the ID of the nth customer that has been created/updated TRAC-ATTR Text (100) On Failure due to Customer error TRAC-PARAMETER Text (20) On Failure due to Customer or MatchValue or Interaction error Returns the Attribute ID of the attribute which failed customer validation Returns the Customer PARAMETER name which failed customer validation eg. RECIPIENT1 Page 32 of 106, Prepared 23 March 2009

33 6. Customer Login API 6.1 Summary The Customer Login API is an interface that allows 3 rd party web sites to check that a customer is a valid Traction customer by supplying a Customer ID, mobile number, address or external ID. A password may be optionally submitted to validate the request. Customer attributes may also be requested at the same time. If your application does not require authentication, use the more efficient Retrieve Customer API (see page 26). 6.2 System Functionality Authentication: Checks that web endpoint exists in account and that username and password are correct Check if customer exists Check that the ACCESSPASSWORD matches the customer s PASSWORD attribute in Traction. Check if customer is inactive, i.e. Customer s ACTIVE attribute in Traction is FALSE. Retrieve the values of attributes requested. 6.3 Business Rules Customer must be identified by using MATCH KEY/VALUE pair. Must have valid Web Endpoint, username and password must match endpoint details If REQUIREPASSWORD is not submitted or is NULL it defaults to TRUE. If REQUIREPASSWORD = TRUE the ACCESSPASSWORD submitted must match the customer s PASSWORD field in Traction. If REQUIREPASSWORD = FALSE, ACCESSPASSWORD is NOT required. If ISINVISIBLE is not submitted it defaults to FALSE If ISINVISIBLE = TRUE and the customer s opt status attribute is set to Opt Out Blocked, the CUSTOMER IS INVISIBLE error code (13) is returned. If customer s active attribute is set to False, the CUSTOMER IS INACTIVE error code (12) is returned. Any number of attributes may be requested, but the parameters must be numbered sequentially beginning with ATTRID1. Attribute values will be returned with the corresponding number, such as TRAC-ATTRVAL1. If the customer does not have a value for the attribute in Traction, the parameter will be returned with no value. If an error occurred retrieving an attribute value, a Warning message with the same number will be returned and no value parameter will be returned. If there are several warning messages, the Result code value will reflect the last message. The Customer ID will be returned on a successful login regardless of warnings issued. 6.4 API Base References Authorisation See section 2.4 for information on authorization requirements. Customer Searching - See section 2.6 for information on Customer searching requirements. 6.5 URL Page 33 of 106, Prepared 23 March 2009

34 6.6 How It Works The most common use of this API is as a login tool. For Example: A website requests from a user that they enter an address and password. The and password must match that of an ACTIVE Traction customer before the user will be allowed into the rest of the site, otherwise they are guided to the registration area. Because customers are never deleted from a Traction account, it is possible that a customer exists after they have purposely requested to be Opted Out. The website however may not want to list them as a Registered customer if this has occurred, they may from a customer service perspective want the customer s login to fail if they have unsubscribed. For this reason the ISINVISIBLE parameter is available which if set to TRUE tells the API to reject the login and return the CUSTOMER IS INVISIBLE error code if their opt status is set to OPT OUT BLOCKED. It is also possible to retrieve attributes for that customer if they are successfully found. There is no limit to the number of attributes to be returned so the entire customer profile may be returned if requested. For example: The first name is required so that a personalized welcome message can be displayed upon successful login. The website would submit the parameter ATTRID1=FIRSTNAME and the API would then return ATTRID1=John. The REQUIREPASSWORD parameter determines whether or not a password is required to validate the login. The website can then be used to retrieve an attribute belonging to a customer without submitting anything other than the address, mobile number or external user id of the customer List A1 Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID MATCHKEY Text (1) Yes Determines the type of data in the MatchValue parameter : E , M mobile, X external user ID, C customer ID MATCHVALUE Text (100) Yes The identifier for customer type is determined by the matchkey, e.g.: Matchkey = E Matchvalue = somebody@company.com.au Matchkey = C Matchvalue = 9 Matchkey = M Matchvalue = 614XXXXXXXX ACCESSPASSWORD Text (50) YES unless Customer password RequirePassword= FALSE REQUIREPASSWORD Boolean No Defaults to TRUE if set to false, ACCESSPASSWORD is NOT MANDATORY ISINVISIBLE Boolean No Set to TRUE to return an error when the customer s Opt Status is Block ATTRID1 Varies See List A2 No Attribute ID 1 The Traction customer attribute ID of the requested attribute. Page 34 of 106, Prepared 23 March 2009

35 ATTRIDn Varies No Attribute ID n See List A2 SUBSCRIPTIONS Boolean No Defaults to False. If TRUE, a comma delimited list of Subscription IDs is returned which includes all live Subscriptions to which the customer is currently subscribed. ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No Supported but has no effect since the Traction database is not being modified List A2 Post Parameter Values for ATTRID1..ATRIDn Parameter Value FIRSTNAME LASTNAME TITLE MOBILE PASSWORD SMSOPT OPT EXTUSERID ACTIVE XXXX Description Customer s First name Customer s Family name Customer s Title e.g. Mr., Ms. Customer s Mobile phone number address of the Customer Password for the Customer SMS opt status for this customer. opt status for this customer. External identification code for Customer Whether the Customer is active in Traction The numeric Attribute ID of the Custom Attribute which is to be returned List B Result Codes Result code Reason Result -4 WARNING - Multi list item not found for attribute Success -3 WARNING - List item not found for attribute Success -2 WARNING - Attribute not found in this account Success 0 Completed successfully Success 1 Incorrect Login credentials Failed 5 Missing Required Data Failed 7 Customer Not Found Failed 8 Customer password invalid Failed 12 Customer is inactive Failed 13 Customer is invisible Failed 14 Invalid Match Key Failed 15 Invalid Match Value Failed Page 35 of 106, Prepared 23 March 2009

36 Result code Reason Result 16 Invalid Match Value Mobile Failed 17 Invalid Match Value External User ID Failed 18 Invalid Match Value Customer ID Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers Parameter Type Returned Description TRAC-RESULT Integer Yes Result code see list B TRAC-ERROR Text (1000) On error Error Description TRAC-CUSTOMERID Integer On success Customer ID TRAC-ATTRVAL1 Text (500) On attribute success Value of Attribute ID 1 TRAC-ATTRVALn Text (500) On attribute success Value of Attribute ID n TRAC- SUBSCRIPTIONS Text (500) If SUBSCRIPTIONS parameter is TRUE Comma-delimited list of live Subscription IDs to which the customer is currently subscribed. TRAC-WARN1 Text (1000) On attribute error Warning message if unable to return TRAC-ATTRVAL1. TRAC-WARNn Text (1000) On attribute error Warning message if unable to return TRAC-ATTRVALn. Page 36 of 106, Prepared 23 March 2009

37 7. Multiple Subscription API 7.1 Summary The Multiple Subscription API allows 3 rd party web sites to subscribe or unsubscribe customers from multiple subscription lists in one submission. The customer s details in the database may be updated by submitting the new data. If a customer is not in the database, a new record will be added unless unsubscribing only, in which case no record is added. 7.2 Traction Requirements Subscriptions Web Endpoint attached to the Subscriptions 7.3 System Functionality Subscribe a customer to one or more subscriptions. Unsubscribe a customer from one or more subscriptions. Define a Subscribe or Unsubscribe action for each subscription submitted, so the customer can be added and removed from subscriptions at the same time. Update a customer s details. Add a new customer if customer doesn t exist. Optionally, send a reply SMS (as specified by each Subscription) to the customer s mobile number if one is known. 7.4 Business Rules Must have valid Web Endpoint, username and password must match endpoint details Customer details must be valid. All subscriptions must be LIVE and the current date must be within the valid date range of the subscription. Web Endpoint must be attached to all of the Subscriptions as an access point. Customer must be identified by using MATCH KEY/VALUE pair. If subscribing and the customer doesn t exist add him/her to the account A reply SMS will not be sent if the customer s mobile number is unknown. If unsubscribing only and the customer doesn t exist DO NOT add him/her to the account (return customer not found error) Return WARNING status if the customer is not subscribed to a subscription they are attempting to unsubscribe from. SUBSCRIPTIONID parameter is a String Array, with each element representing the SubscriptionID Action where the action is S for subscribe or U for unsubscribe see list A for full list of parameters 7.5 API Base References 7.6 URL Authorisation See section 2.4 for information on authorization requirements. Customer Data See section 2.7 for information on Customer Data requirements. Page 37 of 106, Prepared 23 March 2009

38 7.7 How It Works A 3rd party web site will pass customer information to the Traction to subscribe or unsubscribe a customer from one or more subscription lists. The API will verify that the web endpoint details are correct before continuing otherwise it will return an error. Customer s intent to subscribe or unsubscribe is identified within the SUBSCRIPTIONID parameter. This parameter is an Array of Strings. Each String has 2 parts, part 1 is the Id of the subscription, part 2 is S (for subscribe) or U (for unsubscribe). The parts are separated by a character, for example: SUBSCRIPTIONID: { 1234 S, 3241 U, S, S } In the example above the customer is subscribing to three subscription lists (IDs 1234, 12343, and 12313) and unsubscribing from one (3241). If you want to send out the SMS response messages configured for each subscription then set the SENDREPLYSMS parameter to Y. If not, set it to N and the customer will be subscribed/unsubscribed but all configured messages will be ignored. Keep in mind that an SMS message is sent for each subscription/unsubscription! If unsubscribing and the customer does not exist in the Traction account a CUSTOMER NOT FOUND error (7) will be returned. If the customer exists but is not subscribed to any of the subscription lists which they are attempting to unsubscribe from then a WARNING status is returned. The TRAC-WARN message which is also returned will provide information on which subscription IDs the warning applies to. See List A for a full list of variables to pass. If all subscription/un-subscriptions are successful Subscription API returns 0. If any of the subscriptions/unsubscriptions fail then ALL fail. The reason for failure can be identified by the error code returned. See List B for all result codes List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID SUBSCRIPTIONID1 Text Yes Contains the SubscriptionID Action Action = S for subscribe or U for unsubscribe Eg 1234 S 3244 U SUBSCRIPTIONIDn Text Yes Contains the SubscriptionID Action Action = S for subscribe or U for unsubscribe Eg 1234 S 3244 U SENDREPLYSMS Text (1) Yes Y send SMS reply to customer N do not send SMS reply to customer Page 38 of 106, Prepared 23 March 2009

39 MATCHKEY Text (1) Yes Determines the type of data in the MatchValue parameter : E , M mobile, X external user ID, C customer ID MATCHVALUE Text (100) Yes The identifier for customer type is determined by the matchkey, e.g.: Matchkey = E Matchvalue = somebody@company.com.au Matchkey = C Matchvalue = 9 Matchkey = M Matchvalue = 614XXXXXXXX CUSTOMER CUSTOMERTYPE (see section 2.7) No Collection of customer Attributes which need to be added/updated for the Customer ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result -5 WARNING Customer not subscribed Success 0 Completed Success 1 Incorrect Login credentials Failed 5 Missing Required Data Failed 6 Invalid Customer Data Failed 7 Customer Not Found Failed 9 clashes with existing customer Failed 10 Mobile Number clashes with existing customer Failed 11 External user ID clashes with existing customer Failed 14 Invalid Match Key Failed 15 Invalid Match Value Failed 16 Invalid Match Value Mobile Failed 17 Invalid Match Value External User ID Failed 18 Invalid Match Value Customer ID Failed 23 Invalid Subscription Failed 25 Invalid Subscribe/Unsubscribe Indicator Failed 26 Invalid Send Reply SMS Indicator Failed 40 Invalid Customer Attribute Failed 41 Customer Data Error Length Failed 42 Customer Data Error Type Failed 43 Customer Data Error Item not Found Failed 44 Customer Data Error Mandatory Failed Page 39 of 106, Prepared 23 March 2009

40 Result code Reason Result 67 Invalid Mobile Number Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if API has failed for any reason TRAC-CUSTOMERID Integer On success Returns the ID of the customer that has been created/updated TRAC-ATTR Text (100) On Failure due to Customer error Returns the Attribute ID of the attribute which failed customer validation TRAC-WARN1 Text (1000) No Warning Description if API has returned a warning status for SUBSCRIPTIONID1 TRAC-WARN2 Text (1000) No Warning Description if API has returned a warning status for SUBSCRIPTIONID2 TRAC-WARNn Text (1000) No Warning Description if API has returned a warning status for SUBSCRIPTIONIDn Page 40 of 106, Prepared 23 March 2009

41 8. Prize Pool API 8.1 Summary The Prize Pool API allows 3 rd party websites to submit Competition Entries into Traction to be processed in real time, returning to the website any configured SMS response messages. 8.2 Traction Requirements A Live Traction Promotion with 1 Prize Pool attached A valid Web Endpoint attached to the Promotion 8.3 System Functionality Add a single entry to a Prize Pool Return notification to the website of whether or not an instant prize has been won, and a description of the prize If no prize is won, notify website why No tickets left Customer has reached entry limit (eg. max 2 entries per user) Entry is not a winner. Add the customer to Traction if they don t already exist or update their existing details if they do. Send Prize Notification if configured on the Promotion. 8.4 Business Rules Must have valid Web Endpoint, username and password must match endpoint details Promotion must be LIVE and within valid date ranges for entry to be accepted. Promotion will be deemed invalid if there is more than 1 prize pool is attached to it. Web Endpoint must be attached to the Promotion as an access point. Prize Pool will be determined by the Promotion ID Customer must be identified by using MATCH KEY/VALUE pair. Customer details must be valid The notifications sent back to the website are the SMS messages configured in the Prize Pool. A boolean WINNER parameter is returned from the API notifying whether or not the entry won an instant prize. If the Promotion has an configured to be Sent on Prize Win then the API will send the when a prize is won. If the Promotion requires ENTRYCODES, the ENTRYCODE will be validated prior to entry into the Prize Pool. All other functionality configured on the Promotion (e.g. mobile content, standard SMS response messages) will be ignored when entering via the Prize Pool API. 8.5 API Base References 8.6 URL Authorisation See section 2.4 for information on authorization requirements. Customer Data See section 2.7 for information on Customer Data requirements. Page 41 of 106, Prepared 23 March 2009

42 8.7 How It Works A 3 rd party web site will gather the customer information and will pass that information to the Traction to record and enter into the Prize Pool. See List A for a full list of variables to pass. The Prize Pool API will verify that the web endpoint details are correct before continuing otherwise it will return an error. If an ENTRYCODE has been submitted this will be validated prior to entering the customer into the prize pool. If validation is successful an entry code accepted interaction is recorded for the customer and the API continues to enter the customer into the prize pool and update customer attribute data if required. If the entry code does NOT validate, then an entry rejected interaction is recorded for the customer and the API terminates at this point in time. No customer attribute data will be stored for the customer if the entry is rejected, however if the customer did not previously exist in the Traction database they will be added as a new customer, storing only their MATCHVALUE information. The entry is added to the prize pool in real time and the API returns whether or not the entry has won an Instant Prize. See List C for a full list of response headers. If a prize has been won the TRAC-WINNER response header will be set to TRUE and the TRAC-MSG header will contain the SMS message configured for that prize within the prize pool. If a prize hasn t been won, there could be 3 possible reasons: 1. The entry is not a winner in which case the TRAC-MSG header will contain the SMS message configured for NOT A WINNER in the prize pool. 2. No more tickets the prize pool has run out of tickets in which case the TRAC-MSG header will contain the SMS message configured for the NO PRIZES LEFT MESSAGE in the prize pool. 3. Entry limit exceeded for customer the prize pool has a limit to the number of times each customer can enter and the customer submitting the entry has reached their limit. In this case the TRAC-MSG header will contain the SMS message configured for ENTRY LIMIT EXCEEDED in the prize pool. In the Traction Promotion an can be specified to be sent on Prize Win only. If this is the case the will be sent from the Prize Pool API when a prize is won. ANYTHING else configured in the promotion such as reply SMS messages, content or standard s WILL NOT be actioned when entering the promotion through this API. If other functionality is required the Promotion API must be used and no instant prize notification is available. If the Promotion function being used contains an with Snippet placeholders, you can insert an Snippet of your choosing into the using the SNIPPETx parameter, where x represents the placeholder number (e.g. SNIPPET1, SNIPPET2). The value of this parameter is the unique ID of the Snippet as defined and stored in the Traction account. For example: SNIPPET1=MY_ID123. If a warning is generated when Snippets are used, the promotion entry was still recorded and an was sent, however the snippet placeholder contains no data. If real time notification is not needed then the Promotion API is recommended for use instead of this API because it has faster performance. See section 9 for information about the Promotion API List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID PROMOTIONID Integer Yes Traction Promotion Function ID Page 42 of 106, Prepared 23 March 2009

43 MATCHKEY Text (1) Yes Determines the type of data in the MatchValue parameter : E , M mobile, X external user ID, C customer ID MATCHVALUE Text (100) Yes The identifier for the customer type is determined by the matchkey, e.g.: Matchkey = E Matchvalue = somebody@company.com.au Matchkey = C Matchvalue = 9 Matchkey = M Matchvalue = 614XXXXXXXX CUSTOMER CUSTOMERTYPE (see section 2.7) No Collection of customer Attributes which need to be added/updated for the Customer entering the Prize Pool ENTRYCODE Text (50) No An entrycode to validate prior to entering the prize pool. To be used when the promotion is configured with entry codes. SNIPPETx Text (50) No If the Promotion function being entered contains an with Snippet placeholders, use this parameter to specify the Snippet ID to include in the , where x represents the placeholder position, e.g. use SNIPPET1 as the parameter name for the placeholder $SNIPPET:1$ in the . ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result -8 WARNING: No Snippet placeholders in template Success -7 WARNING: Invalid Snippet placeholder Success -6 WARNING: Invalid Snippet ID Success -1 WARNING - Couldn t send prize win invalid address Success 0 Completed Success 1 Incorrect Login credentials Failed 4 Promotion ID not valid will be invalid if no PrizePool or more than one Failed PrizePool is attached to it. 5 Missing Required Data Failed 6 Invalid Customer Data Failed 7 Customer Not Found Failed 9 Customer s duplicated Failed 10 Customer s phone number duplicated Failed 11 External Customer Id matches with existing customer Failed 14 Invalid MatchKey Failed Page 43 of 106, Prepared 23 March 2009

44 Result code Reason Result 15 Invalid Matchvalue Failed 16 Invalid Matchvalue Mobile Failed 17 Invalid Matchvalue External User Id Failed 18 Invalid Matchvalue CustomerId Failed 34 Entry Rejected - Invalid Entry Code Failed 35 Entry Rejected - Entry code exceeded Usage Limit Failed 40 Invalid Customer Attribute Failed 41 Customer Data Error Length Failed 42 Customer Data Error Type Failed 43 Customer Data Error Item not Found Failed 44 Customer Data Error Mandatory Failed 67 Invalid Mobile Number Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if API has failed TRAC-STATUS Integer Yes Status of Entry: 1 Winner 2 - Not a winner 3 - entry limit exceeded 4 - no tickets left TRAC-MSG Text (160) Yes Return message from entry (whatever is set up as sms response for the prizepool) TRAC-CUSTOMERID Integer On success Returns the ID of the customer that has been created/updated TRAC-WARN Text (1000) No If warning result code returned (ie TRAC- RESULT < 0) this will contain a description of the warning. TRAC-ATTR Text (100) On Failure due to Customer error TRAC- ERRORCODES TRAC- ERRORPARAMS Returns the Attribute ID of the attribute which failed customer validation Text (1000) No Returned when a warning status is returned. It contains a comma-delimited list of error/warning codes which occurred during processing Text (1000) No Returned when a warning status is returned. It contains a comma-delimited list of the parameter names which caused the errors listed in ERRORCODES Page 44 of 106, Prepared 23 March 2009

45 9. Promotion API 9.1 Summary The Promotion API allows 3 rd party websites to submit one or more entries into a Traction Promotion. 9.2 Traction Requirements Promotion A valid Web Endpoint attached to the Promotion 9.3 System Functionality Authentication: Checks that web endpoint exists in account and that username and password are correct Add Customer Modify Customer details Add one or more entries for the Customer to the Promotion 9.4 Business Rules Must have valid Web Endpoint Username and password must match endpoint details Promotion must be LIVE and within its valid date ranges for entry to be accepted and the Web endpoint must be attached to the Promotion Customer must be identified by using MATCH KEY/VALUE pair Customer details must be valid If customer doesn t exist add him/her to the account If the number of Entries is not specified it defaults to API Base References 9.6 URL Authorisation See section 2.4 for information on authorization requirements. Customer Data See section 2.7 for information on Customer Data requirements How It Works A 3 rd party web site will gather the customer information and will pass that information to the Traction to record and enter into the Promotion. It is also possible to make a several entries into Promotion by utilizing the ENTRIES parameter. The ENTRIES parameter should be set to the number of entries required. See List A for a full list of variables to pass. The Promotion API will verify that the web endpoint details are correct before continuing otherwise it will return an error. See List B for a full list of result codes. If an ENTRYCODE has been submitted this will be validated prior to entering the customer into the promotion. If validation is successful an entry code accepted interaction is recorded for the customer and the API continues to enter the customer into the promotion and update customer attribute data if required. If the entry code does NOT Page 45 of 106, Prepared 23 March 2009

46 validate, then an entry rejected interaction is recorded for the customer and the API terminates at this point in time. No customer attribute data will be stored for the customer if the entry is rejected, however if the customer did not previously exist in the Traction database they will be added as a new customer, storing only their MATCHVALUE information. If entering multiple entries (ie ENTRIES > 1) then the entry code must validate for the full number of entries; if it doesn t, NO entries will be accepted and an Insufficient Code error (36) will be returned. If the Promotion function being used contains an with Snippet placeholders, you can insert an Snippet of your choosing into the using the SNIPPETx parameter, where x represents the placeholder number (e.g. SNIPPET1, SNIPPET2). The value of this parameter is the unique ID of the Snippet as defined and stored in the Traction account. For example: SNIPPET1=MY_ID123. If a warning is generated when Snippets are used, an entry in the Promotion was still recorded and an was sent, however the snippet placeholder contains no data List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID PROMOTIONID Integer Yes Traction Promotion Function ID MATCHKEY Text (1) Yes Determines the type of data in the MatchValue parameter : E , M mobile, X external user ID, C customer ID MATCHVALUE Text (100) Yes The identifier for the customer type is determined by the matchkey, e.g.: Matchkey = E Matchvalue = somebody@company.com.au Matchkey = C Matchvalue = 9 Matchkey = M Matchvalue = 614XXXXXXXX ENTRIES Integer No Number of tickets (default 1) FREETEXT Text (150) No Text to be stored CUSTOMER CUSTOMERTYPE (see section 2.7) No Collection of customer Attributes which need to be added/updated for the Customer entering the Promotion ENTRYCODE Text (50) No To be submitted when the promotion being entered is configured to require entry codes. SNIPPETx Text (50) No If the Promotion function being entered contains an with Snippet placeholders, use this parameter to specify the Snippet ID to include in the , where x represents the placeholder position, e.g. use SNIPPET1 as the parameter name for the placeholder $SNIPPET:1$ in the . ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database. Page 46 of 106, Prepared 23 March 2009

47 9.7.2 List B Result Codes Result code Reason Result -8 WARNING: No Snippet placeholders in template Success -7 WARNING: Invalid Snippet placeholder Success -6 WARNING: Invalid Snippet ID Success 0 Completed Success 1 Incorrect Login credentials Failed 4 Promotion ID not valid Failed 5 Missing Required Data Failed 6 Invalid customer data Failed 7 Customer Not Found Failed 9 Customer s duplicated Failed 10 Customer s phone number duplicated Failed 11 External Customer Id matches with existing customer Failed 14 Invalid MatchKey Failed 15 Invalid Matchvalue Failed 16 Invalid Matchvalue Mobile Failed 17 Invalid Matchvalue External User Id Failed 18 Invalid Matchvalue Customer Id Failed 34 Entry Rejected - Invalid Entry Code Failed 35 Entry Rejected - Entry code exceeded Usage Limit Failed 36 Entry Rejected - Insufficient code (ie limited to 2 uses per code and attempting to Failed enter 3 entries) 40 Invalid Customer Attribute Failed 41 Customer Data Error Length Failed 42 Customer Data Error Type Failed 43 Customer Data Error Item not Found Failed 44 Customer Data Error Mandatory Failed 46 Invalid ENTRIES Failed 67 Invalid Mobile Number Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if the API has failed for any reason TRAC-CUSTOMERID Integer On success Returns the ID of the customer that has been created/updated Page 47 of 106, Prepared 23 March 2009

48 TRAC-ATTR Text (100) On Failure due to Customer error TRAC- ERRORCODES TRAC- ERRORPARAMS Returns the Attribute ID of the attribute which failed customer validation Text (1000) No Returned when a warning status is returned. It contains a comma-delimited list of error/warning codes which occurred during processing Text (1000) No Returned when a warning status is returned. It contains a comma-delimited list of the parameter names which caused the errors listed in ERRORCODES Page 48 of 106, Prepared 23 March 2009

49 10. Promotion Group Report API 10.1 Summary The Promotion Group Report API allows 3 rd party websites to view the statistics from a Promotion Group configured in Traction. The results are returned in XML format Traction Requirements Promotion Group Web Endpoint 10.3 System Functionality Returns XML containing information about all promotions in group. Information contains promotion attributes and number of unique and non-unique requests received 10.4 Business Rules Must have valid Web Endpoint Username and password must match endpoint details 10.5 API Base References Authorisation See section 2.4 for information on authorization requirements URL How It Works A 3 rd party web site requests the current statistics for a Traction Promotion Group. The API returns an XML file as the response, outlining the promotions in the requested group, their status and the number of distinct requests as well as the total requests (i.e. non-distinct) which have been received. The Promotion Group API will verify that the web endpoint details (authorisation) are correct before continuing otherwise it will return an error. For a list of all possible errors see List B below List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID GROUPID Integer Yes Promotion Group ID ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. Page 49 of 106, Prepared 23 March 2009

50 List B Result Codes Result code Reason Result 0 Completed Success 1 Incorrect Login credentials Failed 5 Missing Required Data Failed 24 Invalid Promotion Group the groupid passed in does not match a valid Failed promotion group in Traction 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if the API has failed for any reason Returned XML The XML result is streamed back to the requesting page. An example of the XML returned is shown below: <feed> <promotiongroup> <id>xxx</id> <name><![cdata[promotion Group Name]]></name> <generateddate>the date this was returned</generateddate> <promotions> <! 1 to n of promotions in promotion group <promotion> <id>xxx</id> <name><![cdata[promotion 1]]></name> <status>finished</status> <! distinct customers --> <distinctrequests>200</distinctrequests> </promotions> </promotiongroup> </feed> <! includes customers who ve entered twice --> <totalrequests>450</totalrequests> </promotion> <promotion> <id>xxx</id> <name><![cdata[promotion 2]]></name> <status>live</status> <distinctrequests>20</distinctrequests> <totalrequests>20</totalrequests> </promotion> <promotion> <id>xxx</id> Etc Page 50 of 106, Prepared 23 March 2009

51 11. Send to a Friend API 11.1 Summary Send to a Friend API allows 3 rd party websites to send either an SMS, WAP or broadcast message to one or more friends Traction Requirements Broadcast Web Endpoint attached to the Broadcast 11.3 System Functionality Add Customers Update Customers Add Recipient to Send To Friend Broadcasts Add Sender to Promotion Add Recipients to Traction as new Customers Update Recipient s details 11.4 Business Rules Must have valid Web Endpoint Username and password must match endpoint details Broadcast must be LIVE and within its valid date ranges for entry to be accepted Web Endpoint must be attached to the Broadcast If Promotion ID supplied Promotion must be LIVE and within its valid date ranges for entry to be accepted and Web endpoint must be attached to the promotion. Customer details must be valid If Sender doesn t exist add him/her to the account If Recipient doesn t exist add him/her to the account At least one Recipient must be specified If sending an Broadcast the TYPE parameter must be set to and the attribute must be present in all CUSTOMERTYPE parameters If sending an SMS or WAP Broadcast the TYPE parameter must be set to SMS or WAP and the MOBILE attribute must be present in all CUSTOMERTYPE parameters 11.5 API Base References Authorisation See section 2.4 for information on authorization requirements. Customer Data See section 2.7 for information on Customer Data requirements URL How It Works A 3 rd party web site will gather the required information of who wants to send s or SMS to their friends (referred to as the SENDER) and the friends that you want to send to (referred to as the RECIPIENTS). The web Page 51 of 106, Prepared 23 March 2009

52 page will post 1 sender and multiple recipients along with web endpoint details and the broadcast ID and, if needed, a Promotion ID to Traction. To collect information about the Sender, SENDER parameter should be used. Recipients should be identified by names such as RECIPIENT1, RECIPIENT2 etc. Numbers in names should be increased sequentially. At least one Recipient must be submitted. The Send to a Friend API updates Sender details or a new Customer will be created if the sender does not match one of the existing customers. It also updates Recipient details comparing Recipient with existing Customers or again, new Customers will be created. The post may optionally specify a Promotion to add the Sender to as well. In this case PROMOTIONID should be supplied. The Sender will receive an additional entry into the promotion for each recipient specified, so if sending to 3 recipients the Sender will receive a total of 4 entries into the promotion. If an entrycode has been submitted this will be validated prior to all other processing within the API. If validation is successful an entry code accepted interaction is recorded for the customer and the API continues. If the entry code does NOT validate, then an entry rejected interaction is recorded for the customer and the API terminates at this point in time. No customer attribute data will be stored for the sender or recipients if the entry is rejected, however if the sender did not previously exist in the Traction database their or MOBILE (dependent of the Send to Friend type or SMS) detail will be added as a new customer. If multiple entries into the promotion are required (determined by the number of recipients) then the entry code must validate for the full number of entries, if it doesn t NO entries will be accepted and the API will terminate with an Insufficient Code error returned. If CHECKOPTIN is sent as TRUE, the API will update the recipient record in Traction, and then retrieve the current or SMS opt status for the recipient (depending on which type of message is being sent). If the opt status returns OPT-OUT or OPT-OUT(Blocked), then the address / mobile number is added to the TRAC- UNSENT return header and a message is not sent to that recipient. See List A for a full list of variables to pass. The Send to a Friend API will verify that the web endpoint details are correct before continuing otherwise it will return an error List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID BROADCASTID Integer Yes Traction Broadcast Function ID PROMOTIONID Integer No Traction Promotion Function ID TYPE Text (5) No Type of Broadcast (SMS or or WAP) Defaults to SENDER CUSTOMERTYPE Yes Sender (see section 2.7) RECIPIENT1 CUSTOMERTYPE Yes 1st Recipient. At least one must exist (see section 2.7) RECIPIENTn CUSTOMERTYPE No nth Recipient (see section 2.7) ENTRYCODE Text (50) No To be submitted when the promotion being entered is configured to require entry codes. Page 52 of 106, Prepared 23 March 2009

53 CHECKOPTIN Boolean No If TRUE, Traction will only send the message ( or SMS) to a recipient who is NOT opted out or opted out (blocked). Anyone who is opted in, undefined, or does not yet exist in the Traction account will be sent the message. If FALSE or not present, Traction will send the message to all recipients. ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result 0 Completed Success 1 Incorrect Login credentials Failed 3 Broadcast ID not valid Failed 4 Promotion ID not valid Failed 5 Missing Required Data Failed 6 Invalid Customer Data Failed 9 Customer s Address clashes with existing customer Failed 10 Customer s Mobile Number clashes with existing customer Failed 11 Customer s External User Id matches with existing customer Failed 15 Invalid (Matchvalue) Address Failed 16 Invalid (Matchvalue) Mobile Number Failed 34 Entry Rejected - Invalid Entry Code Failed 35 Entry Rejected Entry code exceeded Usage Limit Failed 36 Entry Rejected - Insufficient code (ie limited to 2 uses per code and attempting to Failed enter 3 entries) 40 Invalid Customer Attribute Failed 41 Customer Data Error Length Failed 42 Customer Data Error Type Failed 43 Customer Data Error Item not Found Failed 44 Customer Data Error Mandatory Failed 67 Invalid Mobile Number Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B Page 53 of 106, Prepared 23 March 2009

54 TRAC-ERROR Text (1000) No Error Description if the API has failed for any reason TRAC-CUSTOMERID Integer On success Returns the ID of the sending customer that has been created/updated. Friend IDs are not returned. TRAC-ATTR Text (100) On Failure due to Sender or Recipient error TRAC-PARAMETER Text (20) On Failure due to Sender or Recipient error Returns the Attribute ID of the attribute which failed customer validation Returns the Customer PARAMETER name which failed customer validation eg. RECIPIENT1 TRAC-UNSENT Text (4000) No Returns a comma-delimited list of addresses or mobile numbers of recipients to whom the message was NOT sent, if the CHECKOPTIN parameter is set to TRUE and the recipient is opted out or opted out (blocked). Page 54 of 106, Prepared 23 March 2009

55 12. SMS Gateway API 12.1 Summary The SMS Gateway API allows 3 rd party websites to submit incoming messages, outgoing messages and retrieve a list (XML) of received messages from an SMS Gateway function in Traction Traction Requirements SMS Gateway A valid Web Endpoint attached to the SMS Gateway 12.3 System Functionality Authentication: Checks that web endpoint exists in account and that username and password are correct Check if customer exists Add Customers (mobile number only) if they don t already exist Send SMS messages to Traction Send SMS messages to mobile number Retrieve received SMS messages and message attributes from Traction in XML format 12.4 Business Rules Must have a valid Web Endpoint, username and password must match endpoint details Mobile number must be valid SMS Gateway function must both be LIVE and within the valid date ranges for entry to be accepted. ACTION parameter identifying what API should do (send message IN, OUT or Retrieve it) must be specified. If any other option specified error message will be returned. To send messages in and out both mobile phone number and message text should be specified. To retrieve messages the number of messages to retrieve in one XML file should be specified. If the mobile number is not found it should be added to the system 12.5 API Base References Authorisation See section 2.4 for information on authorization requirements URL How It Works A 3 rd party web site will submit messages to the Traction SMS Gateway API for sending them either to Traction or a mobile number. It may also retrieve received messages in XML format. If the mobile doesn t exist in Traction, a new customer is added. See List A for a full list of parameters. There are 3 actions that this API can do: Page 55 of 106, Prepared 23 March 2009

56 1. I Stands for Incoming Message. If you pass in ACTION=I then you are submitting an incoming message from a customer into the Traction Gateway. When using this action the MOBILE and MESSAGE parameters are mandatory. 2. O Stands for Outgoing Message. If you pass in ACTION=O then you are submitting an outgoing message to be sent to a customer through the Traction Gateway. When using this action the MOBILE and MESSAGE parameters are mandatory. 3. R Stands for Retrieve Messages. If you pass in ACTION=R then you are requesting (in xml format) a list of messages which have been submitted to the Gateway. When using this action the MOBILE and MESSAGE parameters ARE NOT MANDATORY, but BATCHSIZE is. The XML response is then streamed back to the caller Returned XML The XML result is streamed back to the requesting page. An example of the xml returned is shown below: <messages number= Number of messages retrieved > <message> <from> </from> <received>01/03/ :24</received> <keyword>pizza</keyword> <text>this is the content of the SMS message!</text> </message> <message> etc.. </messages> List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID GATEWAYID Integer Yes Traction SMS Gateway Function ID ACTION Text (1) Yes What you want the API to do: I = Incoming Message O = Outgoing Message R = Retrieve Messages MOBILE Text (20) Yes unless ACTION = R MESSAGE Text (160) Yes unless ACTION = R BATCHSIZE Integer No unless ACTION = R The customer s Mobile number, this is the person submitting the message (action=i) or being sent the message (action=o) The message sent from the customer (action=i) or the message to be sent to the customer (action=o) When retrieving messages the batchsize specifies how many messages you would like to retrieve at a time. Page 56 of 106, Prepared 23 March 2009

57 ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result 0 Completed Success 1 Incorrect Login credentials Failed 5 Missing Required Data Failed 16 Invalid Match Value Mobile Failed 32 GatewayID not valid Failed 33 Invalid ACTION not I, O or R Failed 45 Invalid BATCHSIZE Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see List B TRAC-ERROR Text (1000) No Error Description if the API has failed for any reason TRAC- CUSTOMERID1 Integer On success (ACTION=I or O) Returns the ID of the first customer that has been created/updated TRAC- CUSTOMERIDn Integer On success (ACTION=I or O) Returns the ID of the nth customer that has been created/updated Page 57 of 106, Prepared 23 March 2009

58 13. Subscription API 13.1 Summary The Subscription API allows 3 rd party web sites to subscribe or unsubscribe a customer from a single subscription list. The customer s details in the database may be updated by submitting the new data. If a customer is not in the database, they will be added. To subscribe or unsubscribe a customer from multiple subscriptions at once, use the Multiple Subscription API as described in section Traction Requirements Subscription Web Endpoint attached to the Subscription 13.3 System Functionality Subscribe a customer to a subscription. Unsubscribe a customer from a subscription. Update a customer s details. Add a new customer if customer doesn t exist. Optionally, send a reply SMS (as specified by the Subscription) to the customer s mobile number if one is known Business Rules Must have valid Web Endpoint, username and password must match endpoint details Customer details must be valid. Subscription must be LIVE and the current date must be within the valid date range of the subscription. Web Endpoint must be attached to the Subscription as an access point. Customer must be identified by using MATCH KEY/VALUE pair. Customer details must be valid. If subscribing and the customer doesn t exist add him/her to the account If unsubscribing and the customer doesn t exist, the customer is not added to the account; a Customer not Found error (7) is returned. A reply SMS will not be sent if the customer s mobile number is unknown. A WARNING status is returned if the customer is not subscribed to the subscription they are attempting to unsubscribe from API Base References 13.6 URL Authorisation See section 2.4 for information on authorization requirements. Customer Data See section 2.7 for information on Customer Data requirements. Page 58 of 106, Prepared 23 March 2009

59 13.7 How It Works A 3 rd party web site will pass customer information to the Traction to subscribe or unsubscribe customer from a subscription list. The Subscription API will verify that the web endpoint details are correct before continuing otherwise it will return an error. Customer s intent to subscribe or unsubscribe is identified by the SUBORUNSUB parameter. If you want to send out the SMS response messages configured for the subscription then set the SENDREPLYSMS parameter to Y. If not set it to N and the customer will be subscribed/unsubscribed but all configured messages will be ignored. If unsubscribing and the customer does not exist in the Traction account a CUSTOMER NOT FOUND error (7) will be returned. If the customer exists but is not subscribed to the particular subscription they are attempting to unsubscribe from then a WARNING status is returned. See List A for a full list of variables to pass. If subscription successful Subscription API returns 0. If the action was unsuccessful, the reason can be identified by the error code returned. See List B for all result codes List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID SUBSCRIPTIONID Integer Yes Traction Subscription Function ID to subscribe to or unsubscribe from SUBORUNSUB Text (1) Yes S for subscribe or U for unsubscribe SENDREPLYSMS Text (1) Yes Y send SMS reply to customer N do not send SMS reply to customer MATCHKEY Text (1) Yes Determines the type of data in the MatchValue parameter : E , M mobile, X external user ID, C customer ID MATCHVALUE Text (100) Yes The identifier for customer type is determined by the matchkey, e.g.: Matchkey = E Matchvalue = somebody@company.com.au Matchkey = C Matchvalue = 9 Matchkey = M Matchvalue = 614XXXXXXXX CUSTOMER CUSTOMERTYPE (see section 2.7) No Collection of customer Attributes which need to be added/updated for the Customer subscribing/unsubscribing Page 59 of 106, Prepared 23 March 2009

60 ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result -5 WARNING Customer not subscribed Success 0 Completed Success 1 Incorrect Login credentials Failed 5 Missing Required Data Failed 6 Invalid Customer Data Failed 7 Customer Not Found Failed 9 clashes with existing customer Failed 10 Mobile Number clashes with existing customer Failed 11 External user ID clashes with existing customer Failed 14 Invalid Match Key Failed 15 Invalid Match Value Failed 16 Invalid Match Value Mobile Failed 17 Invalid Match Value External User ID Failed 18 Invalid Match Value Customer ID Failed 23 Invalid Subscription Failed 25 Invalid Subscribe/Unsubscribe Indicator Failed 26 Invalid Send Reply SMS Indicator Failed 40 Invalid Customer Attribute Failed 41 Customer Data Error Length Failed 42 Customer Data Error Type Failed 43 Customer Data Error Item not Found Failed 44 Customer Data Error Mandatory Failed 67 Invalid Mobile Number Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if the API has failed for any reason TRAC-CUSTOMERID Integer On success Returns the ID of the customer that has been created/updated Page 60 of 106, Prepared 23 March 2009

61 TRAC-WARN Text (1000) No Warning Description if the API has returned a warning status TRAC-ATTR Text (100) On Failure due to Customer error Returns the Attribute ID of the attribute which failed customer validation Page 61 of 106, Prepared 23 March 2009

62 14. Survey API 14.1 Summary The Survey API allows 3 rd party websites to submit Survey responses into Traction Traction Requirements Surveys A valid Web Endpoint attached to the Survey 14.3 System Functionality Authentication: Checks that web endpoint exists in account and that username and password are correct If customer doesn t exist add him/her to the account Add Customer s responses to Survey Add Customer to Promotion if PROMOTIONID specified 14.4 Business Rules Must have valid Web Endpoint Username and password must match endpoint details Survey must be LIVE and within its valid date ranges for entry to be accepted and Web Endpoint must be attached to the survey. If Promotion ID supplied Promotion must be LIVE and within its valid date ranges for entry to be accepted and Web endpoint must be attached to the promotion. Customer must be identified by using MATCH KEY/VALUE pair Customer details must be valid If customer doesn t exist add him/her to the account If the promotion entry is invalid and fails, the survey responses will NOT be saved either API Base References 14.6 URL Authorisation See section 2.4 for information on authorization requirements. Customer Data See section 2.7 for information on Customer Data requirements How It Works A 3 rd party web site will gather the required responses for the survey and will pass that information to the Traction Survey API for recording. The Survey API will first verify that the endpoint details are correct to authorize entry into the survey before continuing otherwise it will return an error. The post provides necessary information about Survey and customer along with responses identified by names such as RESPONSE1, RESPONSE2 etc. Numbers in names should be increased sequentially. The value to send depends on the type of survey question as configured in Traction: Page 62 of 106, Prepared 23 March 2009

63 Text the actual text Drop down list the ordinal response number, e.g. 1 for the first response Radio button group the ordinal response number, e.g. 1 for the first response Multi select drop down list the ordinal response numbers separated by commas, e.g. 1,3 for the first and third responses Check box group the ordinal response numbers separated by commas, e.g. 1,3 for the first and third responses True/False 1 for True, 2 for False. Note that a group of radio buttons is functionally equivalent to a drop down list, and a group of check boxes is functionally equivalent to a multi select drop down list. Survey API updates Customer details or new Customer will be created if he/she does not match one of the existing customers. The post may additionally specify a Promotion to add the customer to as well. In this case Promotion ID should be supplied. Customers cannot be added to a promotion through this API without submitting Survey Responses also. If an ENTRYCODE has been submitted this will be validated prior to entering the customer into the promotion or recording the survey responses. If validation is successful an entry code accepted interaction is recorded for the customer and the API continues to enter the customer into the promotion and survey. If the entry code does NOT validate, then an entry rejected interaction is recorded for the customer and the API terminates at this point in time. No customer attribute data will be stored for the customer if the entry is rejected, however if the customer did not previously exist in the Traction database they will be added as a new customer, storing only their MATCHVALUE information. If the optional Promotion function being used contains an with Snippet placeholders, you can insert an Snippet of your choosing into the using the SNIPPETx parameter, where x represents the placeholder number (e.g. SNIPPET1, SNIPPET2). The value of this parameter is the unique ID of the Snippet as defined and stored in the Traction account. For example: SNIPPET1=MY_ID123. If a warning is generated when Snippets are used, the promotion entry was still recorded and an was sent, however the snippet placeholder contains no data. See List A for a full list of variables to pass. The Survey entry is processed in real time however the promotion entry will enter a queue for processing when convenient. See list B for a full list of result codes List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID SURVEYID Integer Yes Traction Survey Function ID PROMOTIONID Integer No Traction Promotion Function ID MATCHKEY Text (1) Yes Determines the type of data in the MatchValue parameter : E , M mobile, X external user ID, C customer ID Page 63 of 106, Prepared 23 March 2009

64 MATCHVALUE Text (100) Yes The identifier for customer type is determined by the matchkey, e.g.: Matchkey = E Matchvalue = somebody@company.com.au Matchkey = C Matchvalue = 9 Matchkey = M Matchvalue = 614XXXXXXXX CUSTOMER CUSTOMERTYPE (see section 2.7) No Collection of customer Attributes which need to be added/updated for the Customer RESPONSE1 Text (500) No Response to Question 1 RESPONSEn Text (500) No Response to Question n ENTRYCODE Text (50) No To be submitted when the promotion being entered is configured to require entry codes. SNIPPETx Text (50) No If the optional Promotion function being entered contains an with Snippet placeholders, use this parameter to specify the Snippet ID to include in the , where x represents the placeholder position, e.g. use SNIPPET1 as the parameter name for the placeholder $SNIPPET:1$ in the . ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result -8 WARNING: No Snippet placeholders in template Success -7 WARNING: Invalid Snippet placeholder Success -6 WARNING: Invalid Snippet ID Success 0 Completed Success 1 Incorrect Login credentials Failed 4 Promotion ID not valid Failed 5 Missing Required Data Failed 6 Invalid Customer Data Failed 7 Customer Not Found Failed 9 Customer s duplicated Failed 10 Customer s phone number duplicated Failed 11 External Customer Id matches with existing customer Failed 14 Invalid MatchKey Failed 15 Invalid Matchvalue Failed 16 Invalid Matchvalue Mobile Failed Page 64 of 106, Prepared 23 March 2009

65 Result code Reason Result 17 Invalid Matchvalue External User Id Failed 18 Invalid Matchvalue CustomerId Failed 19 Survey ID not valid Failed 20 Missing Survey Data (mandatory question not answered) Failed 21 Invalid Survey Data Failed 22 Max Survey Submissions Exceeded Failed 34 Entry Rejected - Invalid Entry Code Failed 35 Entry Rejected - Entry code exceeded Usage Limit Failed 40 Invalid Customer Attribute Failed 41 Customer Data Error Length Failed 42 Customer Data Error Type Failed 43 Customer Data Error Item not Found Failed 44 Customer Data Error Mandatory Failed 67 Invalid Mobile Number Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if the API has failed for any reason TRAC-CUSTOMERID Integer On success Returns the ID of the customer that has been created/updated TRAC-ATTR Text (100) On Failure due to Customer error TRAC- ERRORCODES TRAC- ERRORPARAMS Returns the Attribute ID of the attribute which failed customer validation Text (1000) No Returned when a warning status is returned. It contains a comma-delimited list of error/warning codes which occurred during processing Text (1000) No Returned when a warning status is returned. It contains a comma-delimited list of the parameter names which caused the errors listed in ERRORCODES Page 65 of 106, Prepared 23 March 2009

66 15. Voting API 15.1 Summary The Voting API allows 3 rd party websites to submit Votes into Traction and to retrieve the current voting stats Traction Requirements A valid Vote Function Web Endpoint attached to this Vote function 15.3 System Functionality Add the customer to Traction if they don t already exist or update their existing details if they do. IF a CANDIDATEID is submitted add a vote from this Customer to the candidate IF SHOWRESULTS = TRUE, return the current results for all candidates Add Customer votes for a candidate into a Vote and return the current result for all candidates instantly in one request Check if Customer exceeds maximum entries number and do not accept vote if they have 15.4 Business Rules Must have valid Web Endpoint, username and password must match endpoint details Customer details must be valid Customer cannot vote if the number of maximum permitted votes is exceeded, and an error message will be returned Voting function must both be LIVE and within the valid date ranges for entry to be accepted. If web site requests only voting results (SHOWRESULTS is TRUE) then candidate and customer details (valid CANDIDATEID, MATCHKEY and MATCHVALUE) are not required API Base References Authorisation See section 2.4 for information on authorization requirements. Customer Data See section 2.7 for information on Customer Data requirements URL How It Works See List A for a full list of variables to pass to the API. The Voting API will verify that the web endpoint details and the voting Id are correct before continuing otherwise it will return an error. The API can be used to submit a vote OR to request the current results for a vote. If SHOWRESULTS parameter is set to TRUE then the results will be returned. If a CANDIDATEID and customer details (MATCHKEY/VALUE pair) are submitted also then the entry will be submitted to the VOTE for real time processing and the results will then be returned including the new entry. Page 66 of 106, Prepared 23 March 2009

67 If SHOWRESULTS parameter is set to FALSE and a CANDIDATEID and customer details (MATCHKEY/VALUE pair) are submitted then the entry is added to a queue for batch processing at a later date. If SHOWRESULTS is FALSE and NO CANDIDATEID or MATCHKEY/VALUE details are submitted an error is returned. If the results are being returned each CANDIDATE will be returned as a separate response header with the name TRAC- followed by the CANDIDATEID code, e.g. TRAC-132. The value for this response header contains the number of votes for that candidate. If the Voting function being used contains an with Snippet placeholders, you can insert an Snippet of your choosing into the using the SNIPPETx parameter, where x represents the placeholder number (e.g. SNIPPET1, SNIPPET2). The value of this parameter is the unique ID of the Snippet as defined and stored in the Traction account. For example: SNIPPET1=MY_ID123. If a warning is generated when Snippets are used, the vote was still recorded and an was sent, however the snippet placeholder contains no data List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID VOTEID Integer Yes Traction Vote Function ID CANDIDATEID Integer Only if SHOWRESULTS = FALSE Traction Vote Candidate ID MATCHKEY Text (1) Only if SHOWRESULTS=FALSE MATCHVALUE Text (100) Only if SHOWRESULTS=FALSE CUSTOMER CUSTOMERTYPE (see section 2.7) SHOWRESULTS Boolean No Defaults to FALSE if not present No Determines the type of data in the MatchValue parameter : E , M mobile, X external user ID, C customer ID The identifier for customer type is determined by the matchkey, e.g.: Matchkey = E Matchvalue = somebody@company.com.au Matchkey = C Matchvalue = 9 Matchkey = M Matchvalue = 614XXXXXXXX Collection of customer Attributes which need to be added/updated for the Customer submitting the Vote Accepts TRUE or FALSE, If TRUE the current results for all candidates will be returned. SNIPPETx Text (50) No If the Voting function being entered contains an with Snippet placeholders, use this parameter to specify the Snippet ID to include in the , where x represents the placeholder position, e.g. use SNIPPET1 as the parameter name for the placeholder $SNIPPET:1$ in the . Page 67 of 106, Prepared 23 March 2009

68 ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result -8 WARNING: No Snippet placeholders in template Success -7 WARNING: Invalid Snippet placeholder Success -6 WARNING: Invalid Snippet ID Success 0 Completed Success 1 Incorrect Login credentials Failed 5 Missing Required Data Failed 6 Invalid Customer Data Failed 7 Customer Not Found Failed 9 Duplicate Customer Failed 10 Duplicate Customer Mobile Failed 11 Duplicate Customer External User ID Failed 14 Invalid MatchKey Failed 15 Invalid Matchvalue Failed 16 Invalid Matchvalue Mobile Failed 17 Invalid Matchvalue External User Id Failed 18 Invalid Matchvalue CustomerId Failed 22 Number of Entries exceeded for this Customer Failed 30 VoteID not valid Failed 31 CandidateID not valid Failed 40 Invalid Customer Attribute Failed 41 Customer Data Error Length Failed 42 Customer Data Error Type Failed 43 Customer Data Error Item not Found Failed 44 Customer Data Error Mandatory Failed 47 Invalid ShowResults value (ie not a valid Boolean) Failed 67 Invalid Mobile Number Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers Page 68 of 106, Prepared 23 March 2009

69 TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if the API has failed for any reason TRAC- CUSTOMERID Integer On success Returns the ID of the customer that has been created/updated TRAC-ATTR Text (100) On Failure due to Customer error TRAC- CANDIDATEID E.g. TRAC-132 TRAC- CANDIDATEIDn TRAC- ERRORCODES TRAC- ERRORPARAMS Returns the Attribute ID of the attribute which failed customer validation Integer No The name of this parameter is the CANDIDATEID whose results are being returned; the value is the current vote count for that candidate Integer No The name of this parameter is the CANDIDATEID whose results are being returned; the value is the current vote count for that candidate Text (1000) No Returned when a warning status is returned. It contains a comma-delimited list of error/warning codes which occurred during processing Text (1000) No Returned when a warning status is returned. It contains a comma-delimited list of the parameter names which caused the errors listed in ERRORCODES Page 69 of 106, Prepared 23 March 2009

70 16. RSS Update API 16.1 Summary Trigger an update to an RSS feed that is registered in Traction. Items in RSS feeds may be used as SMS messages and as parts of broadcasts. NOTE: If an SMS broadcast is configured to send automatically on RSS update, using this API may trigger a broadcast to be sent. Please ensure that you understand the current usage of RSS feeds in your Traction account before calling this API. Use the TEST parameter during testing to prevent live messages from being sent Traction Requirements An active RSS feed registered in Traction A valid Web Endpoint 16.3 System Functionality Update the latest RSS feed contents into Traction Any SMS broadcasts configured to send on an RSS update may automatically send if an update is detected Business Rules Must have a valid Web Endpoint, username and password must match endpoint details. RSS ID must reference a valid, active RSS feed in the same account as the Web Endpoint 16.5 API Base References Authorisation See section 2.4 for information on authorization requirements URL How It Works By calling this API, Traction will update the RSS feed referenced in the RSSID parameter. RSS items may or may not be added/updated depending on the content of the feed at the time the API is called. If an SMS broadcast has been configured to automatically send on an RSS update, and the feed and item in question are updated by calling this API, the SMS broadcast will automatically send the updated content to the defined customer list in Traction. See List A for a full list of variables to pass to the API List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID RSSID Integer Yes Traction RSS ID to be updated Page 70 of 106, Prepared 23 March 2009

71 ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result 0 Completed Success 1 Incorrect Login credentials Failed 5 Missing Required Data Failed 48 RSS Feed ID is not valid Failed 49 Error updating Feed Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if the API has failed for any reason Page 71 of 106, Prepared 23 March 2009

72 17. Broadcast Trigger API 17.1 Summary The Broadcast Trigger API will trigger an Externally Triggered broadcast in Traction, sending live s to the defined customer list. This API is often used in conjunction with the RSS Update API to allow content to be maintained and broadcast directly in an external application. NOTE: This API will trigger a broadcast of live s to the customers defined in the Externally Triggered broadcast. Use the TEST parameter while testing to avoid sending live s Traction Requirements A live Externally Triggered broadcast in Traction A valid Web Endpoint 17.3 System Functionality Trigger a live occurrence of the Externally Triggered Broadcast defined in BROADCASTID parameter. Content and recipient customers are defined in the broadcast in Traction Business Rules Must have a valid Web Endpoint, username and password must match endpoint details. Broadcast must be an Externally Triggered broadcast. Broadcast must be Live or Processing preliminary or finished broadcasts may not be triggered. Broadcast must be within its valid date ranges. If the broadcast is already processing (from a previous Broadcast Trigger API request), error 50 (Broadcast Already Processing) is returned and the broadcast is not resent API Base References 17.6 URL Authorisation See section 2.4 for information on authorization requirements How It Works By calling this API, a live Externally Triggered broadcast will be sent to all customers defined by the broadcast. If the broadcast is already running (due to a previous call to the API), error 50 (Broadcast Already Processing) is returned and the broadcast is not resent. See List A for a full list of variables to pass to the API List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password Page 72 of 106, Prepared 23 March 2009

73 ENDPOINTID Integer Yes Traction Web Endpoint ID BROADCASTID Integer Yes Traction Externally Triggered Broadcast ID ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result 0 Completed Success 1 Incorrect Login credentials Failed 3 Broadcast ID not valid Failed 5 Missing Required Data Failed 50 Broadcast Currently Processing Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if The API has failed for any reason Page 73 of 106, Prepared 23 March 2009

74 18. Snippet Upload API 18.1 Summary The Snippet Upload API will upload an XML file containing Snippets into a Traction account Traction Requirements A valid Web Endpoint 18.3 System Functionality Uploads an XML file containing one or more Snippets into a Traction account. Each Snippet contains the following information: o A unique ID o A friendly title o An HTML snippet, a text snippet, or both If a Snippet already exists in the Traction account with the same ID, it will be overwritten. If a Snippet does not exist in the Traction account, it will be created Business Rules Must have a valid Web Endpoint, username and password must match endpoint details. The file must be formatted according to the pre-defined schema. Each Snippet may be no more than 30,000 bytes in length (HTML and text versions are counted separately). HTML and text snippet content must be stored as CDATA Large Snippet files may be zipped before uploading. Do not use a password-protected zip file. Overall file size is limited to 50 MB (native or zipped). A File Transfer ID is returned to the application. Use the File Status API (page 85) to check the progress of an uploaded file at any time API Base References Authorisation See section 2.4 for information on authorization requirements URL How It Works An Snippet is a piece of HTML, text, or both, that represents a potential portion or snippet of an s content. In your Traction account you are able to create a library of these Snippets, and add them to your promotional broadcasts selectively. For example, you may wish to include a product recommendation in a purchase confirmation , based on the product purchased and the customer s prior history. Using your own business rules, you can identify a suitable Snippet or Snippets to include in the confirmation . Snippets may be used in that is attached to Promotion and Voting functions. Actual s are then triggered by an application that you develop using API calls. You may use the Promotion API (page 45), the Voting Page 74 of 106, Prepared 23 March 2009

75 API (page 66), or the Prize Pool API (page 41) to submit customers to a Promotion or Vote and trigger an to them. You may also use the Survey API (page 62), which has an optional Promotion ID parameter. Snippets may not be used in regular broadcasts, $$event-triggered$$ broadcasts, or $$send-tofriend$$ broadcasts. You do not identify individual Snippets when you create your content. Instead, you add a placeholder in the where a Snippet should be inserted using the $SNIPPET:x$ $$tractag$$, where x is a simple ordinal number such as 1 or 2. Then, whenever you trigger an using one of the aforementioned APIs, you identify which particular Snippet to include in each placeholder by referencing its unique identifier. For instance, you might indicate that Snippet placeholder 1 should use your Snippet ID pr Using this methodology, you can develop your own business rules to choose which Snippet or Snippets should go to which customer. Any number of Snippet placeholders may be used in a single template. Although it is recommended that placeholders are numbered 1, 2, and so on, any integer values may be used. See List A for a full list of variables to pass to the API List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID FILE Text (20) Yes The XML file to be uploaded ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result 0 Completed Success 1 Incorrect Login credentials Failed 3 Broadcast ID not valid Failed 5 Missing Required Data Failed 54 File too large (maximum is 50 MB) Failed 55 Invalid file type (must be.zip or.xml) Failed 100 General Java Error Failed 101 General Database Error Failed Page 75 of 106, Prepared 23 March 2009

76 List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if the API has failed for any reason TRAC- FILETRANSFERID Integer Yes The ID of the file transfer in Traction this becomes an input parameter for the File Status API Snippet XML Schema <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs=" targetnamespace=" xmlns=" elementformdefault="qualified"> <xs:complextype name="snippettype"> <xs:sequence> <xs:element name="id" nillable="false"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:maxlength value="50"/> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="title" nillable="false"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:maxlength value="100"/> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="html" type="xs:string" /> <xs:element name="text" type="xs:string" /> </xs:sequence> </xs:complextype> <xs:element name="snippetlist"> <xs:complextype> <xs:sequence> <xs:element name="snippet" type="snippettype" maxoccurs="unbounded" minoccurs="1" /> </xs:sequence> </xs:complextype> </xs:element> </xs:schema> Page 76 of 106, Prepared 23 March 2009

77 Snippet XML Example <?xml version="1.0" encoding="utf-8"?> <snippetlist xmlns=" <snippet> <id>c13_m234</id> <title>my first recommendation</title> <html><![cdata[ <table> <tr><td>recommendation 1</td></tr> <tr><td>recommendation 2</td></tr> <tr><td>recommendation 3</td></tr> </table> ]]></html> <text><![cdata[this is the text version of my 1st recommendation]]> </text> </snippet> <snippet> <id>c13_m235</id> <title>recommendation 2</title> <html><![cdata[ <table> <tr><td>recommendation 4</td></tr> <tr><td>recommendation 5</td></tr> <tr><td>recommendation 6</td></tr> </table> ]]></html> <text><![cdata[this is the text version of my 2nd recommendation]]> </text> </snippet> </snippetlist> Page 77 of 106, Prepared 23 March 2009

78 19. Batch Customer Transfer API Suite The Batch Customer Transfer API suite allows you to automate the importing and exporting of customer files between Traction and your applications. It is a suite of four API calls that allow the following functionality: File Upload API File Export API File Status API File Request API File Download API Sends a CSV file to Traction for upload/import Creates a CSV file in Traction for download/export Monitors the processing of a file that has been initiated using the File Upload and File Export APIs. If the File Status API indicates that errors were encountered during a file upload process, this API requests that an error file be generated for download. Use the File Status API to monitor the processing of the error file. Downloads an error file initiated by the File Request API from Traction. Each API is documented in its own sub-chapter of this chapter. Notes: The file format is defined by a Traction File Profile. File Profiles must be manually configured in Traction. Files may be comma- or tab-delimited. Customers in an upload may be subscribed to or unsubscribed from a Subscription Customers in an upload may be added to a Customer Group. The Customer Group may either already exist in Traction or can be created automatically during the upload process. New customers in an upload may have their Opt Status and SMS Opt Status attributes initialised to Opt In, Opt Out, or Opt Out (Blocked). Page 78 of 106, Prepared 23 March 2009

79 19.1 File Upload API Summary The File Upload API initiates the transfer of a local file of customer records to Traction Traction Requirements File Profile that matches the format of the file to be uploaded A valid Web Endpoint Optionally a Subscription function Optionally an existing Customer Group (Customer Groups can also be made automatically via this API) System Functionality Authentication: Checks that the Web Endpoint exists in the Traction account and that the username and password are correct. Upload a file of customer records from a local path to Traction. Processing of file commences use the File Status API to determine processing status. Customer records may be matched against existing records using address, mobile phone number, or external customer ID. Customer records are either added (if new), modified (if existing), or rejected (if file data contains errors) If more than 1000 errors are encountered, the entire file upload is abandoned: File Status API will return ERROR. File records with errors are not processed in any way. Subscribe customers to or unsubscribe customers from a Subscription if SUBSCRIPTIONID specified. Merge customers into an existing Customer Group or a new Customer Group Customer Group merge logic may be: o Add uploaded customers are added to the Customer Group o Replace uploaded customers replace the existing customers in the Customer Group o Subtract uploaded customers are removed from the Customer Group o Intersect uploaded customers who are already in the Customer Group are retained in the Group; others are removed. o Suppress uploaded customers who are not in the Customer Group are added; those in the Group are removed (opposite of Intersect). o New A new Customer Group is created and the customers are added to it. Initialise the Opt Status and SMS Opt Status attributes for new customers. Customers already in the Traction account are not affected. Opt statuses may be independently initialised to: o Opted in this customer may be communicated with o Opted out someone other than the customer has chosen to suppress communication with this customer o Opted out (blocked) the customer has chosen to suppress communication Returns a FILETRANSFERID value which may be used in the File Status API to determine status and the File Request API to request an Errors file Business Rules Must have valid Web Endpoint Username and password must match endpoint details File size is limited to 50 MB Page 79 of 106, Prepared 23 March 2009

80 A valid MATCHKEY and FILEPROFILEID must be provided. File must be either comma- or tab-delimited CSV format (depending on the setting in the selected File Profile) Files may be compressed name the upload file with the extension.zip. If extended character set support is required (e.g. Asian characters), the submitted file must be UTF-8 encoded API Base References Authorisation See section 2.4 for information on authorization requirements URL Page 80 of 106, Prepared 23 March 2009

81 Typical API Workflow Diagram Page 81 of 106, Prepared 23 March 2009

82 How It Works A 3 rd party application will create or identify a CSV file (optionally compressed as a ZIP file) of customer records and will upload that file to Traction. The File Upload API will first verify that the endpoint details are correct to authorize upload to the Traction account, otherwise it will return an error. The FILEPROFILEID parameter is mandatory and determines the File Profile to be used when uploading the file. File Profiles designate the order of file columns and the file format (comma- or tab-delimited). The MATCHKEY parameter determines which criteria Traction will use to identify whether a customer already exists in Traction. The SUBSCRIPTIONID parameter determines an optional Subscription function to either subscribe customers to or unsubscribe them from. If used, the SUBORUNSUB parameter must be set to either S for subscribe or U for unsubscribe. The GROUPID parameter determines an optional Customer Group to merge customers into. If creating a new Customer Group (GROUPACTION = N), this parameter contains the name of the new Customer Group. If merging into an existing Group (GROUPACTION = A, R, S, I, or M), this parameter contains the Traction ID of the Group. When using this parameter, the GROUPACTION parameter must always be set. The DEFAULT parameter determines how to initialise the Opt Status attribute for new Traction customers. If omitted, the opt status is set to Undefined. The DEFAULTSMS parameter determines how to initialise the SMS Opt Status attribute for new Traction customers. If omitted, the opt status is set to Undefined. The TEST attribute allows you to simulate the upload of a file without actually creating new customer records. A FILETRANSFERID will still be returned but will be invalid for any further processing List A Post Parameters USERID Text (50) Yes Traction Web Endpoint Username PASSWORD Text (50) Yes Traction Web Endpoint Password ENDPOINTID Integer Yes Traction Web Endpoint ID FILE Text (20) Yes The local file to be uploaded FILEPROFILEID Integer Yes Traction File Profile ID MATCHKEY Text (1) Yes Determines the type of data to match on when matching with existing customers: E , M mobile, X external user ID SUBSCRIPTIONID Integer No A subscription ID within Traction to which customers should be subscribed or unsubscribed SUBORUNSUB Text (1) If SUBSCRIPTIONID is used S Subscribe U - Unsubscribe Page 82 of 106, Prepared 23 March 2009

83 GROUPID Integer No Either: A Customer Group ID (for existing Groups) OR The name of a new Customer Group GROUPACTION Text (1) If GROUPID is used N add to new group (GROUPID parameter must be the name of the group) A add to existing group (GROUPID parameter must be the ID of an existing group) R replace existing group (GROUPID parameter must be the ID of an existing group) S subtract from existing group (GROUPID parameter must be the ID of an existing group) I intersect with existing group (GROUPID parameter must be the ID of an existing group) M suppress with existing group (GROUPID parameter must be the ID of an existing group) DEFAULT Text (1) No Initialise the Opt Status attribute of new customers I opt in O opt out B opt out (blocked) If not provided, the attribute is set to Undefined. DEFAULTSMS Text (1) No Initialise the SMS Opt Status attribute of new customers I opt in O opt out B opt out (blocked) If not provided, the attribute is set to Undefined. ENCODE - No If present, response headers will be encoded in base-64. See Multilingual (Double-Byte) Issues on page 21 for more information. TEST - No If present, Traction will emulate the processing, returning results as per normal but will not modify its database List B Result Codes Result code Reason Result 0 Completed Success 1 Incorrect Login credentials Failed 5 Missing Required Data Failed Page 83 of 106, Prepared 23 March 2009

84 Result code Reason Result 14 Invalid MatchKey Failed 23 Invalid Subscription ID Failed 25 Invalid SUBORUNSUB parameter (must be S or U) Failed 33 Invalid GROUPACTION parameter (must be N, A, R, S, I, M) Failed 53 Invalid File Profile ID Failed 54 File too large (max 50MB) Failed 55 Invalid file type (not.zip,.csv,.txt) Failed 56 Invalid Group ID Failed 57 Invalid Group Name Failed 58 Invalid opt status Failed 59 Invalid SMS opt status Failed 100 General Java Error Failed 101 General Database Error Failed List C Response Headers TRAC-RESULT Integer Yes Result code Value see list B TRAC-ERROR Text (1000) No Error Description if the API has failed for any reason TRAC- FILETRANSFERID Integer Yes The ID of the file transfer in Traction this becomes an input parameter for the File Status API and File Request API TRAC-GROUPID Integer No The ID of the newly created Customer Group if there is one Page 84 of 106, Prepared 23 March 2009

85 19.2 File Export API Summary The File Export API starts the creation of a file of customer records within Traction. When complete, the file may be downloaded with the File Download API. Any Customer Group or Target may be exported. Alternatively, all customers in the account may be exported Traction Requirements File Profile that matches the format of the file to be exported A valid Web Endpoint System Functionality Authentication: Checks that the Web Endpoint exists in the Traction account and that the username and password are correct. Starts the creation of an export file of customer records in Traction. Processing of file commences use the File Status API to determine processing status. Returns a FILETRANSFERID value which may be used in the File Status API to determine processing status Business Rules Must have valid Web Endpoint Username and password must match endpoint details File will be either comma- or tab-delimited CSV format (depending on the setting in the selected File Profile) A single Customer Group, Target, or all customers in the account. Files may be compressed; the ZIP parameter must be set to TRUE in this case The export file is UTF-8 encoded API Base References URL Authorisation See section 2.4 for information on authorization requirements. Page 85 of 106, Prepared 23 March 2009

86 Typical API Workflow Diagram How It Works A 3 rd party application will request that a set of customers be put into a CSV file for export from Traction. The File Export API will first verify that the endpoint details are correct to authorize upload to the Traction account, otherwise it will return an error. The SOURCETYPE parameter identifies the set of customers may be a Customer Group ( G ), a Target ( T ), or all customers in the account ( A ). If a Customer Group or a Target is specified, the SOURCEID parameter identifies the ID of the Group or Target. The FILEPROFILEID parameter is mandatory and determines the File Profile to be used when creating the export file. File Profiles define the set of customer attributes to be exported, and the file format (comma- or tab-delimited). The COLUMN_HEADERS parameter is optional and tells Traction to write a header row as the first row in the export file. The default value is TRUE. When exporting a Target, the UPDATE_TARGET parameter is optional if TRUE, Traction recalculates the requested Target before creating the export file if FALSE, Traction exports the customers as they currently exist as of the last time it was recalculated. Note: In either case the Target will not appear to have recalculated if you check the user interface. The ZIP parameter is optional and tells Traction to compress the export file on completion. A compressed file will have the extension.zip and will need to be uncompressed after download using a program such as Winzip. The default value is TRUE. Page 86 of 106, Prepared 23 March 2009