keyboard_return Back to docs
Custom Survey Parameters API

Inclivio sends metadata to your survey in the form of survey parameters that allow you to control the flow of your survey and track completion over time. You can send additional survey parameters at the participant level to track data unique to each participant and control what they see in their surveys. For example, you might send information to your survey indicating the between-subjects experimental condition of which each participant belongs, then show them different survey content accordingly.

Inclivio's custom survey parameters API can be used to add, change, and remove survey parameters dynamically. This is useful in situations where you want to control the flow of your surveys based on a participant's previous response (e.g., present a questionnaire after participants indicate engaging in a certain behavior). You can also use this API to dynamically present content to participants based on previous responses.

To add, change, and remove custom survey parameters, send a POST request with pingid = {pingid} and survey-parameter = {key=value} in the body of the API call. If the key does not yet exist for that participant, it will be added as a new custom survey parameter. If the key already exists for that participant, the value will be updated. If the value is missing from the right hand side of the API call (e.g., survey-parameter = parameterName=). All changes will be reflected in subsequent pings sent to that participant.
How to set up your survey to interact with Inclivio's Survey Completion API

The following example shows you how to achieve this using the web service feature in Qualtrics®.

  1. Capture the pingid survey parameter as embedded data (refer to the Survey Parameters documentation for more information)
  2. Add Below > Web Service
  3. Add the following information:
    • Method: POST
    • URL: https://incliv.io/surveyCallback
  4. Select 'Add a body parameter to send to web service'
  5. Set the parameter as pingid and the value as ${e://Field/pingid} (this is equivalent to Insert Piped Text > Embedded Data Field > pingid).
  6. Add a second body parameter by pressing the button. Add your project's API key (found in Project > Settings > Project API Key). Set the parameter as api-key and the value as your project's API key.
  7. Add another parameter called survey-parameter and the value as the key/value pair of the survey parameter you want to add. For example, if you want to add the custom survey parameter usedSubstance with a value of alcohol you would make the following API call from Qualtrics®. You can also change an existing custom survey parameter using the same method.
    To remove the custom survey parameter usedSubstance from a participant's future pings, leave the right hand side blank:
    You can include a participant's response as the value of your parameter by inserting piped text into the API call (Insert Piped Text > Survey Question).
    To capture this data in future surveys, include usedSubstance as embedded data and then pipe this into your question text:
    8. To make multiple changes to a participant's custom survey parameters in one survey response, you need to make the API call once per survey parameter. You can make as many changes to custom survey parameters as you would like.