Survey123 for ArcGIS is capable of integrating with other apps using a custom URL scheme. A URL scheme can be used in a web browser to open apps on your desktop or device, or from within another app. ArcGIS apps that can be opened with a URL scheme include Survey123, Collector for ArcGIS, and Navigator for ArcGIS.
To help you understand the structure of the URL, the following sections describe how to construct a URL that opens Survey123 from a web browser and how to open Navigator from within Survey123.
Link to Survey123 from other apps
You can create a URL to open the Survey123 field or web app that can be embedded into your own native or web app. The same URL can also be entered into a web browser for testing.
- Type arcgis-survey123:// into your browser. This automatically opens the Survey123 field app (or prompts you to do so).
You can also add a unique reference to a survey and add it to the URL. First you must identify the item ID of the survey you want to open. This is the string of characters that ArcGIS Online uses to uniquely identify your survey and can be found in the URL of your form item in ArcGIS Online. For example, if your form's URL is https://exampleurl.maps.arcgis.com/home/item.html?id=36ff9e8c13e042a58cfce4ad87f55d19, your form's item ID is 36ff9e8c13e042a58cfce4ad87f55d19.
- To include your survey in the URL you're constructing, add ?itemID= and your form's item ID to the URL. Your URL should look similar to the following:
If you test your URL, it should now open the Survey123 field app and immediately open your survey.
The survey needs to be downloaded to your device before it can be opened.
- Optionally, you can include some predetermined answers to questions. To do this, the URL needs to include a reference to the field using the name assigned to it in the XLSForm (not its label). For example, to populate a field called Surname, type &field:Surname=and the value you want to enter; the & acts as a parameter separator, while field: refers to the question name to be populated.Your URL should look similar to the following:
The URL will now open the Survey123 field app and your survey, and fill the given question with the answer you defined. You can populate multiple questions in the one survey URL. Field names are case sensitive.
- Optionally, you can add coordinates to the URL, defining a location for a geopoint question in the survey. To do this, type ¢er=, and then type the coordinates. Type the latitude and then longitude coordinates in decimal degrees, separated by a single comma. You can optionally add altitude in decimal meters as a third value, also separated by a single comma.
Your final URL should look similar to the following:
This complete URL will now open the Survey123 field app and your chosen survey, populate a text question, and provide a new default location for your geopoint question.
Contents of fields can also be passed to Survey123 from a pop-up in an ArcGIS web map, allowing for integration with any Esri apps that make use of pop-ups in a web map. This capability can be used to populate a field in Survey123 with the contents of a feature attribute, rather than a set value, by providing the name of the attribute enclosed in curly brackets. To do this, select Configure Pop-up for an existing layer in your web map. In the display drop-down menu, select a custom attribute display, and then click Configure and insert a link to your survey.
This example URL would populate the Surname field with the contents of the selected feature's name attribute rather than a set value.
There is currently a bug with the Survey123 URL scheme where values can only be passed to select one or select multiple questions if the name and label of the choice in a choice list are identical.
Pass parameters to Survey123 web app
The Survey123 web app can accept parameters in the same format as the field app. The only difference is that you must use a question mark to separate the item ID of the survey from the first parameter, rather than an ampersand (ampersands are still used to separate parameters). The following example URL passes the surname and coordinate parameters to a survey in the Survey123 web app.
The Survey123 web app also supports a number of parameters that the Survey123 field app does not. These parameters relate to the presentation of the survey within a browser.
Hides elements of the survey in the web app. This parameter can accept multiple parameters, separated by a comma. Valid values are navbar (the bar at the top of the survey including options to log in, log out, and change language), header, description, footer, theme, and field:fieldName (a specific question in your survey, with the question's name in place of fieldName).
Determines the app used to open the survey. Valid values are web (opens the survey in the web app), native (opens the survey in the field app, if the field app is installed), and menu (opens a web page to let the user decide what app the survey will be opened in). If this parameter is not provided, the URL will open the web app.
Switches the language of your survey. This parameter only works if your survey has multiple languages included. It accepts locale codes, for example, zh-cn.
Sets the mode of the web form. Currently, the only valid value is edit, which will set your survey to edit an existing entry rather than creating one. Be aware that to edit a survey, the objectId parameter also needs to be provided.
Determines the exact survey record loaded into the form for editing. Valid values are the object IDs available for the survey. Be aware that the name of this parameter is case sensitive.
Sets the version of web app that will be used. Currently, the only valid value is latest, which will set the web app to use the latest version of the web app, even if the survey is version locked.
Pass parameters to Survey123 Connect
The URL scheme used by Survey123 Connect is arcgis-survey123connect://, which will allow the user to automatically download and open a survey, ready for editing.
This URL scheme accepts different parameters than the field app or web app, however, instead accepting the form's item ID and the URL for the portal that the item is stored on. This example URL opens a specific survey in Survey123 Connect from the ArcGIS Enterprise portal provided, downloading it if it isn't already present.
If your survey is saved in ArcGIS Online, you still need to provide the portal URL for ArcGIS Online.
Currently, these URL parameters can only be used to open forms that you are the owner of. It can't be used to open surveys that you have access to, but did not create.
Link to other apps from Survey123
You can create a URL that opens another app and insert it into your survey. These apps can also accept custom parameters in their URLs in the same way as Survey123.
To start, you need to add a note question to your survey with a label that contains the URL.
In iOS 9 and later, URL schemes need to be added to a whitelist, or list of approved schemes, within the app. The URL schemes that are whitelisted in Survey123 are as follows:
Navigator URL scheme
- To open Navigator from a survey, enter the following text as the label of a note question:
<a href="arcgis-navigator://">Launch Navigator</a>
- Navigator can accept stops as custom parameters to allow you to send a specific destination to the app. To open Navigator with a stop designated by the given coordinates, see the following example:
<a href="arcgis-navigator://?stop=34.057419, -117.182646">Launch Navigator</a>
- Optionally, you can add a parameter to return to the Survey123 field app once navigation is complete. This parameter is referred to as a callback. The following example includes a callback to the Survey123 field app:
<a href="arcgis-navigator://?stop=34.057419, -117.182646&callbackprompt=Survey123&callback=arcgis-survey123://">Launch Navigator</a>
For more information, see Navigator custom URL scheme.
Collector URL scheme
- To open Collector from a survey to a specific map, provide the item ID in the link, as in this example:
<a href="arcgis-collector://?itemID=35b1ccecf226485ea7d593f100996b49">Launch Collector</a>
- Collector can accept center as a custom parameter to provide latitude and longitude coordinates for a location to center the map on. To open Collector with a specific center location, see the following example:
<a href="arcgis-collector://?itemID=35b1ccecf226485ea7d593f100996b49¢er=34.0547155,-117.1961714">Launch Collector</a>
For more information, see Collector custom URL scheme.
Explorer URL scheme
- To open Explorer from a survey to a specific map, provide the item ID in the link, as in this example:
<a href="arcgis-explorer://?itemID=35b1ccecf226485ea7d593f100996b49">Launch Explorer</a>
- Explorer can accept center as a custom parameter to provide latitude and longitude coordinates for a location to center the map on. To open Explorer with a specific center location, see the following example:
<a href="arcgis-explorer://?itemID=35b1ccecf226485ea7d593f100996b49¢er=34.0547155,-117.1961714">Launch Explorer</a>
For more information, see Explorer custom URL scheme.
Currently, the Explorer URL scheme is only capable of accepting one custom parameter at a time.