Back to Top

Launch the field app

In this topic

  1. Link from a web browser on Windows
  2. Link from another app on iOS or Android
  3. URL parameters for launching the field app

You can create app links to open the Survey123 field app from another app, a web map pop-up, or a hyperlink in an email or website. Use a custom URL scheme to launch the app from a web browser or use a Survey123 app link to launch it from an app on Android or iOS. Use URL parameters to customize how the field app opens, such as to load a specific survey, set coordinates for the default map location, and populate answers to questions with predetermined values or by passing data attributes from a web map pop-up.

Link from a web browser on Windows

You can create a link to open the field app that can be embedded in 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).

  2. Add a unique reference to a survey and add it to the URL:
    1. Identify the item ID of the survey you want to open.
      Note:

      This is the string of characters that ArcGIS Online uses to uniquely identify the survey and can be found in the URL of your form item in ArcGIS Online. For example, if the survey's URL is https://exampleurl.maps.arcgis.com/home/item.html?id=36ff9e8c13e042a58cfce4ad87f55d19, your form's item ID is 36ff9e8c13e042a58cfce4ad87f55d19.

    2. Include the survey in the URL by adding ?itemID= and your form's item ID to the end of the URL.
    The URL should look similar to the following:
    arcgis-survey123://?itemID=36ff9e8c13e042a58cfce4ad87f55d19

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

    Note:

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

  3. Include predetermined answers to questions by adding a reference in the URL to a field using the name assigned to it in XLSForm (not its label). 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.

    The 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 the 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.

  4. Define a location for a geopoint question in the survey by adding coordinates to the URL:
    • 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.

    The final 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 the chosen survey, populate a text question, and provide a new default location for the geopoint question.

    Field attributes can also be passed to Survey123 from a pop-up in an ArcGIS web map, allowing integration with other Esri apps that use pop-ups in a web map. This capability can be used to populate a field in Survey123 with the value of a feature attribute, rather than a set value, by providing the name of the attribute enclosed in curly brackets.

  5. Open the web map and select Pop-ups for one of the layers. Choose Add content and select Text. Provide the text to display for the link and click the Link button to enter the Link URL value.

    Set the link for the URL scheme in the pop-up.

    This URL populates 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 populates 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 from another app on iOS or Android

You can create a link for use in ArcGIS apps to open Survey123 and capture data in a survey. The steps below describe how to create a Survey123 app 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 preceding section) on an iOS or Android device.

  1. Open a web map that will be viewed on the device and select Pop-ups for one of the layers.
  2. Choose Add content and select Text.
  3. Type Launch Survey123, highlight this text, and click the Link button to enter the link URL. Type https://survey123.arcgis.app, and click OK.
    1. Open the 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 the survey in the URL, add ?itemID= and your form's item ID to the end of the URL.
    The URL should look similar to the following:
    https://survey123.arcgis.app?itemID=36ff9e8c13e042a58cfce4ad87f55d19

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

    Note:

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

  5. Include predetermined answers to questions by adding a reference in the URL to a field using the name assigned to it in XLSForm (not its label). 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.

    The 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 the survey, and you can 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. Define a location for a geopoint question in the survey by adding coordinates to the URL:
    • 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.

    The 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 the chosen survey, populates a text question, and provides a new default location for the geopoint question.

URL parameters for launching the field app

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

ParameterDescriptionType

center

Centers the map to known latitude, longitude, and optional altitude.

Example:

center=37.8199,-122.4783,20

String

field:fieldname

Populates survey questions with field values.

Example:

field:surname=Klauser

String

portalUrl

The URL to the portal where the survey item is hosted.

Example:

portalUrl=https://myorg.arcgis.com

String

itemID

The form to open.

Example:

itemID=36ff9e8c13e042a58cfce4ad87f55d19

UUID

download

Automatically downloads the survey when the device is online. The default is true.

Example:

download=false

Boolean

action

Specifies how the survey is opened. Supported values are collect (the default), edit, view, and copy.

Example:

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

Example:

folder=drafts

String

callback

The URL to return to when a form action (for example, submit, move to drafts, cancel, or exit) is completed.

Example:

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.

Example:

callback:draft=https://quickcapture.arcgis.app

String

filter

Searches existing surveys on the device for a specific string. When an instance name has been defined, provide a string that represents either the full instance name or a substring of the instance name. The following examples show how to filter for all records with the full instance name of Klauser or all records that contain the word lake within their instance name.

Examples:

filter=Klauser
filter=lake

When searching a field that is not a part of the instance name or no instance name is defined, include both the field name and the field value, in the form filter=field:fieldname:fieldvalue. Only whole field values can be filtered using the field. The following examples show how to filter for records whose water body type is River or whose station number is 5171.

Examples:

filter=field:waterbodytype:River
filter=field:ws_stationnumber:5171

String

update

Refreshes the Inbox contents and attempts to submit surveys to the Outbox option. If both update and filter are both included in a URL, the update will refresh the folder contents before the filter (which is performed on existing surveys on the device) is applied. The default is false.

Example:

update=false

Boolean

q:queryparameter

Queries the feature layer for an existing record. This is used to retrieve content that is not already on the device.

Examples:

q:where=ws_stationnumber=5171
q:where=waterbodytype='Lake'
q:globalId=1d392670-33e2-456d-8435-7fad3abd8bb9

String

Feedback on this topic?

In this topic
  1. Link from a web browser on Windows
  2. Link from another app on iOS or Android
  3. URL parameters for launching the field app