Skip to main content

Working with Surveys using the Conversational APIs

This guide walks through the Conversational APIs that allow you to take a survey programmatically. By using these APIs, you can create new user interfaces to surveys and use the Conversational APIs to record survey responses.

Overview​

  1. Create a session with Create Survey Session - returns first page of questions
  2. Update the session with Update Survey Session to submit responses and navigate
  3. Resume a session with Resume Survey Session to continue an incomplete session
  4. Delete a session with Delete Survey Session to cancel without saving

Supported Question Types​

Authentication​

All requests require authentication. See API Authentication for details.

API Token​

const headers = {
    "X-API-TOKEN": "your_api_token_here",
    "Content-Type": "application/json"
};

OAuth 2.0​

Required scopes:

  • read:survey_sessions - Resume sessions
  • write:survey_sessions - Create, update, and delete sessions

Creating a Session​

Start a new survey session with POST /surveys/{surveyId}/sessions-v2.

Anonymous Session​

const apiToken = process.env.Q_API_TOKEN;
const dataCenter = process.env.Q_DATA_CENTER;
const surveyId = "SV_123456789";

const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2`;
const headers = {
    "X-API-TOKEN": apiToken,
    "Content-Type": "application/json"
};

const data = {
    language: "EN",
    questionsPerPage: 1,
    channel: "anonymous",
    embeddedData: {
        userId: "12345",
        source: "mobile_app"
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});

const session = await response.json();
console.log(`Session ID: ${session.sessionId}`);

Response​

{
  "sessionId": "FS_123456789",
  "done": false,
  "endMessage": null,
  "embeddedData": {
    "Q_Language": "EN",
    "userId": "12345"
  },
  "questions": [
    {
      "id": "QID1",
      "type": "mc",
      "display": "What is your favorite color?",
      "required": "force",
      "multiSelect": false,
      "choices": [
        {
          "id": "1",
          "display": "Red"
        },
        {
          "id": "2",
          "display": "Blue"
        },
        {
          "id": "3",
          "display": "Green"
        }
      ]
    }
  ]
}
FieldDescription
sessionIdUnique session identifier - save this to update the session.
donefalse if survey continues, true if complete.
endMessageSurvey completion message (only when done: true).
embeddedDataEmbedded data defined in survey flow.
questionsArray of question objects for current page.

Distribution-Based Session​

Use distribution-based sessions to track which recipients completed surveys and pull in recipient-specific embedded data.

const apiToken = process.env.Q_API_TOKEN;
const dataCenter = process.env.Q_DATA_CENTER;
const surveyId = "SV_123456789";

const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2`;
const headers = {
    "X-API-TOKEN": apiToken,
    "Content-Type": "application/json"
};


const data = {
    language: "EN",
    questionsPerPage: 1,
    channel: "distribution",
    distribution: {
        distributionId: "EMD_123456789",
        recipientId: "CGC_123456789"
    },
    embeddedData: {
        campaign: "spring_2026"
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});

Employee Engagement Session​

For Employee Engagement surveys, use the EI Link channel to associate responses with specific projects and participants.

const apiToken = process.env.Q_API_TOKEN;
const dataCenter = process.env.Q_DATA_CENTER;
const surveyId = "SV_123456789";

const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2`;
const headers = {
    "X-API-TOKEN": apiToken,
    "Content-Type": "application/json"
};


const data = {
    language: "EN",
    questionsPerPage: 1,
    channel: "eiLink",
    eiLink: {
        projectId: "TS_123456789",
        personId: "P_123456789",
        relationship: "manager",
        evaluatorId: "P_123456789"
    },
    embeddedData: {
        department: "engineering"
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});

The relationship field specifies the respondent's relationship to the person being evaluated (e.g., "Self", "manager", "peer", "direct_report").

Updating a Session​

Submit responses and navigate with POST /surveys/{surveyId}/sessions-v2/{sessionId}.

Text Entry Response​

const sessionId = "FS_123456789";
const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2/${sessionId}`;

const data = {
    navigation: "next",
    responses: {
        QID1: "This is my answer"
    },
    embeddedData: {
        completedSection: "intro"
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});

const nextPage = await response.json();

Multiple Choice Response​

// Single select
const sessionId = "FS_123456789";
const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2/${sessionId}`;
const data = {
    navigation: "next",
    responses: {
        QID1: {
            "1": {
                selected: true
            }
        }
    }
};

// Multi-select with text entry
const sessionId = "FS_123456789";
const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2/${sessionId}`;
const data = {
    navigation: "next",
    responses: {
        QID2: {
            "1": { selected: true },
            "2": { selected: true },
            "3": { selected: true, text: "Purple" }
        }
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});

NPS Response​

const sessionId = "FS_123456789";
const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2/${sessionId}`;
const data = {
    navigation: "next",
    responses: {
        QID1: {
            selected: 9
        }
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});

Matrix Response​

const sessionId = "FS_123456789";
const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2/${sessionId}`;
const data = {
    navigation: "next",
    responses: {
        QID1: {
            1: {
                scalePoints: {
                    1: { selected: true }
                }
            },
            2: {
                scalePoints: {
                    3: { selected: true }
                },
                text: "Additional comment"
            }
        }
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});

Slider Response​

const sessionId = "FS_123456789";
const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2/${sessionId}`;
const data = {
    navigation: "next",
    responses: {
        QID1: {
            1: { value: 75 },
            2: { value: null, text: "N/A" }
        }
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});

Form Response​

const sessionId = "FS_123456789";
const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2/${sessionId}`;
const data = {
    navigation: "next",
    responses: {
        QID1: {
            1: "John",
            2: "Doe",
            3: "john.doe@example.com"
        }
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});

Rank Order Response​

const sessionId = "FS_123456789";
const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2/${sessionId}`;
const data = {
    navigation: "next",
    responses: {
        QID1: {
            1: { value: 1 },
            2: { value: 3 },
            3: { value: 2, text: "Good option" }
        }
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});
CommandDescription
nextSubmit responses and advance to next page.
previousGo back to previous page.
saveProgressSave responses without advancing.
closeSubmit final responses and complete survey.

Going Back to Previous Page​

// Navigate to previous page
const data = {
    navigation: "previous"
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});

const previousPage = await response.json();

// The responses field will contain previously saved answers
// You can update those answers and navigate forward again

You can optionally include new responses when navigating backwards to update answers on the current page before going back.

Saving Progress Without Advancing​

const data = {
    navigation: "saveProgress",
    responses: {
        QID1: "Partial answer"
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});
// Returns same page with saved responses

Closing a Survey​

const data = {
    navigation: "close",
    responses: {
        QID5: "Final answer"
    }
};

const response = await fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
});

const result = await response.json();

if (result.done) {
    console.log(`Survey complete: ${result.endMessage}`);
}

Resuming a Session​

Retrieve the current state of an incomplete session with GET /surveys/{surveyId}/sessions-v2/{sessionId}.

const sessionId = "FS_123456789";
const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2/${sessionId}`;

const response = await fetch(url, { headers: headers });
const sessionState = await response.json();

// Check if survey is complete
if (sessionState.done) {
    console.log("Survey already complete");
} else {
    // Display current questions
    for (const question of sessionState.questions) {
        console.log(`Question: ${question.display}`);
    }
    
    // Check for previously saved responses
    if (sessionState.responses) {
        console.log("\nPreviously saved answers:");
        for (const [qId, answer] of Object.entries(sessionState.responses)) {
            console.log(`  ${qId}:`, answer);
        }
    }
}

The response includes:

  • questions: Current page of questions
  • responses: Previously saved answers for questions on the current page
  • embeddedData: Current embedded data values
  • done: Completion status

Note: The responses field only includes answers for questions on the current page, not all questions in the survey.

Deleting a Session​

Cancel a session without recording responses with DELETE /surveys/{surveyId}/sessions-v2/{sessionId}.

const sessionId = "FS_123456789";
const url = `https://${dataCenter}.qualtrics.com/API/v3/surveys/${surveyId}/sessions-v2/${sessionId}`;

const response = await fetch(url, {
    method: "DELETE",
    headers: headers
});

if (response.status_code === 200) {
    console.log("Session deleted");
}

Important: Deleting a session does NOT record responses. To close a session and save responses, use navigation: "close" in the update endpoint.

Error Handling​

All errors follow a standard format:

HTTP StatusError CodeDescription
400SVY_1.0Bad request - invalid surveyId, sessionId, or malformed request body
403SVY_1.1Forbidden - authentication/authorization failure from downstream service
403SVY_1.3Forbidden - brand not authorized for Survey Sessions V2 API
404SVY_1.2Not found - session or survey doesn't exist
500SVY_1.5Internal server error - downstream service failure
500SVY_2.xInternal server error - unexpected failures

Error Response Structure​

json
{
  "meta": {
    "httpStatus": "400 - Bad Request",
    "error": {
      "errorCode": "SVY_1.0",
      "errorMessage": "VALIDATION_ERROR: Invalid response format"
    }
  }
}

Common Error Scenarios​

Validation Errors (400)​

  • Invalid request body schema
  • Invalid question response format
  • Missing required fields

Session Errors (400/404)​

  • SESSION_NOT_FOUND - Session expired or doesn't exist
  • INVALID_NAVIGATION - Invalid navigation command (e.g., going back when disabled)

Survey State Errors (400)​

  • SurveyExpired - Survey past end date
  • SurveyInactive - Survey is turned off
  • DistributionLinkExpired - Distribution link no longer valid
  • FormTooLarge - Survey too complex for headless API
  • NotSessionsV2Compatible - Survey uses unsupported features

Authorization Errors (403)​

Brand not enabled for Survey Sessions V2 Invalid credentials or insufficient permissions

Server Errors (500)​

Unexpected downstream failures

Best Practices​

  1. Store the session ID - You'll need it for all subsequent requests.

  2. Check the done flag - When true, the survey is complete and no further updates are allowed.

  3. Handle validation errors - Re-display questions with error messages and let users correct their responses.

  4. Respect question requirements - Check the required field (force, request, or off) and validate accordingly:

    • force - Required, user must answer
    • request - Optional but encouraged
    • off - Optional

  5. Use appropriate data types - Match response format to question type (string for text entry, object for multiple choice, etc.).

  6. Only one update at a time - The API rejects concurrent updates to the same session. Queue requests if needed.

V1 API (Deprecated)

Deprecated API​

The V1 Survey Sessions API (/surveys/{surveyId}/sessions) is deprecated and will be removed in a future release.

Please migrate to the V2 API (/surveys/{surveyId}/sessions-v2) documented above.

V1 limitations compared to V2:

  • Only supports 3 question types (Multiple Choice, Text Entry, Descriptive Block)
  • Uses advance field instead of navigation commands
  • No support for Matrix, NPS, Form, Slider, or Rank Order questions
  • No previous navigation or session deletion
  • Different response object structure

Starting a Survey Session (V1)​

The first step in taking a survey is to start a new session with the Create Session API call. Every time this API is called a new session will be created. The response object will include a session id that you will need to keep track of in order to answer questions and advance through the survey using the Update Session API.

Code and Qualtrics Support​

Our support team does not offer assistance or consultation on custom coding, but you can always try asking our community of dedicated users. If you'd like to know more about our custom coding services you can commission, please contact your Qualtrics Account Executive.

The following code example shows how to create a survey session:

# Create Survey Session

import os
import requests

# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"]
dataCenter = os.environ["Q_DATA_CENTER"]

surveyId = "SV_eyRJDHHhxbvI6aN"

baseUrl = "https://{0}.qualtrics.com/API/v3/surveys/{1}/sessions".format(dataCenter, surveyId)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

data = { 
  "language": "EN",
  "embeddedData": {
     "storeId": "48123"
   }
}
response = requests.post(baseUrl, json=data, headers=headers)
print(response.text)

Survey Session Request Object (V1)​

As shown in the previous code example, you can provide an optional request object to configure the survey session. An example of a complete request object is shown below:

{
  "language": "EN",
  "embeddedData": {
    "storeNumber": "123"
  },
  "recipientId": "MLRP_1234567890",
  "distributionId": "EMD_1234567890"
}

The following table describes the members of the request object:

NameTypeDescription
languageStringThe language field specifies the language of the survey questions. It must be an uppercase version of a supported language. For a list of the language codes supported by Qualtrics, see Language Codes. If a question is not translated in the given language it will use the survey's default language. The language cannot be changed mid-survey.
embeddedDataObjectThe embeddedData object can be set when starting the survey. You can also specify additional embedded data during the survey by using the Updating a Survey Session API.
recipientId and distributionIdStringThe recipientId and distributionId fields can be specified to associate a survey session to a Qualtrics panel member and distribution. See Generate Distribution Links for more information on creating a distribution. Both fields are optional, but if a distributionId is specified there must also be a recipientId. The recipientId field can be used by itself to pull in any recipient embedded data.

Survey Session Response Object (V1)​

The response to all Survey Session API calls will have the same structure. The response body will contain the current session id, the questions that the respondent should be asked, any embedded data that has been defined in the survey flow, any preexisting response data (default choices), and an end of survey message if there are no more questions.

All response bodies will be returned as JSON (including errors). The following shows an example of a response object:

{
  "result": {
    "sessionId": "FS_3jVhuKYaCoptXkW",
    "questions": [
      {
        "questionId": "QID3",
        "type": "db",
        "display": "Thanks for taking this survey. Please answer the following questions.",
        "options": {}
      },
      {
        "questionId": "QID1",
        "type": "mc",
        "display": "What is your favorite color?",
        "options": {
          "multiSelect": false
        },
        "choices": [
          {
            "choiceId": "1",
            "display": "red",
            "textual": false
          },
          {
            "choiceId": "2",
            "display": "green",
            "textual": false
          },
          {
            "choiceId": "3",
            "display": "other",
            "textual": true
          }
        ]
      },
      {
        "questionId": "QID2",
        "type": "te",
        "display": "Tell me why it's your favorite color",
        "options": {}
      }
    ],
    "embeddedData": {
      "customerId": "123"
    },
    "responses": {
      "QID1": {
        "1": {
          "selected": true
        }
      }
    },
    "done": false
  }
}

The response object contains the following members:

NameTypeDescription
sessionIdStringThe sessionId field contains the current session ID. Keep track of this ID to submit responses to questions.
embeddedDataObjectThe embeddedData object contains the embedded data that is defined in the survey flow. Only embedded data values defined in the survey flow will be returned. You can set arbitrary embedded data values when you start or update a session, but those values will not be returned here unless they are defined in the survey flow.
questionsArray of ObjectsThe questions array contains question definitions. The order of the questions in the array is the order in which they should be asked. The order will reflect any question randomization defined in the survey. Only a subset of questions are supported by the survey session APIs. Each question will have a type to distinguish between them. More details are in The Question Object below.
responsesArray of ObjectsThe responses array contains the recorded responses for each question on the current page. These can come from default choices or using the Updating a Survey Session API without advancing. See Updating a Survey Session for more details on the format.
doneStringThe done boolean indicates that the survey session is complete. It will be false unless the session is complete in which case it will be a string containing the end of survey message.

The Question Object (V1)​

The question object contains information about each question on the survey. There are some common fields among all types of question objects. The following table shows those common fields, and the following sections contain information about members specific to each question type.

NameTypeDescription
questionIdStringThis is the question's id. It is needed to record responses.
typeStringThe type string defines what kind of question this is. Supported question types are mc (multiple choice), te (text entry), and db (descriptive block, but also know as descriptive text).
displayStringThe display string is the question text.

Question Types (V1)​

There are three possible question types: multiple choice (mc), text entry (te), and descriptive block (db). For more information on these types of questions, see the following pages:

Multiple Choice (mc) - V1​

The following JSON shows an example of an mc or multiple choice question object:

{
  "questionId": "QID1",
  "type": "mc",
  "display": "What is your favorite color?",
  "options": {
    "multiSelect": false
  },
  "choices": [
    {
      "choiceId": "1",
      "display": "red",
      "textual": false
    },
    {
      "choiceId": "2",
      "display": "green",
      "textual": false
    },
    {
      "choiceId": "3",
      "display": "other",
      "textual": true
    }
  ]
}

The following table contains information on each of the members of the multiple choice question:

NameTypeDescription
optionsObjectThe options object defines whether multiple choices can be selected via multiSelect. For single answer (radio buttons) mc questions, it will be false, and for multiple answer (checkbox), it will be true.
choicesArray of ObjectsThe choices array contains choice objects. (Choice randomization defined in the survey may affect the order of this array.) A choice has an id that will be used to specify it as selected (see Updating a Survey Session), display is the choice text, and textual is defined if this choice allows a textual response.

Text Entry (te) - V1​

The following JSON shows an example text entry question:

{
  "questionId": "QID3",
  "type": "te",
  "display": "Tell me why it's your favorite color",
  "options": {}
}

Text entry questions don't have choices or any options. They accept any textual response.

Descriptive Block (db) - V1​

The following shows an example of a descriptive block question:

{
  "questionId": "QID7",
  "type": "db",
  "display": "Thank you for taking this survey. Please answer truthfully.",
  "options": {}
}

A db question is simply used to display text information, an image, or some other file to a respondent. You cannot answer a db question.

Updating a Survey Session (V1)​

To record the respondent's answers, use the Update Session API.

The following code example shows how to use this API:

# Update Survey Session

import os
import requests

# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"]
dataCenter = os.environ["Q_DATA_CENTER"]

surveyId = "SV_eyRJDHHhxbvI6aN"
sessionId = "FS_xfJgWwTtRXSLFD3"
 
baseUrl = "https://{0}.qualtrics.com/API/v3/surveys/{1}/sessions/{2}".format(dataCenter, surveyId, sessionId)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

data = { 
  "advance": False,
  "embeddedData": {
    "username": "johns"
  },
  "responses": {
    "QID1": {
      "3": {
        "selected": True
      }
    }
  }
}
response = requests.post(baseUrl, json=data, headers=headers)
print(response.text)

The previous example chooses answer three to the first multiple choice question and does not advance to the next question.

An example POST request body is shown below:

{
  "advance": true,
  "embeddedData": {
    "additionalEmbeddedData": "something new"
  },
  "responses": {
    "QID1": {
      "1": {
        "selected": true
      }
    },
    "QID2": "It's a nice color."
  }
}

The following table provides information on the members in the request:

NameTypeDescription
advanceBooleanThe advance field is used indicate whether to move to the next set of questions or save a respondent's current progress without moving on. Specify true to move to the next page or false to save current responses and come back later. When advance is true, it will run through any validation specified in the survey. If validation fails the same set of questions will be returned in the response body with a message about why validation failed.
embeddedDataObjectAny additional embeddedData can be set here.
responsesObjectThe responses object contains the respondent's answers to questions. The responses object is a mapping from question id to question response. The response format is different for each question type and is detailed in the next section. Descriptive block (db) questions do not accept responses so they should not be included in the responses object.

Response Types (V1)​

There are two types of responses, multiple choice (mc) responses and text entry (te) responses. Descriptive block (db) questions do not have a response.

Multiple Choice Response Types (mc) - V1​

There are two formats of multiple choice response types:

  1. An explicit response format
  2. A "fuzzy" response format.

Fuzzy Search Parameter Only Works with English Responses​

Please note that the fuzzySearch parameter only works with English language responses.

Multiple Choice Explicit Response - V1​

The explicit response format tells the API exactly which choices are selected and any textual response associated with that choice. It is an object with choice id keys that map to an object with a selected and text key. The following example shows an explicit answer to a multiple choice question:

"QID1": {
  "3": {
    "selected": true,
    "text": "blue"
  }
}

In this example, answer 3 is selected for QID1 and the textual response was blue. If multiSelect (in the options object of each choice in the choices array) is true for the mc question, include multiple choice IDs in the QID object. Any choices not included in the response are considered unselected. The following JSON shows an example of multiple choices:

"QID1": {
  "1": {
    "selected": true
  },
  "2": {
    "selected": true
  },
  "3": {
    "selected": true,
    "text": "blue"
  }
}

Multiple Choice Fuzzy Response - V1​

Using the fuzzy response format is useful for loosely matching against the choice texts. It lets Qualtrics figure out which choice should be selected based on the text of the response. For example, you ask "What if your favorite color?" with choices "Crimson Red", "Forest Green", and "Sky Blue". If the respondent responds with "red," the API will determine that "Crimson Red" is the appropriate match and mark that choice as selected. The following example shows how to supply a fuzzy match to a question:

"QID1": {
  "fuzzySearch": "red",
  "maxMatches": 1
}

The maxMatches field can be set to select multiple choices if desired. It uses some very basic string matching to determine which choice should be selected. Because of the simple nature of the algorithm, it might match too many choices or no choices at all, in which case an error will be returned. See the example error response formats of the Update Session API for details.

Text Entry Response - V1​

A text entry (te) response is simply a string. The following example shows such a response:

"QID2": "It's a nice color."

Getting the Current Survey Session (V1)​

To get the respondent's current session use the Get Session API. The following example shows how to use the Get Survey Session API:

# Get Survey Session

import os
import requests

# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"]
dataCenter = os.environ["Q_DATA_CENTER"]

surveyId = "SV_eyRJDHHhxbvI6aN"
sessionId = "FS_xfJgWwTtRXSLFD3"

baseUrl = "https://{0}.qualtrics.com/API/v3/surveys/{1}/sessions/{2}".format(dataCenter, surveyId, sessionId)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

response = requests.get(baseUrl, headers=headers)
print(response.text)

It will return the current set of questions that should be asked to the respondent as well as any saved answers. It has the same format described above. From here you can use the Updating a Survey Session API to provide answers.

Potential Errors (V1)​

If the original Create Session API request is successful, status code 201 is returned along with the session body. However, keep in mind that to start a session, the surveyId must correspond to a survey that is compatible with this API and the proper authorization headers must be included with the initial request. (See Authentication for more information.)

Create Session Errors - V1​

You may encounter errors with the following formats upon attempting to start a session.

In the case of a bad survey error, you will need to ensure your survey contains no incompatible questions and that it is currently started, active, and unexpired.

In the case of an authentication error, you will need to ensure that the correct X-API-TOKEN header was included with your request.

In the case of a survey not found error, you will need to ensure that the surveyId you are using corresponds to an existing survey.

The following shows examples of each of these errors:

{
  "error": "BadSurvey",
  "desc": "survey is incompatible.",
  "incompatibilities": {
    "questions": {
      "QID1": [
        "Unsupported question type Matrix-Likert-SingleAnswer"
      ],
      "QID2": [
        "Unsupported question type TE-FORM"
      ]
    }
  }
}
{
  "error": "BadSurvey",
  "desc": "survey is inactive."
}
{
  "error": "NotFound"
}

Note that errors with the same formats can occur for the same reasons when attempting to use the Get Session or Update Session APIs.

Updating Session Errors - V1​

There are some additional errors you should be aware of when updating sessions.

In the case of a validation error, the session cannot proceed because of validation logic within the survey. The respondent will have to pick different answers. The problems field will contain an array of objects, each with an ID of a question that did not pass validation and its associated message.

An outdated session error means that the session has expired and can no longer be updated.

Lastly, if you use the fuzzy matching feature to select responses, a fuzzy error may occur if there are no matches or if the number of matches is greater than maxMatches.

The following gives examples of these errors:

{
  "error": "ValidationErrors",
  "problems": [
    {
      "questionId": "QID1",
      "message": "Please select Choice 2"
    }
  ]
}
{
  "error": "OutdatedSession"
}
{
  "error": "FuzzyNoMatch"
}