Integrate with other apps

ArcGIS Survey123 can be integrated with other apps using either a Survey123 link or a custom URL scheme. Both methods support the same parameters, but there are platform-dependent differences between the methods.

Survey123 links begin with https://survey123.arcgis.app and can be opened from or can open other ArcGIS apps that support app linking and are available on iOS and Android only. ArcGIS apps that can be opened with a Survey123 link include ArcGIS QuickCapture, ArcGIS Collector, ArcGIS Navigator, and Explorer for ArcGIS.

Custom URL scheme links begin with arcgis-survey123:// and can be opened from or can open other ArcGIS apps on Android and Windows. To use a custom URL scheme link on iOS, the other app must also have Survey123 approved within it to allow linking. ArcGIS apps that can be opened with a URL scheme from Survey123 include ArcGIS QuickCapture and Collector for ArcGIS (Classic).

When you use a custom URL scheme on Windows, you can create and test your link and its parameters before deploying it to your mobile workers as either a custom URL scheme or a Survey123 link.

Survey123 links are the preferred method of linking.

Parameters for field app

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

ParameterDescriptionExampleType

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, * (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 are cancel, draft, and submit.

callback:status=draft

String

filter

Searches existing surveys on the device.

filter=surname: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:objectIds=12

String

Parameters for web app

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

ParameterDescriptionExampleType

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. It 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, and theme. 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

lang

Switches the language of the survey. It only works if the survey includes multiple languages.

lang=zh_cn

String

mode

Sets the mode of the web form. Valid values are edit, which sets the survey to edit an existing entry rather than create one, and view, which opens an existing entry in read-only mode. 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

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 without signing in.

token= E60M4Gsc-h4Q8plqQ...

String

encodeUrlParams

Obscures URL parameters.

encodeUrlParams=true

Boolean

Link to Survey123 from a desktop web browser

You can create a link to open the Survey123 field app that can be embedded into another app. The same link can also be entered into a web browser for testing. The following steps describe how to create a custom URL scheme and use it in a desktop web browser:

Note:

Once you create the link, you can replace arcgis-survey123:// with https://survey123.arcgis.app as the Survey123 link.

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

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

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

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

    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.

  6. Optionally, you can add coordinates to the URL, defining a location for a geopoint question in the survey.
  7. Type &center=, and type the coordinates. Type the latitude and 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 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.

  8. 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.
  9. 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.

    Set the link for the URL scheme in the custom attribute.

    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}

  10. Note:

    Due to a limitation with Esri apps that use pop-ups in a web map, 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.

    Questions in repeats cannot be populated.

Link to Survey123 from another app

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

  1. Select Configure Pop-up for an existing layer in a web map that will be viewed in Explorer.
  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 in Explorer on a mobile device.
    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.

  5. Optionally, you can include predetermined answers to questions.
  6. 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.

  7. Optionally, you can add coordinates to the URL, defining a location for a geopoint question in the survey.
  8. Type &center=, and type the coordinates. Type the latitude and 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:

    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, populate a text question, and provide 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 the plus sign (+), you must instead use %2B to represent the +. To learn more, see Encode URL parameters below.

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 need to 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 need to add a note question to your survey with a label that contains the URL.

Note:

In iOS 9 and later, 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-collector
  • arcgis-trek2there
  • arcgis-explorer
  • arcgis-navigator
  • arcgis-workforce
  • comgooglemaps
  • foreflightmobile
  • waze
  • spike-partner

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

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 web map in Explorer with parameters that are not encoded:

https://survey123.arcgis.app/?itemID=36ff9e8c13e042a58cfce4ad87f55d19?callback=https://explorer.arcgis.app?itemId=867895a71a1840399476fc717e76bb43

The following is the same URL with encoded parameters:

https://survey123.arcgis.app/?itemID%3D36ff9e8c13e042a58cfce4ad87f55d19%3Fcallback%3Dhttps%3A%2F%2Fexplorer.arcgis.app%3FitemId%3D867895a71a1840399476fc717e76bb43

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.

Caution:

Rather than encoding URL parameters for cross-platform compatibility, a survey author may want to obscure the contents of a URL so survey users cannot read sensitive data. In this circumstance, when you create a URL to use in the web app, include encodeUrlParams=true. When this parameter is included, all parameters are obscured from view.