keyboard_return Back to docs
Survey Parameters
Inclivio sends several values to your participants' surveys to help you track survey completion, structure the flow of your survey, and capture metadata in your final dataset. With only one exception, these parameters are sent automatically and do not require any additional setup on Inclivio. These values are sent in the form of key/value pairs in the survey URL. Except for the first key/value pair, these parameters take the form of &key=value which is appended to the survey URL (e.g., https://example.com?key1=value1&key2=value2). On this page you will find information about:
Inclivio sends the following survey parameters:
  • projectid
    Alphanumeric code (20 characters) unique to each project. The value of projectid can be found at the top of your project's page.
  • scheduleid
    Alphanumeric code (20 characters) unique to each schedule. The value of scheduleid can be found at the top of each schedule's page.
  • participantid
    Alphanumeric code (20 characters) unique to each participant. Use this to track participants across surveys. Each participant's unique ID can be found at the top of their participant page.
  • pingid
    A unique alphanumeric code used to identify each scheduled ping. This value is used in conjunction with our survey callback API to notify Inclivio when surveys have been completed. The pingid is constant across modalities (SMS, email) and reminders.
  • customid
    Optional ID to identify your participants, located in the participant page. This value is not automatically generated (you must add this yourself). Duplicate values across participants are allowed.
  • daynumber
    Numeric value indicating the Nth day of the schedule, starting at 1. For example, if your schedule is applied 1 day after enrollment and Participant A enrolls on 1/1/2022, daynumber will be equal to 1 for all pings sent on 1/2/2022, 2 for all pings sent on 1/3/2022, etc.
  • pingnumber
    Numeric value indication the Nth ping of the day per schedule, starting at 1. For example, if your schedule indicates 5 pings per day, pingnumber will be set to 1 for the first ping of the day, 2 for the second, etc.
  • remindernumber
    Numeric value indicating whether the ping was sent at the original scheduled time remindernumber = 0 or if it was sent as a reminder (remindernumber > 0)
  • pingtotalschedule
    Numeric value indicating the total number of pings sent to the participant per schedule, at the time that the ping was sent, starting at 1. For example, if the participant has been enrolled in the study for 10 days and receives 5 pings per day on schedule X, pingtotalschedule on the 1st ping of day 11 on schedule X will be 51.
  • pingtotalproject
    Numeric value indicating the total number of pings sent to the participant per project, at the time that the ping was sent, starting at 1. For example, if the participant has been enrolled in the study for 10 days and receives 5 pings per day across all schedules, pingtotalproject on the 1st ping of day 11 will be 51.
  • pingtotalcumulative
    Numeric value indicating the total number of pings sent to the participant per project, at the time that the ping was clicked on by the participant, starting at 1. For example, if the participant has been enrolled in the study for 10 days and receives 5 pings per day across all schedules, pingtotalcumulative on the 1st ping of day 11 will be 51 for any ping (1-51) that is clicked on day 11.
  • numclicks
    Numeric value indicating the number of times the participant has clicked on this ping. Starts at 1 (i.e., the first click with have a numclicks value of 1).
  • nclickedschedule
    Numeric value indicating how many surveys have been clicked on from the schedule in which the ping was sent. For example, if you have two schedules, Schedule A and Schedule B, the current ping (i.e., survey) was sent from Schedule B, and your participant has clicked on 5 surveys from Schedule A and 2 surveys from Schedule B, nclickedschedule will be equal to 2. Duplicate clicks (i.e., clicking on the same survey from the same schedule more than once) are not added to this value. This parameter includes the participant's click on the current ping (if it is their first click on this ping).
  • ncompletedschedule
    Numeric value indicating how many surveys have been marked as complete using Inclivio's survey completion API, from the schedule in which the ping was sent. Duplicate completions (i.e., completing the same survey from the same schedule more than once) are not added to this value. For example, if you have two schedules, Schedule A and Schedule B, the current ping (i.e., survey) was sent from Schedule B, and your participant has completed 5 surveys from Schedule A and 2 surveys from Schedule B, ncompletedschedule will be equal to 2. This parameter is sent to your survey with the participant and reflects the most up-to-date information at the time the participant was sent to the survey (i.e., does not reflect actions taken within the survey). Therefore, if you choose to use this parameter to inform the participant how many surveys they have completed at the end of their current survey, you will need to add 1 to this value.
  • nclickedtotal
    Numeric value indicating the project-wide total number of pings the participant has clicked on. Duplicate clicks (i.e., clicking on the same survey from the same schedule more than once) are not added to this value. For example, if you have two schedules, Schedule A and Schedule B and your participant has clicked on 5 surveys from Schedule A and 2 surveys from Schedule B, nclickedtotal will be equal to 7. This parameter includes the participant's click on the current ping (if it is their first click on this ping).
  • ncompletedtotal
    Numeric value indicating the project-wide total number of surveys have been marked as complete using Inclivio's survey completion API. Duplicate completions (i.e., completing the same survey from the same schedule more than once) are not added to this value. For example, if you have two schedules, Schedule A and Schedule B, the current ping (i.e., survey) was sent from Schedule B, and your participant has completed 5 surveys from Schedule A and 2 surveys from Schedule B, ncompletedtotal will be equal to 7. This parameter is sent to your survey with the participant and reflects the most up-to-date information at the time the participant was sent to the survey (i.e., does not reflect actions taken within the survey). Therefore, if you choose to use this parameter to inform the participant how many surveys they have completed at the end of their current survey, you will need to add 1 to this value.
  • pingtimestamp
    String indicating the time in UTC that the ping was sent. Takes the format Www, dd Mmm yyyy hh:mm:ss GMT. For example, pingtimestamp for a ping sent right now would have the following value: Fri, 13 May 2022 03:55:12 GMT
  • responsetimestamp
    String indicating the time in UTC that the ping was clicked on. Takes the format Www, dd Mmm yyyy hh:mm:ss GMT. For example, responsetimestamp for a ping clicked on right now would have the following value: Fri, 13 May 2022 03:55:12 GMT
  • timezone
    String indicating the participant's timezone in UTC offset. Takes the format GMT+-HMM. For example, a participant in Pacific Daylight Time will have the value GMT-700 and a participant in Eastern Daylight Time will have the value GMT-400.
  • modality
    String indicating how the ping was sent. Takes the value SMS for pings sent by text message and email for pings sent by email.
  • randomsequence
    Numeric value used to implement within-person experimental designs. This value is set within each schedule. If 'None' is selected, this value is left blank. If 'All Pings' is selected, a value between 1 and the total number of pings contained within that schedule will be sampled without replacement. If 'All Days' is selected, a value between 1 and the total number of days contained within that schedule will be sampled without replacement (if multiple pings per day, each will contain the same randomsequence on any given day).
Custom Survey Parameters

You can also create your own custom survey parameters to control the flow of your survey and track additional information over time. For example, imagine you are conducting experience sampling research with individuals diagnosed with a substance use disorder. You may want to ask one group about alcohol use and another about marijuana use. In this case, it would be helpful to add your own survey parameter called substance (you can name these whatever you want, but it is helpful to keep it meaningful) that you assign different values to for each participant.

To create your own custom survey parameters:

  1. Projects > {Project Name}
  2. Participants > {Participant Name}
  3. Scroll down to 'Custom Survey Parameters' and click on the Add Parameter button

Adding Survey Parameters As Data In Your Survey

Qualtrics® reads survey parameters in the form of embedded data, which are controlled in your survey flow.

  1. Survey > Survey Flow
  2. Select 'Add a New Element Here'
  3. Select 'Embedded Data'
  4. Add all survey parameters sent by Inclivio, leaving the value as the default ('Value will be set from Panel or URL'). Select 'Move' at the bottom of this box and move the bedded data to the top of your survey flow, which will allow you to use these values to control the flow of your survey.

REDCap® reads survey parameters in the form of a text box field with the @HIDDEN-SURVEY Action Tag / Field Annotation. Action Tags in REDCap® surveys allow you to customize the behavior of your field (i.e., question). The @HIDDEN-SURVEY action tag hides your questions from participants but still includes it in your survey flow, allowing REDCap® to unobstrusively capture survey parameter metadata.

  1. Click Add Field to add a new survey item
  2. Select 'Text Box (Short Text, Number, Date/Time, ...)
  3. Click on the 'Action Tags / Field Annotation' box. In the Logic Editor, type @HIDDEN-SURVEY and select 'Update & Close Editor'
  4. In the 'Variable Name' box, enter the name of the survey parameter you wish to include in your survey's metadata. For example, to capture the participantid parameter, enter 'participantid' as the variable name. Optionally use the Field Label box to write a description of the survey parameter to help stay organized.
  5. Click 'Save' to add the field to your survey. Repeat these steps for each of the survey parameters you wish to include in your survey.