Insert-response API

Evan McGivern

Updated June 14, 2022 18:03

You can use the API to post responses from your server.

Request

POST https://app.satismeter.com/api/responses

Headers

Content-Type: application/json

Body

{
  "writeKey": "WRITE_KEY",
  "campaign": "CAMPAIGN_ID",
  "method": "In-App",
  "answers": [
    {
      "id": "QUESTION_ID",
      "value": "QUESTION_ANSWER"
    }
  ],
  "userId": "007",
  "traits": {
    "name": "James Bond",
    "email": "007@sis.gov.uk"
  }
}

{ writeKey } holds a key that is used to identify the project and authorize the request, replace "WRITE_KEY" with the actual project write-key (can be found on SatisMeter > Settings > Integrations > API keys).
{ campaign } represents the survey for the response to be associated with, replace "CAMPAIGN_ID" with the actual survey ID (can be found on SatisMeter > Settings > Integrations > API keys).
{ method } represents survey delivery method and can take either "In-App" (for web app), "Mobile" (for native mobile app), or "Email" as a value. Optional defaults to "In-App" if not set explicitly.
{ answers } is an array that contains a list of objects, representing answers to the survey questions. Each object should have an { id } field, holding an ID of the question (can be found on SatisMeter > Settings > Integrations > API keys), as well as a { value } field, holding an answer to the question, which can be either an integer (for rating questions) or a string (for free-text and single-choice questions).
{ userId } represents an ID of the user, as used in your system
{ traits } is an object that contains any user-data to be associated with the response. Optional, existing user data will be used if the field is not present.

Anonymous surveys

If a user can not be identified and your survey targeting allows anonymous response-collection, you should use an { anonymousId } field instead of the { userId } field, to provide some form of identification. The { traits } field can be used as usual.

Troubleshooting

Error 400 Duplicate response

You might receive the error if user traits do not match survey targeting conditions, which can happen if you recently created a response associated with the user or if the user traits simply don't match the conditions.

Force-create a response

During the development or debugging of the API integration you might want to skip some checks we perform before creating a response - eg targeting-conditions check or check for duplicate-response creation. If that is the case, add a { forceSurvey } field set to { true }. We do not encourage using the field in production.