Overview

This API allows other programs and hardware to interface with the loyalty platform directly, without having to go through a browser, allowing you to integrate transactional steps into mobile, web, or desktop applications.

You can use this API to:

• Integrate with a POS system.
• Design your own mobile application.
• Program your own email, sms, or custom marketing and customer relations application.
• Automate the recording of transactions based on your own triggers.
• Integrate with other SaaS online applications for a seamless enterprise solution.

API Access URL

Any API call from any account can be sent to the main API url:

https://api.clienttoolbox.com

NOTE: Notice the "s" in https – Connections to the API must be through encrypted SSL, in order to protect the sensitive nature of your data.

Also, ALL PARAMETERS, including the user_id and user_api_key/user_password credentials, must be passed as POST form-data. (ie: as if it was a form submission on a page.) This ensures that data is included in the encryption stream, and allows compatibility with older hardware that does not look for authentication fields in a POST header.

It is possible to form and submit a GET request where all the parameters are part of the URL, but this is not recommended as any data that is part of the URL is open and visible to anyone, which would expose your user credentials to the world.

You can also use your vanity or domain-mapped domain, but with "api.php" as the destination to send the requests to (and not "admin.php".) For example:

• Take a look at the URL used to access your Control Panel. It is likely to be something like:

  https://sub.domain.com/admin.php

• Now, replace the "admin.php" with "api.php" like this:

  https://sub.domain.com/api.php

There is no difference in speed accessing either URLs, although domain-mapped URLs may take slightly longer due to the additional DNS hop. Generally, we recommend you use the main API url unless you have a specific reason to use your vanity or domain-mapped domain.

API Access Credentials

To be able to access the API, you need to be a registered User of an account. We recommend
that you create a User in your account specifically for API calls.

All API calls require the two following credentials:

• user_id: The username of an authorized user to the account.
• user_api_key (API v1.5) or user_password (v1.0 APIs): IMPORTANT: In both cases, provide the Security Token of the user, not the actual password.

To get the user_id:

• Go to your account's Control Panel screen.
• Display the list of Users for that account
  
• Click on the EDIT button next to the user you want to use to access the API with
  
• On the top, in the light-blue bar, next to the title "Edit user:" is the user_id

To get the user_api_key (also called the Security Token) and in some API calls prior to version 1.5 called the user_password):

• Go to your account's Control Panel screen.
• Display the list of Users for that account
  
• Click on the EDIT button next to the user you want to use to access the API with
  
• At the bottom of the first section, next to the label "API access Security Token", will be a long string of characters in grey. This is the user_api_key / user_password.

To clarify: You will need to always include both a user_id and a user_api_key / user_password to be able to receive any responses from any requests to the API. Each API call has these two parameters as the first two items in its required fields list. Think of this as each API call being a new connection. To work with old school terminals and other similar devices, the use of sessions or similar connection persistance schemas has had to be avoided.

Integration with your application:

From inside your application, you send an HTTPS request to the API url above with POST form-data fields containing each parameters needed. The response will be an XML document by default, or in JSON if the parameter output=JSON is part of the API call.

An example in PHP using cURL is this function that takes the POST fields in the array "$data" and returns the API's response as a SimpleXML object:

1. function submit_cURL ($data) {
2. // initialize curl handle:
3. $ch = curl_init();
4. // set url to post to:
5. curl_setopt($ch, CURLOPT_URL, 'https://sub.domain.com/api.php' );
6. // return into a variable instead on on-screen:
7. curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
8. // Set timeout, in seconds:
9. curl_setopt($ch, CURLOPT_TIMEOUT, 10);
10. // add XML data here:
11. curl_setopt($ch, CURLOPT_POST, 1);
12. curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
13. // turn off verification of SSL for testing:
14. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
15. curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
16. // Workaround for certain Virtual Hosting hosts:
17. // curl_setopt ($ch, CURLOPT_PROXY,"http://");
18. // Send query to server:
19. $result = curl_exec($ch);
20. curl_close ($ch);
21. // Create a SimpleXML object from the result and return it.
22. $parsed_result = new SimpleXMLElement($result);
23. return $parsed_result;
24. }

NOTES:

• XML does not deal elegantly with ampersands ("&"). See this article that explains why. Some XML parsers will crash if they encounter content with an ampersand that is not part of an HTML-encoded character. To fix this, replace line 22 above with the following regular expression:

  $parsed_result = new SimpleXMLElement(preg_replace('/&[^; ]{0,6}.?/e', "((substr('\\0',-1) == ';') ? '\\0' : '&'.substr('\\0',1))", $result ) );

  This will replace any rogue ampersands without touching any that are port of an encoded character. We do this on our side, but it would be good practice to put it on yours too.
  
  
• Make sure that the server that originates the API request has SSL enabled for the enviroment or programming language that creates the request, otherwise the request will be ignored and fail, and the data in the request could potentially be intercepted and read.
  
  
• Any API request must also include, each time, a valid user_id and user_api_key/user_password mentioned above – Except for the access test below:

   

Test Access:

NOTE: These test requests use the GET type of request which in these calls do not expose any sensitive data. For all other API calls, use POST form-data.

The simplest test is to enter the API url in any browser:

https://api.clienttoolbox.com?type=test

To test if your server can properly access the API using PHP, use something like this:

$data['type'] = 'test';
$result = submit_cURL ($data);
print_r($result);

To test if your server can properly access the API using command-line cURL, type:

curl https://api.clienttoolbox.com/api.php?type=test

In all three of these test cases, you should receive an XML formatted reponse like this one:

<response status="success">Success</response>

If you want JSON as a response instead, the call would be to:

https://api.clienttoolbox.com/api.php?type=test&output=JSON

And the response should then be:

{"status":"success"}

Coalition and Two-Tier Accounts:

Coalition and Two-Tier accounts (enabled with an Activation Code provided at an additional cost) provide the ability to share points across multiple campaigns within a single account.

• A coalition account will treat as a single balance all of a customer's activity across multiple campaigns (stores, for example) and provide reports that enable the coalition operator to properly manage the billing and disbursements of each participant.
• A two-tier account provides for a defined percentage of a customer's activity in any of the account's points campaigns to be added to a master campaign.

In either case, there are no specific API calls to either account styles -- everyting is done in the background, and the proper results always shown. In the couple instances where results for Coalition and Two-Tier accounts are different than expected, the differences are noted in the applicable section's notes.