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. This can be found inside the “Push Options” area of your Customer Thermometer account:

Push Options

On that page, there is a API Information section.

API key configuration

There are two sets of API keys available. Your ‘Super API key’ which allows you full access to the account, API and is used for some third-party integrations.
Or an sub-API key, which is only available for communicating with our API. All API calls into Customer Thermometer must be made using an key.
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 keys, you’ll also find the API request URL, used to make calls via our RESTful API.

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

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