Locating your API key
This document contains a list of methods that can be called by invoking a web service using the REST method.
Before you begin you will need to retrieve an API key. See further instructions of where to find your API key.
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 (with super API key):
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
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?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
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
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).
logResponse
This method will allow you to submit a response to the Customer Thermometer reporting. It will immediately register the response in your reporting and can trigger email and webhook notifications.
URL Parameters
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | logResponse |
POST body
| Key | Type | Required / Optional | Value |
| recipient | String | Required | [email protected] |
| temperatureId | Integer | Required | 1, 2, 3 or 4 |
| thermometerId | Integer | Required | 222 |
| blastId | Integer | Optional | 12345 |
| npsRating | Integer | Optional | 0-10 |
| isoCountry | String | Optional | GB – Two digit country reference |
| responseDate | String | Optional | Format YYYY-MM-DD: 2024-08-01 14:03:33 (1st August 2024, 2:03:33 PM) |
| comment | String | Optional | |
| userAgent | String | Optional | `Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:15.0) Gecko/20100101 Firefox/15.0.1` |
| emailNotificationFlag | Boolean | Optional | true / false |
| webhookNotificationFlag | Boolean | Optional | true / false |
| firstName | String | Optional | Steve |
| lastName | String | Optional | Stevenson |
| companyName | String | Optional | Love Architecture |
| custom1 | String | Optional | |
| custom2 | String | Optional | |
| custom3 | String | Optional | |
| custom4 | String | Optional | |
| custom5 | String | Optional | |
| custom6 | String | Optional | |
| custom7 | String | Optional | |
| custom8 | String | Optional | |
| custom9 | String | Optional | |
| custom10 | String | Optional | |
| custom11 | String | Optional | |
| custom12 | String | Optional |
Example syntax (with super API key):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=logResponse
Example syntax (with sub-API key):
POST https://app.customerthermometer.com/api.php?getMethod=logResponse
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
Return Type: Integer
addRecipientToList
This method will allow you to add a recipient to an existing list within Customer Thermometer. You can then later trigger a blast to this list.
URL Parameters
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | addRecipientToList |
POST body
| Key | Type | Required / Optional | Value |
| emailAddress | String | Required | [email protected] |
| listId | Integer | Required | 54321 |
| firstName | String | Optional | Steve |
| lastName | String | Optional | Stevenson |
| companyName | String | Optional | Love Architecture |
| custom1 | String | Optional | |
| custom2 | String | Optional | |
| custom3 | String | Optional | |
| custom4 | String | Optional | |
| custom5 | String | Optional | |
| custom6 | String | Optional | |
| custom7 | String | Optional | |
| custom8 | String | Optional | |
| custom9 | String | Optional | |
| custom10 | String | Optional | |
| custom11 | String | Optional | |
| custom12 | String | Optional |
Example syntax (with super API key):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=addRecipientToList
Example syntax (with sub-API key):
POST https://app.customerthermometer.com/api.php?getMethod=addRecipientToList
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
Return Type: String (email address)
deleteResponse
This method will allow you to delete a single response from your Customer Thermometer reporting. It will immediately remove the passed response ID to your response bin, which will then be cleared automatically after 30 days.
URL Parameters
| Variable Name | Variable Type | Required / Optional | Description |
| apiKey | String | Required | Your API Key |
| getMethod | String | Required | deleteResponse |
| responseID | Integer | Required | 22273291 |
Example syntax (with super API key):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=deleteResponse&responseID=22273291
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?getMethod=deleteResponse&responseID=22273291
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
Return Type: Integer
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] |
| notify | boolean | Optional | true / false |
Example syntax (with super API):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=unsubscribeRecipient
Example syntax (with sub-API key):
POST https://app.customerthermometer.com/api.php?getMethod=unsubscribeRecipient
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
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 (with super API):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getThermometers
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?getMethod=getThermometers
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
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 (with super API):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getRecipientLists
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?getMethod=getRecipientLists
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
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 (with super API key):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getSendQuota
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?getMethod=getSendQuota
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
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 (with super API key):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getHappinessValue&limit=100&blastID=12345&fromDate=2015-01-01&endDate=2015-02-01
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?getMethod=getHappinessValue
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
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 (with super API key):
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
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?getMethod=getNPSValue
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
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 (with super API key):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getTempRatingValue&blastID=12345
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?getMethod=getTempRatingValue&blastID=12345
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
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 (with super API key):
https://app.customerthermometer.com/api.php?apiKey=c2cb8788abfc1a0ff609ed3b1&getMethod=getResponseRateValue&fromDate=2015-01-01&toDate=2015-02-01
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?getMethod=getResponseRateValue&fromDate=2015-01-01&toDate=2015-02-01
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
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 (with super API):
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
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?getMethod=getNumResponsesValue
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
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 (with super API):
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
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?getMethod=getBlastResults
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
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 (with super API):
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
Example syntax (with sub-API key):
GET https://app.customerthermometer.com/api.php?getMethod=getComments
Additional header: Authorization: Bearer 58d03ed3c7f7e8e742e6709f48f26ac94689a5fba3c412c37b5fdbbc
Return Type: XML
