Integrate with other apps

ArcGIS Survey123 can be integrated with other apps using links to the Survey123 web app or field app. Links to the web app begin with https://survey123.arcgis.com/share. Links to the field app can be either a Survey123 link or a custom URL scheme link.

Survey123 links begin with https://survey123.arcgis.app and work on iOS and Android only. Survey123 links conform to requirements set by the App Store and Google Play, enable linking to more apps, and support shortened links that are easier to share.

Custom URL scheme links begin with arcgis-survey123:// and work on Windows, Android, and with a select group of apps on iOS. Custom URL scheme links cannot be shortened, and can be difficult to open on Android. Consider presenting custom URL scheme links in the form of hyperlinks, similar to the following:

<a href="arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19">Open survey</a>

Before using a link that contains parameters to launch a survey in the field app, it is recommended that the app already be installed on the device. For more information, see Install the Survey123 field app.

Parameters for a field app

The following parameters can be used to customize how a field app is opened:

Parameter	Description	Example	Type
center	Centers the map to known latitude, longitude, and optional altitude.	center=37.8199,-122.4783,20	String
field:fieldname	Populates survey questions with field values.	field:surname=Klauser	String
portalUrl	Specifies the URL to the portal where the survey item is hosted.	portalUrl=https://myorg.arcgis.com	String
itemID	Specifies the form to open.	itemID=36ff9e8c13e042a58cfce4ad87f55d19	UUID
download	Automatically downloads the survey when the device is online. The default is true.	download=false	Boolean
action	Specifies how the survey is opened. Supported values are collect (the default), edit, view, and copy.	action=edit	String
folder	Specifies the folder to be searched when the filter parameter is used. Supported values are inbox, drafts, outbox, sent, and * (all folders).	folder=drafts	String
callback	Specifies the URL to return to when a form action (for example, submit, move to drafts, cancel, or exit) is completed.	callback=https://quickcapture.arcgis.app	URL
callback:status	Specifies the status of the survey when callback is activated. Supported values for status are cancel, draft, submit, and close. The close status can only be used when action=view.	callback:draft=https://quickcapture.arcgis.app	String
filter	Searches existing surveys on the device for a specific string. Provide the name of a particular field to only search that field for the desired string.	filter=Klauser	String
update	Refreshes the Inbox and attempts to submit surveys to the Outbox. The default is false.	update=false	Boolean
q:queryparameter	Queries the feature layer for an existing record. It can be used to retrieve content that is not on the device.	q:where=ws_stationnumber=5171 q:where=waterbodytype='Lake' q:globalId=1d392670-33e2-456d-8435-7fad3abd8bb9	String

Parameters for a web app

The following parameters can be used to customize how a web app is opened:

Parameter	Description	Example	Type
center	Centers the map to known latitude, longitude, and optional altitude.	center=37.8199,-122.4783,20	String
field:fieldname	Populates survey questions with field values.	field:surname=Klauser	String
portalUrl	Specifies the URL to the portal where the survey item is hosted.	portalUrl=https://myorg.arcgis.com	String
open	Specifies the app used to open the survey. Valid values are web, which opens the survey in the web app (the default); native, which opens the survey in the field app if the field app is installed; and menu, which opens a web page to determine the app that will open the survey.	open=web	String
hide	Hides elements of the survey in the web app. The parameter can accept multiple values 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, submit, theme, and leaveDialog (the warning message displayed when navigating away from or closing the page). You can also use the field:fieldName parameter to hide a specific question, group, page, or repeat, by providing the name in place of fieldName. Note: Questions in repeats cannot be hidden individually.	hide=header,description,footer,theme	String
locale	Switches the language of the survey. It only works if the survey includes multiple languages.	locale=zh-cn	String
mode	Sets the mode of the web app. Valid values are edit, which sets the survey to edit an existing entry rather than create one; view, which opens an existing entry in read-only mode; and copy, which creates a survey that is populated with the contents of the specified entry. When using this parameter, the globalId parameter must also be provided.	mode=edit&globalId=42db492cb06111ea...	String
globalId	Specifies the survey record that's loaded into the form. Valid values are the global IDs for existing survey records. The name of this parameter is case sensitive.	globalId=42db492cb06111ea...	String
recalculate	Can only be used with mode=edit. Forces specified questions to be recalculated as the survey is loaded, without use of the Recalculate button.	recalculate=field:question1,field:question2	String
version	Sets the version of the web app that will be used. The only valid value is latest, which uses the latest version of the web app, even if the survey is version locked.	version=latest	String
token	Passes a valid token for a survey. It can be used to allow respondents to respond to a survey that requires an ArcGIS account to access it without signing in.	token= E60M4Gsc-h4Q8plqQ...	String
autoReload	Reloads the survey after submission. Specify the delay (in seconds) before the survey is reloaded. Previously called autoRefresh. The autoRefresh parameter is supported for backward compatibility.	autoReload=3	Integer
encodeUrlParams	Obscures URL parameters. The resulting URL will instead include a code parameter representing all encoded parameters; parameters included outside of this code parameter will be ignored.	encodeUrlParams=true	Boolean
width	Sets the width for the survey, in pixels. This also affects other controls within the survey, such as text boxes.	width=1000	Integer

Note:

The field:fieldname parameter supports geopoint, geotrace, and geoshape questions in the web app. For geopoint questions, specify latitude, longitude, and altitude (optional) separated by spaces. For geotrace and geoshape, for each vertex specify the latitude and longitude separated by a space, with each pair of coordinates separated by a semicolon. This example would work for a geoshape question:

field:geoshape=-37.842156723211474 144.95942945338243;-37.83554486071995 144.9726235713864;-37.85681405373047 144.98240735651922;-37.85954045531896 144.97715349053766

Link to Survey123 from a desktop web browser

You can create a link to open the field app that can be embedded into another app. The same link can also be entered into a web browser for testing.

Note:

Once you create the link, you can replace arcgis-survey123:// with https://survey123.arcgis.app as the Survey123 link for use on iOS or Android.

The following steps describe how to create a custom URL scheme and use it in a desktop web browser:

1. Type arcgis-survey123:// into your browser.
   The Survey123 field app opens (or you are prompted to open it).

   Note:

   To launch and download a survey from a specific portal, include the portal URL parameter, for example, arcgis-survey123://?portalUrl=host.domain.com/webadaptor (where host, domain, and webadaptor are replaced by your portal information).

You can also add a unique reference to a survey and add it to the URL. First, 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 survey's URL is https://exampleurl.maps.arcgis.com/home/item.html?id=36ff9e8c13e042a58cfce4ad87f55d19, your form's item ID is 36ff9e8c13e042a58cfce4ad87f55d19.

2. 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:

   arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19

   If you test your URL, it should now open the Survey123 field app and immediately open your survey.

   Note:

   If it's not already on your device, the survey is downloaded to it.

Optionally, include predetermined answers to questions.
3. Include a reference to the field using the name assigned to it in XLSForm (not its label) in your URL. For example, to populate the Surname field, type &field:Surname= and the value.

   The & acts as a parameter separator and field: refers to the question name to be populated.

   Your URL should look similar to the following:

   arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser

   You can now use the URL to open the Survey123 field app and your survey and fill in the given question with the answer you defined. You can populate multiple questions in the one survey URL. Field names are case sensitive.

Optionally, add coordinates to the URL, defining a location for a geopoint question in the survey.
4. Type &center=, and type the coordinates. Type the latitude and longitude coordinates in decimal degrees, separated by a single comma. Optionally, add altitude in decimal meters as a third value, also separated by a single comma.

   Your URL should look similar to the following:

   arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser&center=37.8199,-122.4783,20

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

Field contents can also be passed to Survey123 from a pop-up in an ArcGIS web map, allowing integration with any Esri apps that use 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.
5. Select Configure Pop-up for an existing layer in your web map. In the display drop-down menu, select A custom attribute display, click Configure, and insert the link to your survey.

   

   This URL would populate the surname field with the contents of the selected feature's name attribute rather than a set value:

   arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname={name}

   This URL would populate the hydrantGlobalID field with the global ID of the selected hydrant:

   arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:hydrantGlobalID={globalid}

Note:

By default, values can only be passed to select one or select multiple questions from a pop-up in a web map if the name and label of the corresponding choice are identical. If the names and labels in your choice list are different, you can use the DomainCode or UrlEncode functions in an ArcGIS Arcade expression in the pop-up to pass the desired value.

Questions in repeats cannot be populated.

Link to Survey123 from another app

You can create a link for use in ArcGIS apps to open Survey123 and capture a survey. The following steps describe how to create a Survey123 link and use it in a web map pop-up. This link is entered in the pop-up of a web map in your ArcGIS organization. You can test the link using a web browser (using similar steps as in the section above) on an iOS or Android device.

1. Select Configure Pop-up for an existing layer in a web map that will be viewed on the device.
2. In the display drop-down menu, select a custom attribute display, click Configure, and insert the link to your project.
3. For URL, type https://survey123.arcgis.app and for Link Text, type Launch Survey123. Click OK.
   1. Open your web map on a mobile device from either a browser or an ArcGIS app.
   2. Select a feature and click the Launch Survey123 link in the pop-up to open Survey123.
4. 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:

   https://survey123.arcgis.app?itemID=36ff9e8c13e042a58cfce4ad87f55d19

   If you test your URL, it should now open the Survey123 field app and immediately open your survey.

   Note:

   If it's not already on your device, the survey is downloaded to it.

Optionally, you can include predetermined answers to questions.
5. Include a reference to the field using the name assigned to it in XLSForm (not its label) in your URL. For example, to populate the Surname field, type &field:Surname= and the value.

   The & acts as a parameter separator and field: refers to the question name to be populated.

   Your URL should look similar to the following:

   https://survey123.arcgis.app?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser

   You can now use the URL to open the Survey123 field app and your survey, and fill in 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.
6. Type &center=, and type the coordinates. Type the latitude and longitude coordinates in decimal degrees, separated by a single comma. 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:

   https://survey123.arcgis.app?itemID=36ff9e8c13e042a58cfce4ad87f55d19&field:surname=Klauser&center=37.8199,-122.4783,20

   This complete URL now opens the Survey123 field app and your chosen survey, populates a text question, and provides a new default location for your geopoint question.

Pass parameters to the 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:

https://survey123.arcgis.com/share/36ff9e8c13e042a58cfce4ad87f55d19?field:surname=Klauser&center=37.8199,-122.4783

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 in a browser.

Note:

If a parameter value includes spaces, plus signs (+), or other special characters, these characters should be percent-encoded. For more information, see Encode URL parameters.

Pass parameters to Survey123 Connect

The URL scheme used by Survey123 Connect is arcgis-survey123connect://, which allows 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; it accepts the form's item ID and the URL for the portal in which the item is stored. The following example URL opens a specific survey in Survey123 Connect from the ArcGIS Enterprise portal provided, downloading it if it isn't already present:

arcgis-survey123connect://?portalUrl=https://exampleportal.esri.com/arcgis&itemID=36ff9e8c13e042a58cfce4ad87f55d19

If your survey is saved in ArcGIS Online, you still must provide the portal URL for ArcGIS Online, such as the following:

arcgis-survey123connect://?portalUrl=https://www.arcgis.com&itemID=36ff9e8c13e042a58cfce4ad87f55d19

Note:

These URL parameters can only be used to open forms that you own. They can't be used to open surveys to which you have access but did not create.

Link to other apps from Survey123

Many apps can be opened through links. 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 must add a note question to your survey with a label that contains the URL.

Note:

On iOS devices, URL schemes other than HTTP and HTTPS must be added to an approved list of schemes in the app. The following URL schemes are approved in Survey123:

• arcgis-appstudio-player
• arcgis-quickcapture
• arcgis-collector ArcGIS Collector on Windows only
• arcgis-trek2there
• arcgis-navigator
• arcgis-workforce Workforce for ArcGIS (Classic) only
• comgooglemaps
• foreflightmobile
• waze
• spike-partner

To link to Field Maps and the newest version of Workforce, you must use an app link that begins with HTTP or HTTPS.

See the following for information about some of the common Esri apps that can be opened through Survey123:

• ArcGIS QuickCapture
• ArcGIS Field Maps
• ArcGIS Navigator

Encode URL parameters

Although URL parameters that are not encoded work in some environments, it is recommended that you encode URL parameters. Encoding replaces invalid characters with the percent sign (%) followed by their hex equivalent.

For example, the following is a Survey123 link that uses a callback to return to a specific project in QuickCapture with parameters that are not encoded:

https://survey123.arcgis.app?itemID=36ff9e8c13e042a58cfce4ad87f55d19&callback=https://quickcapture.arcgis.app?itemID=867895a71a1840399476fc717e76bb43

The following is the same URL with encoded parameters:

https://survey123.arcgis.app?itemID=36ff9e8c13e042a58cfce4ad87f55d19&callback=https%3A%2F%2Fquickcapture.arcgis.app%3FitemID=867895a71a1840399476fc717e76bb43

An equal sign that specifies a break between a key and its value should not be encoded.

One way to create encoded parameters is to use ArcGIS Arcade. The UrlEncode function allows you to define a collection of key value pairs that represent each parameter and produce a URL with appropriate encoding.

A survey author may also want to obscure URL parameters so that sensitive data is not visible in the URL. In this case, when you create a URL to use in the web app, include encodeUrlParams=true. For more information, see Parameters for a web app.