Integrate with other apps

Survey123 for ArcGIS integrates with other apps. A URL scheme can be used in a web browser to open Survey123 on your desktop or device or from another app. Survey123 can also open other ArcGIS apps, including 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.

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.

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

  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:

    The survey must be downloaded to your device before it can be opened.

  3. Optionally, you can include some predetermined answers to questions. To do this, the URL must 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:

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

    You can now use the URL to 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.

  4. Optionally, you can add coordinates to the URL, defining a location for a geopoint question in the survey. To do this, 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:

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

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.

Caution:

While Survey123 does support locales with decimal commas, the center parameter does not support decimal commas. Coordinates containing decimal commas will not be passed to the survey.

Contents of fields 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. 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 click Configure and insert a link to your survey.

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

This example 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}

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 within repeats cannot be populated.

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.

ParameterDescription

hide

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, and theme. You can also use field:fieldName to hide a specific question, group, page, or repeat, by providing their name in place of fieldName.

Note:

Questions within repeats cannot be hidden individually.

open

Determines the app used to open the survey. Valid values are web (opens the survey in the web app), which is the default, native (opens the survey in the field app, if the field app is installed), and menu (opens a web page to allow the user to decide which app the survey will be opened in). If this parameter is not provided, the URL will open the web app.

lang

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.

mode

Sets the mode of the web form. Valid values are edit, which sets your 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.

objectId

Deprecated.

globalId

Determines the survey record loaded into the form. Valid values are the global IDs for existing survey records. The name of this parameter is case sensitive.

version

Sets the version of the web app that will be used. Currently, the only valid value is latest, which sets the web app to use the latest version of the web app, even if the survey is version locked.

token

Passes a valid token for a survey. This can be used to allow respondents to respond to a survey that requires an ArcGIS account to access, without going through sign-in.

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:

Currently, 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 a whitelist, or list of approved schemes, in the app. The URL schemes that are whitelisted in Survey123 are as follows:

  • 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: