Account
Javascript Embed
Api

API Methods

Thermostat API methods mostly revolve around sending surveys, however we provide access to get information about your surveys as well.

Error Responses

Errors return 4** HTTP status codes and usually will include a json array of error issues.

Surveys

The following methods are available to retrieve information about a team's surveys.

GET /api/surveys

A list of all your surveys.

Request:

curl -H "Accept: application/json" \
     -H "Authorization: Bearer some-long-token" \
     https://thermostat.io/api/surveys

Response:

[
  {
    "id": 1234,
    "archived": false,
    "name": "Foo Bar Support",
    "slug": "foo-bar-support",
    "headline": "We'd love your feedback on The Foo Bar",
    "question": "How was the help you received?",
    "label_scale_0": "Not Likely",
    "label_scale_10": "Very Likely",
    "submit_survey": "Submit Feedback",
    "msg_general_thanks": "Thanks! ?",
    "msg_promoter": "You are the best. We love you.",
    "msg_passive": "Thanks for the feedback.",
    "msg_detractor": "Sorry to hear things are not going well...",
    "created_at": "2018-04-28 14:03:26",
    "publicly_available": 0,
    "publicly_show_passives": 0,
    "publicly_show_detractors": 0,
    "public_key": "7716b972621a7806",
    "explanation": null,
    "lockout_period": 180,
    "campaign_enabled": false,
    "reply_to_name": null,
    "reply_to_email": null,
    "daily_survey_target": 1000,
    "type": "csat",
    "csat_1": "Terrible",
    "csat_2": "Bad",
    "csat_3": "Okay",
    "csat_4": "Good",
    "csat_5": "Great!",
    "email_subject": "How was our support?",
    "email_footer": "You are receiving this email because...",
    "anonymous": 0,
    "show_feedback_promoter": 1,
    "show_feedback_passive": 0,
    "show_feedback_detractor": 0,
    "feedback_question_promoter": "What is the most important...",
    "feedback_question_passive": "What is the most important...",
    "feedback_question_detractor": "What is the most important...",
    "score": 76,
    "feedback_count": 796,
    "promoters": 0,
    "passives": 0,
    "detractors": 1005,
    "satisfied": "762",
    "dissatisfied": "243",
    "response_count": 1005,
    "name_with_type": "The Foo Bar (CSAT)",
    "team": {
      "name": "The Foo Bar",
      "slug": "the-foo-bar",
      "created_at": "2018-04-28 14:01:31"
    }
  },
  {
   ...
  }
]

GET /api/survey/####

Details on a survey.

Note the survey ID in the URL.

Request:

curl -H "Accept: application/json" \
     -H "Authorization: Bearer some-long-token" \
     https://thermostat.io/api/survey/1234

Response:

{
  "id": 1234,
  "archived": false,
  "name": "Foo Bar Support",
  "slug": "foo-bar-support",
  "headline": "We'd love your feedback on The Foo Bar",
  "question": "How was the help you received?",
  "label_scale_0": "Not Likely",
  "label_scale_10": "Very Likely",
  "submit_survey": "Submit Feedback",
  "msg_general_thanks": "Thanks! ?",
  "msg_promoter": "You are the best. We love you.",
  "msg_passive": "Thanks for the feedback.",
  "msg_detractor": "Sorry to hear things are not going well...",
  "created_at": "2018-04-28 14:03:26",
  "publicly_available": 0,
  "publicly_show_passives": 0,
  "publicly_show_detractors": 0,
  "public_key": "7716b972621a7806",
  "explanation": null,
  "lockout_period": 180,
  "campaign_enabled": false,
  "reply_to_name": null,
  "reply_to_email": null,
  "daily_survey_target": 1000,
  "type": "csat",
  "csat_1": "Terrible",
  "csat_2": "Bad",
  "csat_3": "Okay",
  "csat_4": "Good",
  "csat_5": "Great!",
  "email_subject": "How was our support?",
  "email_footer": "You are receiving this email because...",
  "anonymous": 0,
  "show_feedback_promoter": 1,
  "show_feedback_passive": 0,
  "show_feedback_detractor": 0,
  "feedback_question_promoter": "What is the most important...",
  "feedback_question_passive": "What is the most importan...",
  "feedback_question_detractor": "What is the most important...",
  "score": 76,
  "feedback_count": 796,
  "promoters": 0,
  "passives": 0,
  "detractors": 1005,
  "satisfied": "762",
  "dissatisfied": "243",
  "response_count": 1005,
  "name_with_type": "The Foo Bar (CSAT)",
  "team": {
    "name": "The Foo Bar",
    "slug": "the-foo-bar",
    "created_at": "2018-04-28 14:01:31"
  }
}

Sending Surveys

The following methods are available to help send surveys to your users & customers;

GET /api/ping

Check if a person should be surveyed. This is used to ascertain if a customer should be surveyed. If the user has been surveyed with the set number of "DAYS BEFORE USER CAN RETAKE SURVEY" option, this will return an error response.

This helps prevent over-surveying customers and should be used before sending any user a survey through the API.

Please cache this method on the client end to avoid excessive load on Thermostat servers.

HTTP Status Code Responses

  • 200: This person is OK to be surveyed based on the survey's frequency settings
  • 422: This person should not be surveyed right now based on the survey's frequency settings

URL Parameters:

  • survey_id - Required.
  • cid - A customer ID of your own definition. Useful if you don't know their email.
  • email - The person's email.

Request:

curl -i -H "Accept: application/json" \
     -H "Authorization: Bearer some-long-token" \
     https://thermostat.io/api/ping?survey_id=1234&email=person%40example.org

Can Survey Response:

// HTTP Headers/Status Code
HTTP/1.1 200 OK
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 196

Should Not Survey Response:

// HTTP Headers/Status Code
HTTP/1.1 422 Unprocessable Entity
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 196

Please URL-encode the URL query string.

In our example above, note that the @ symbol in the email has been URL-encoded to %40.

POST /api/survey/####/response

Add a survey response to a survey. This API method is not restricted by the maximum daily survey setting.

Note the survey ID in the URL.

Request Parameters:

  • score - Required - NPS score on the 0-10 scale
  • name - Responder's name
  • email - Responder's email.
  • cid - A unique ID for this responder that you set. From a CRM, device ID, etc.
  • feedback - Text feedback from this person if collected. Limited to 8000 characters.
  • device - One of: desktop, mobile, tablet

Request:

curl -X POST \
     -H "Accept: application/json" \
     -H "Authorization: Bearer some-long-token" \
     -d "score=6" \
     -d "[email protected]" \
     -d "device=desktop" \
     https://thermostat.io/api/survey/1234/response

Success Response:

HTTP/1.1 200 OK

{
  "uuid":"c1de7afd-262d-4995-afb0-cad437ffa11b"
}

Error Response:

Here we see an error response for invalid entry (we sent a score of 6 on a CSAT survey, which has a max score of 5).

HTTP/1.1 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "score": [
      "The selected score is invalid."
    ]
  }
}

Here we see the result if the user has already been surveyed.

Note: The response is plaintext, not json. Please use the /api/ping method before surveying to avoid this response.

HTTP/1.1 400 Bad Request
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 197

User not eligible to take this survey at this time.

POST /api/survey/####/email

Add a user's email to a survey's email list. This is most useful for the survey Campaign feature.

Note the survey ID in the URL.

Request Parameters:

  • email - Required - A valid email address.
  • name - User's name
  • cid - A unique ID for this responder that you set. From a CRM, device ID, etc.
  • custom field(s) - A custom field. Set any name and any value. Any custom fields listed that do not exist will be created. You can add multiple fields.

Request:

curl -X POST \
     -H "Accept: application/json" \
     -H "Authorization: Bearer some-long-token" \
     -d "[email protected]" \
     -d "name=Morgan Doe" \
     -d "paying_customer=yes" \
     -d "drip_sequence=foo" \
     https://thermostat.io/api/survey/1234/email

Note the addition of two custom fields:

  • paying_customer set to "yes"
  • drip_sequence set to "foo"

Fields that don't already exist will be created as type "text". You can create fields of different types within the survey's "Fields" settings.

Success Response:

HTTP/1.1 201 Created

{
  "survey_id": 4,
  "email": "[email protected]",
  "cid": null,
  "name": "Morgan Doe",
  "custom_fields": {
      "paying_customer": "yes",
      "drip_sequence": "foo"
  },
  "updated_at": "2018-11-06 20:20:26",
  "created_at": "2018-11-06 20:20:26",
  "id": 1234
}

Error Response:

HTTP/1.1 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ]
  }
}

POST /api/survey/####/sendnow

Immediately sends a survey to the users email.

This ignores the survey's "DAYS BEFORE USER CAN RETAKE SURVEY" option

Note the survey ID in the URL.

Request Parameters:

  • email - Required - A valid email address.
  • name - User's name
  • cid - A unique ID for this responder that you set. From a CRM, device ID, etc.
  • custom field(s) - A custom field. Set any name and any value. Any custom fields listed that do not exist will be created. You can add multiple fields.
curl -X POST \
     -H "Accept: application/json" \
     -H "Authorization: Bearer some-long-token" \
     -d "[email protected]" \
     -d "name=Morgan Doe" \
     -d "paying_customer=no" \
     -d "foo_bar=baz" \
     https://thermostat.io/api/survey/1234/sendnow

Note the addition of two custom fields:

  • paying_customer set to "no"
  • foo_bar set to "baz"

Fields that don't already exist will be created as type "text". You can create fields of different types within the survey's "Fields" settings.

Success Response:

HTTP/1.1 201 Created

{
  "survey_id": 4,
  "email": "[email protected]",
  "cid": null,
  "name": "Morgan Doe",
  "custom_fields": {
      "paying_customer": "no",
      "foobar": "baz"
  },
  "updated_at": "2018-11-06 20:23:19",
  "created_at": "2018-11-06 20:23:19",
  "id": 1234
}

Error Response:

HTTP/1.1 422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ]
  }
}