Survey123 Tricks of the Trade: Web form URL parameters

02-06-2019 08:00 AM
Esri Frequent Contributor
16 61 36.5K

[Updated February 28, 2020]

[Updated April 2, 2020]

[Updated July 13, 2020. Added autoRefresh]

[Updated March1, 2021. Added mode copy]



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:


The first part of the URL refers to the Survey123 web app: 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 1cb28b212b5542acbbdbaa35feba0765, in this case it is an Oak Tree Health 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: Pared...


You will notice that now the Submitted By question is automatically adding the name Fernando Paredes in the survey.  Well, that was a URL parameter!  Note that 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 Paredes.


You can add multiple parameters by simply separating them with an ampersand (&). For example:


...?field:submittedBy=Fernando Paredes&field:commonName=Oak


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:




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. 


Modify Schema in Survey123 web designer


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.




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:


  1. This URL parameter only takes effect if the geopoint question is flagged as required, AND
  2. 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

navbarHides 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.
headerHides 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.
descriptionThe description element is optionally included if you author your survey in web designer.
footerHides 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.
themeUse the theme value to disable any custom theme applied to your survey.  Example.
field:fieldNameThis 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.


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.


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:


There is a lot you can do with this (mode=edit) alone. Go to for more details.


Similarly, you can also open a survey in view-only mode.



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... ).



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:



Redirect the Survey123 web app to your own ArcGIS Enterprise (portal)


While the Survey123 web app is hosted in ArcGIS Online, there is no reason why you can't load surveys from your own ArcGIS Enteprise instance.  You do this through the portal URL parameter, which takes as a value the URL of your own ArcGIS Enterprise  Web Adaptor. For example:




The above URL will load into your web browser the survey with identifier acb28b212b5542acbbdbaa35feba0765 as found in the ArcGIS Enterprise instance.


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.




Parameter Value  Description

webOpens your survey in the Survey123 web app, as a web form. This is the default. Example.
nativeWill open your survey in the Survey123 field app. This option will only work if the Survey123 field app is already installed in the device. Example.
menuWill 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. Example.


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 

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.



Occasional Contributor
New Contributor

Hi @IsmaelChivite, @JamesTedrick , @Ruth_JiatengXu ,

Is it possible to create an url with a centering geopoint, combined with an custom basemap? My url with custom basemap doesn't zoom in to the right coordinates but to the coordinates defined in survey123 connect.



New Contributor III

Is there a way to hide or collapse a group upon opening by using a URL parameter?

Occasional Contributor

Is there a limit to the number of fields values you can send from one survey to another through a single url or am not doing something correct with my url?  I have survey in which I want to send the values of up to 18 different fields over to a separate survey.  I have had success sending up to 4 field values over but not with the rest.


concat('<a href="arcgis-survey123://?itemID=MYSURVEYSUNIQUEID&field:Code1=100&field:Form_Type=Damage_Log','&field:Crew_Size=',${Crew_Size},'&field:Truck_Units=',${Truck_Units},'&field:Name_1=',${Name_1},'&field:Position_1=',${Position_1},'&field:Name_2=',${Name_2},'&field:Position_2=',${Position_2},'&field:Name_3=',${Name_3},'&field:Position_3=',${Position_3},'&field:Name_4=',${Name_4},'&field:Position_4=',${Position_4},'&field:Name_5=',${Name_5},'&field:Position_5=',${Position_5},'&field:Truck_1=',${Truck_1},'&field:Truck_2=',${Truck_2},'&field:Truck_3=',${Truck_3},'&field:Truck_4=',${Truck_4},'&field:Truck_5=',${Truck_5},'">Send To Survey 2 Form</a>')

New Contributor

Is there a way to populate an image field? I've got an image URL, and I'd like to add this as an image to the survey.

New Contributor III

I have a question about the auto-refresh parameter.

My situation is a little different as I'm using the Survey123 widget in Experience Builder, but when I submit a survey it does automatically refresh, however I don't want it to in this case. Any idea on why this would be or how to stop it?

Occasional Contributor

Can I use a URL to prepopulate and then make it read only for a web entry?

I am looking to use this from a map pop-up so the business name can be prepopulated.  I do not want the person filling out the survey to have the option to change the business name. 

I still want to display the business name in the survey but make it read only or a note.

New Contributor II
Try the reply from TimothyMichael with the Excel cheat sheet in this post:

I think you can use the item ID for the feature service that includes the business name and then build the parameters with your desired fields. And mark the field that includes the parameter as read-only in the Survey123 spreadsheet.

New Contributor II

Can you please give an example on how to pass field parameters for a survey on Enterprise? I am able to open my survey but unable to figure out how to pass parameters.

New Contributor III



Is the capability to edit an existing feature in the field application via URL supported yet? 

Since the inbox functionality does not support attachments we are at a stand still with our workflow. What are the available options to be able to allow users to edit existing features (and attachments)? We want to be able to email the users a link to the survey assigned to them and then it open up and let them populate the rest of the data in the feature service via the survey123 mobile app. Currently it appears like this is not possible. 




Esri Regular Contributor

Hi @RobertAnderson3 , 

The Survey widget in Experience Builder always adds a ?autoRefresh=3 URL parameter to the user specifies in it. In the future, it will be removed and expose as an option in the Survey123 web designer. You can track this by BUG-000134729.


For now, as a workaround, you can use the Embed widget in Experience Builder and specify the Survey123 web app URL to embed a survey.