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:
1. Integrate with a POS system.
2. Design your own mobile application.
3. Program your own email, sms, or custom marketing and customer relations application.
4. Automate the recording of transactions based on your own triggers.
5. Integrate with other SaaS online applications for a seamless enterprise solution.
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:
https://sub.domain.com/admin.php
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.
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:
To get 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):
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.
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:
function submit_cURL ($data) {
// initialize curl handle:
$ch = curl_init();
// set url to post to:
curl_setopt($ch, CURLOPT_URL, 'https://sub.domain.com/api.php' );
// return into a variable instead on on-screen:
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Set timeout, in seconds:
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
// add XML data here:
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
// turn off verification of SSL for testing:
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
// Workaround for certain Virtual Hosting hosts:
// curl_setopt ($ch, CURLOPT_PROXY,"http://");
// Send query to server:
$result = curl_exec($ch);
curl_close ($ch);
// Create a SimpleXML object from the result and return it.
$parsed_result = new SimpleXMLElement($result);
return $parsed_result;
}
NOTES:
$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.
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.
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.