Survey123 Tricks of the Trade: Web form URL parameters
[Updated February 28, 2020]
[Updated April 2, 2020]
[Updated July 13, 2020. Added autoRefresh]
[Updated March1, 2021. Added mode copy]
[Updated September 15, 2022. Added ?hide=leaveDialog]
[Updated September 22, 2022. Added ?forceRecalculate]
[Updated January 9, 2023. Updated ?forceRecalculate to ?recalculate]
[Updated August 25, 2023. Updated sample links]
Many web applications support the notion of URL parameters and Survey123 web forms are no exception. URL parameters allow you to dynamically pass data into your survey. This data can be used to prepopulate questions, hide questions, change the language of a form and many other things with your survey form. In this blog post, I will explore the options available in detail.
Before I start, I want to clarify that in the past we already covered how to use the Custom URL Scheme in the Survey123 field app. The concept of a Custom URL Scheme is similar to URL parameters, but they are two different things: the Custom URL Scheme applies to the Survey123 field app and the URL parameters discussed in this post only apply to web forms. That is, to forms loaded within a web browser, as opposed to loaded into the Survey123 field app in your device.
With that, lets get started:
The Basics
Lets first get familiar with how surveys get loaded into the Survey123 web app. Take the following URL:
https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765
The first part of the URL refers to the Survey123 web app: https://survey123.arcgis.com/share/ We host the Survey123 web app in our ArcGIS Online servers, and it is used to render your surveys as web forms. The second part of the URL is the unique identifier of your survey. In this particular case, it is: 1cb28b212b5542acbbdbaa35feba0765
The complete URL will open the Survey123 web app in your web browser and immediately present the survey id specified , in this case it is an Quick Tree Hazard Report survey.
So far, no URL parameters have been used, but now we are going to add one parameter to automatically populate one of the questions. Try the following:
https://survey123.arcgis.com/share/7fdcf75abfad4ae29f0156e161740d27?field:submitted_by=Fernando
You will notice that now the Submitted By question is automatically adding the name Fernando in the survey.
Immediately after the basic URL of the web form, I added a question mark (?). The question mark indicates that what follows are URL parameters. Next, I added the name of the parameter, which in this case is field:submittedBy and a value for that parameter: Fernando after the = sign.
You can add multiple parameters by simply separating them with an ampersand (&). For example:
Next, lets learn about the different URL parameters you can pass to Survey123 web forms.
Setting values on questions (field:fieldname)
In the previous section you saw how a URL parameter can set a value to a question in your form, but lets take a closer look at how it works. The syntax is simple:
...?field:common_name=Oak
The name of the parameter is made out of two distinct parts. First, you have the field: suffix and then you have the name of the question where you want to put a value. Figuring out the name of a question can be tricky. The question name should not be confused with the label of the question. The label is what users see in the form. The question name represents the column in your feature layer where the response will be stored.
If you author surveys in Survey123 Connect, I am sure you already know what I am talking about: The question name is represented by the name column in the survey worksheet of your XLSForm. If you design your forms in Survey123 web designer, then finding out the exact name of your questions deserves a more detailed explanation.
After adding a question into your survey in web designer, you need to set its label and other properties, but not the name. The name of your question is automatically assigned by Survey123 web designer. Assigning a valid question name needs to follow very strict rules (the name cannot start with a number, cannot have special characters, or spaces and must be unique within your entire form) and that is why we put that out of your way in designer. This simplifies authoring for beginners, although in cases like this it obscures what is really going on. In any event, you can look at the question names by using the 'Modify Schema' link during the publishing process.
The Modify Schema dialog will let you define the exact names of your questions only when you add your questions to the form for the first time. Once you publish your survey, questions that already exist in your survey will appear as read-only in the Modify Schema dialog. In my case, I really did not want to change anything, I simply wanted to get the names so I could use them with my URL parameters.
Question names are case sensitive. You must pass the exact name. For example, in the oak survey, field:commonName=Oak will work, but field:CommonName=Oak will not work.
...?field:common_name=Oak
Centering geopoint questions (center)
The center parameter lets you set the default location of the geopoint question in your survey. It looks like this:
This parameter accepts a latitude/longitude coordinate pair where the values are separated by a comma. Now. there are a couple of important things to remember when using this parameter:
- This URL parameter only takes effect if the geopoint question is flagged as required, AND
- If authoring from web designer, the option to 'Ask user's location when opening this question' must be disabled'.
If the geopoint question is not required or the user location is used, the values from this URL parameter will be overridden at runtime when the end-user opens the question.
Hiding questions and survey elements (hide)
The hide parameter is handy when you want to control visual aspects of your survey. You can load a survey and hide questions, the navigation bar and more. This parameter takes as an input more or more values, separated by a comma.
Parameter Value Description
| navbar | Hides the navigation bar. That is, the bar at the top of the survey that includes options to login/logout and to change the language. This is particularly useful when you embed your survey within a website. Example. |
| header | Hides the survey header. The header typically includes the title of the survey or alternatively a banner image. This is particularly useful when you embed your survey within a website. Example. |
| description | The description element is optionally included if you author your survey in web designer. |
| footer | Hides the footer element, which includes the Powered by Survey123 link, or an alternative link if you modified it. Also useful when embedding your survey within a website. Example. |
| theme | Use the theme value to disable any custom theme applied to your survey. Example. |
| field:fieldName | This value is used to hide specific questions within your survey. If you want to hide multiple questions, simply add their names separated by a comma. If you want to hide a question within a group, reference it by its full path: field:groupname/questionname. Example hiding the Submitted by and Survey Date questions. |
| leaveDialog | Use this value if you do not want the web browser to request user confirmation before leaving the web browser survey page. 
|
The hide parameter is very flexible, allowing you to hide multiple elements at once. That is, you can hide the navigation bar, the footer, description and as many questions in the survey as you like. To hide multiple elements, you simply need to keep adding comma separated values to hide the different components. For example:
Another interesting thing you can do is hide a question and at the same time set its default value through a URL parameter. For example, you can hide the Submitted by question in the Oak survey and also set a value for it through your URL parameter.
Adjusting the width of the survey in the screen (width)
The width parameter sets the width, in pixels, of the survey in the screen. For example:
Automatically reload the survey after a record is submitted (autoRefresh)
Using the autoRefresh parameter your survey will reload immediately after a survey is submitted. This is very useful when people are expected to repeatedly send data from a survey.
...?autoRefresh=true
Do not forget that the parameter is case sensitive. Works with version 3.10 and above.
Edit existing records and opening surveys in view-only mode (mode)
The mode parameter supports the values edit and view. Combined with the globalid parameter, you can easily open specific records in edit or view modes. For example, here is how you can update an existing record:
...?mode=edit&globalId=56cf0f7a-def7-4402-bd2c-536b717637bb
There is a lot you can do with this (mode=edit) alone. Go to https://community.esri.com/groups/survey123/blog/2019/05/24/survey123-tricks-of-the-trade-editing-re... for more details.
Similarly, you can also open a survey in view-only mode.
...?mode=view&globalId=56cf0f7a-def7-4402-bd2c-536b717637bb
If you get an error like shown below when opening a record in view mode, you will need to adjust the sharing.
When a survey is shared for viewing, the Survey123 web app uses a special feature layer view built so users cannot edit your data. This feature layer view is created only when you share your survey results for viewing. That is done through the Collaborate tab in the Survey123 website, by selecting the Viewer section and then sharing with the appropriate groups (and clicking save... ).
Recalculate values when in edit mode (recalculate)
Use the recalculate URL parameter to force certain fields to be recalculated, even if the record is opened in edit mode. This can be very handy, for example, if you want to record the name of the person editing the record, or to refresh the date when the record was last edited.
Copying (cloning) existing records
The mode parameter supports a third value: copy. It is used to load the smart form with information from an existing record and to create a new record when the user submits:
?mode=copy&globalId=56cf0f7a-def7-4402-bd2c-536b717637bb
Set the app that will open your survey (open)
You can use the open URL parameter to determine the app to use with survey. Valid values for this parameter include: web, native and menu.
...?open=menu
Parameter Value Description
| web | Opens your survey in the Survey123 web app, as a web form. This is the default. |
| native | Will open your survey in the Survey123 field app. This option will only work if the Survey123 field app is already installed in the device. |
| menu | Will open web page to let the end user decide if the survey should be open in the Survey123 field app or within a web browser. |
Set the language of your survey (locale)
You can use the locale parameter to define the language of your survey. For more details on mutiple-language surveys refer to https://community.esri.com/groups/survey123/blog/2019/01/23/introducing-multiple-language-surveys
The locale parameter accepts ISO language codes. For example: locale=zh-cn or locale=en.
Below is a clever example where this parameter is used to help end users switch the language of the survey right from within a note in the form. You can see the different links added. Each of these links uses the locale parameter to reload the form in a different language within the web browser.
Encrypt URL parameters
If you are concerned about having your URL parameters in clear text, you can encrypt them. To learn more check out Survey123 Tricks of the Trade: Encode URL parameters in the web app.