Locating your API key
This document contains a list of methods that can be called by invoking a web service using either the REST or SOAP method.
Before you begin you will need to retrieve your API key. This can be found inside the “Push Options” area of your Customer Thermometer account:
On that page, there is a API Information section.
All API calls into Customer Thermometer must be made using this key. You shouldn’t disclose it to anyone. If you are concerned your key has been exposed, please contact us and we will supply a new one.
In addition to your unique API key, you’ll also find the API request URL, used to make calls via our RESTful API.
NB: The WSDL file for SOAP calls is at: https://app.customerthermometer.com/ctapi.wsdl
How to trigger Email Thermometers (Write Method)
sendEmail
This method is designed to send a single Email Thermometer to a single user. You could use this to trigger Email Thermometers as part of workflows within applications.
If the Thermometer blast ID is not passed then a new one will be created. Once the email has been sent, the Thermometer blast ID will be returned.
If the user is unable to send any more emails for any reason then the return value will be 0.
Input Variables
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | sendEmail |
| thermometerID | Integer | Required | The ID of the prebuilt Thermometer you would like to send |
| blastID | Integer | Optional | The Blast ID to log sends and responses against. If not supplied a new Blast, hence Blast ID will be created – this would mean creating Blasts of just one person. |
| listID | Integer | Required | The recipient List ID to add new email addresses to. This would need to be set up in advance. |
| emailAddress | String | Required | The email address of the recipient |
| firstName | String | Optional | The first name of the recipient |
| lastName | String | Optional | The surname of the recipient |
| companyName | String | Optional | The name of the company |
| custom1 | String | Optional | custom1 data field associated with the recipient |
| custom2 | String | Optional | custom2 data field associated with the recipient |
| custom3 | String | Optional | custom3 data field associated with the recipient |
Example syntax (note API key and variables are fictitious):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=sendEmail&emailAddress=danny@customerthermometer.com&firstName=Danny&lastName=Smith&companyName=Danny Co&custom1=Friday&custom2=Strawberry&custom3=New York&thermometerID=16694&listID=41374&blastID=71763
When executed, this string will trigger an Email Thermometer remotely from the Customer Thermometer application.
It will use a prebuilt Thermometer template as indicated by the ID number. You will find the ID in the URL bar of your browser when inside the specific Manage Thermometer screen.
It will take the contact data supplied and add that to the List ID you supply. Again this could already be set up with contacts within it – and this remote call will append additional contacts to that list. You will find the List ID in the URL bar of your browser when inside the specific Manage List screen.
Finally, it will send the relevant Thermometer containing the contact data and add it as pending to the Blast ID which is supplied.
Results will then be appended to that Blast ‘envelope’ on an indefinite basis.
Return Type: Integer (indicating success or failure).
unsubscribeRecipient
This method will allow you to add an email address to the Customer Thermometer unsubscribe list. You are unable to send a email blast survey to any recipient present on the unsubscribe list.
Survey recipients are able to unsubscribe themselves when receiving an Email Thermometer survey.
URL Parameters
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | unsubscribeRecipient |
POST body
| Key | Type | Required / Optional | Value |
| emailAddress | String | Required | [email protected] |
Example syntax (note API key is fictitious):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=unsubscribeRecipient
Return Type: String
Read Methods
getThermometers
This method will return an XML document containing a list of all of the Thermometer names and ID’s available inside the account linked to the API Key used.
Input Variables
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | getThermometers |
Example syntax (note API key is fictitious):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getThermometers
Return Type: XML
getRecipientLists
This method will return an XML document of all of the List names and ID’s available inside the account linked to the API Key used.
Input Variables
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | getRecipientLists |
Example syntax (note API key is fictitious):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getRecipientLists
Return Type: XML
getSendQuota
This method will return an integer containing the number of Thermometer credits currently existing inside the account linked to the API Key used.
Input Variables
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | getSendQuota |
Example syntax (note API key is fictitious):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getSendQuota
Return Type: Integer
getHappinessValue
This method will return an integer (as a %age) showing the Happiness Factor (based on the last x values) for the account linked to the API Key used.
Input Variables
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | getHappinessValue (Will return value for the account, unless limited by variables shown below) |
| limit | Integer | Optional | Limit number of results to take into account (current result first). There is a limit of 100 by default and will be applied if no limit parameter is added. |
| blastID | Integer | Optional | Limit results by Blast ID (found in URL bar on relevant Blast Breakdown page) |
| fromDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
| toDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
Example syntax (note API key is fictitious):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getHappinessValue&limit=100&blastID=12345&fromDate=2015-01-01&endDate=2015-02-01
Return Type: Integer
getNPSValue
This method will return an integer (either positive or negative) showing the NPS score for a specific Blast ID or for the account for the account linked to the API Key used.
Note, you could display an NPS score for your account for a single month for example.
Input Variables
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | getNPSValue (Will return value for the account, unless limited by variables shown below) |
| limit | Integer | Optional | Number of results to take into account (current result first). Limit must be defined in conjunction by Blast ID or Date Range currently. There is no limit applied by default. |
| blastID | Integer | Optional | Limit results by Blast ID (found in URL bar on relevant Blast Breakdown page) |
| fromDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
| toDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
Example syntax (note API key is fictitious):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getNPSValue
To return NPS score for a specific Blast – add the blastID element:
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getNPSValue&blastID=121212
To return NPS score for a specific time period – add the date element:
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getNPSValue&fromDate=2015-01-01&toDate=2015-02-01
Return Type: Integer
getTempRatingValue
This method will return an integer showing the Temperature Rating (as a percentage) for a specific Blast ID for the account linked to the API Key used.
Input Variables
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | getTempRatingValue (Will return value for the account, unless limited by variables shown below) |
| limit | Integer | Optional | Limit number of results to take into account (current result first). There is a limit of 100 by default and will be applied if no limit parameter is added. |
| blastID | Integer | Optional | Limit results by Blast ID (found in URL bar on relevant Blast Breakdown page) |
| fromDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
| toDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
Example syntax (note API key is fictitious):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getTempRatingValue&blastID=12345
Return Type: Integer
getResponseRateValue
This method will return an integer (expressed as a percentage) showing the Response Rate for a specific Blast ID or for the account for the account linked to the API Key used. This will only take into account Email Thermometer Blasts and remove Embedded Blasts from the equation at account level.
Input Variables
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | getResponseRate (Will return value for the account, unless limited by variables shown below) |
| limit | Integer | Optional | Limit number of results to take into account (current result first). There is a limit of 100 by default and will be applied if no limit parameter is added. |
| blastID | Integer | Optional | Limit results by Blast ID (found in URL bar on relevant Blast Breakdown page) |
| fromDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
| toDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
Example syntax (note API key is fictitious):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getResponseRateValue&fromDate=2015-01-01&toDate=2015-02-01
Return Type: Integer
getNumResponsesValue
This method will return an integer showing the number of Responses received for a specific Blast ID or for the account linked to the API Key used. Would like to define TIME banded variables here – so you could display the number of responses for an account for March.
Input Variables
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | getNumResponses |
| temperatureID | Integer | Optional | 1 (gold), 2 (green), 3 (yellow), 4 (red) |
| limit | Integer | Optional | Limit number of results to take into account (current result first). There is no default limit applied. |
| blastID | Integer | Optional | Limit results by Blast ID (found in URL bar on relevant Blast Breakdown page) |
| fromDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
| toDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
Example syntax (note API key is fictitious):
Get total number of responses received
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getNumResponsesValue
Get total number of Gold responses received
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getNumResponsesValue&temperatureID=1
Get total number of Red responses received in July
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getNumResponsesValue&temperatureID=4&fromDate=2015-01-01&toDate=2015-02-01
Return Type: Integer
getBlastResults
This method will return an XML document showing the Responses received for a specific Blast ID or for the account linked to the API Key used.
Input Variables
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | getBlastResults (Will return the last 200 results for the account, unless limited by variables shown below) |
| temperatureID | Integer | Optional | 1 (gold), 2 (green), 3 (yellow), 4 (red) |
| limit | Integer | Optional | Limit number of results to take into account (current result first). There is a limit of 200 by default and will be applied if no limit parameter is added. |
| blastID | Integer | Optional | Limit results by Blast ID (found in URL bar on relevant Blast Breakdown page) |
| fromDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
| toDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
Example syntax (note API key is fictitious):
Return XML document of last 200 results (all data attached)
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getBlastResults
Return XML document of last 200 Gold responses
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getBlastResults&limit=200&temperatureID=1
Return Type: XML
getComments
This method will return an XML document showing the comments received for a specific Blast ID or for the account linked to the API Key used.
Input Variables
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | getComments (Will return the last 200 results for the account, unless limited by variables shown below) 2992} |
| temperatureID | Integer | Optional | 1 (gold), 2 (green), 3 (yellow), 4 (red) |
| limit | Integer | Optional | Limit number of results to take into account (current result first). There is a limit of 200 by default and will be applied if no limit parameter is added. |
| blastID | Integer | Optional | Limit results by Blast ID (found in URL bar on relevant Blast Breakdown page) |
| fromDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
| toDate | string | Optional | Limit results between a date range (format YYYY-MM-DD) |
Example syntax (note API key is fictitious):
Return XML document of last 200 results
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getComments
Return XML document of Comments left against a Gold response from the last 200 results
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getComments&limit=200&temperatureID=1
Return Type: XML
