Understanding Survey123's custom URL Scheme

07-29-2016 11:14 PM
Esri Frequent Contributor
52 318 94.3K

.Updated August 10, 2020 (Added reference to Arcade UrlEncode operation)

The purpose of a URL scheme is to provide a well-known protocol for apps to communicate with each other. Through a custom URL scheme you can remotely launch apps and invoke actions in them.  Specifically, the URL scheme in Survey123 allows you to:

  • Launch the Survey123 app
  • Open a survey
  • Prepopulate answers in the survey

A common practical scenario for using the Survey123 custom URL scheme is integrating Survey123 with other ArcGIS apps like Explorer, QuickCapture, Collector or even your own web mapping apps. Take for example a case where you want field users to use a map to identify a particular asset, and then use a smart form in Survey123 to capture information about that particular asset. Explorer, Collector or a plain Web Map can serve the first purpose.

In this post I will first describe the syntax of the Survey123 custom URL scheme, then how to execute a call with it and later how to integrate URL scheme calls into feature popups in ArcGIS Web Maps, so other ArcGIS Apps can leverage it.

About the Survey123 Custom URL Scheme syntax

A call to Survey123 through its URL Scheme looks something like this:


Let’s break it down:

The first bit is pretty obvious: arcgis-survey123:// invokes the Survey123 mobile app. For this to work, the Survey123 app must be installed in the device in which the call is being made.

Everything after arcgis-survey123:// are optional parameters that you can pass if you want the app to do additional things. The list of parameters starts with a question mark (?).

Parameters are separated from each other through ampersands (&). Each parameter is actually made of two parts: the parameter name and the parameter value, which are separated by the equal (=) sign.  The rules for how to properly pass parameters are common to how you build query strings for the web.

The itemID parameter (itemID=89bc8c7844e548e09baa3aad4695e78b) refers to the survey you want to open. If the survey is not already in the device, the app will attempt to download it automatically. 

To obtain the proper itemID for a survey follow these instructions:

1.    In a web browser, login into survey123.arcgis.com
2.    Click on the survey for which you want the itemID
3.    Now get the ID of your Form from the location bar of your browser.

For example, if the URL of your survey looks like this:


, the itemID will be: 3d02eec41a224902ab4c44e6d39319c8

The app will automatically attempt to download the survey as specified in the itemID parameter.  If the survey is shared publicly, it will open right away.  If the survey is private, it will be downloaded using the currently logged-in user. If no user is logged-in, a dialog will prompt the user for credentials.

In the example above we use the field:AssetID and field:Status parameters to prepopulate questions in the survey.  If you want a survey to open and have some or all questions already answered, you will add as many field parameters as needed. Field parameters always are prefixed with the word field:  After that, you enter the name of the actual question for which you want to set the answer, then you add an equal sign and the answer. For example:

  • field:AssetID=FF34001 will populate the AssetID question in your survey with the value FF34001.

Here are some tips when passing field  parameters:

  • The value to insert immediately after field: is the value of the corresponding NAME question in your XLSForm. Do  not pass the Label!
  • The value to insert after the equal (=) sign is the actual value that will be stored in the feature service. If you are working with select_one type of  questions this is very relevant, since the value you must pass is that of the XLSForm Name of the choice, rather than its Label.
  • Passing field parameters for questions within a repeat or attachments is not supported at the moment.
  • If you would like to prepopulate a question, but do not want to user to change its value, flag the question in the XLSForm as read-only.

The last parameter we pass in the example above is center=43.567,-117.380.  This will set the location of geopoint questions in your survey at the provided coordinate pair. You must pass a latitude-longitude pair in decimal degrees separated by a comma as no other coordinate systems or formats are supported.

Invoking a Custom URL Scheme call: The Basics

If you would like to give this a quick try, I recommend that you use a web browser to experiment. Start by downloading the Survey123 app into your desktop. You can download it for Windows or for your Mac. Once you have the app, manually launch it and login to download a couple of surveys. Then get the itemID of one of them to start and use it to adjust the itemID parameter:  arcgis-survey123://?itemID=insert your own Form item ID here Then paste it into your web browser to launch Survey123 and open one of the surveys you downloaded. Continue experimenting by pre-populating survey questions.

Once you feel comfortable with the syntax of your URL scheme links, try in your own device. Start by e-mailing the URL Scheme invocation to yourself, and using it from your device's web browser. You can also use Survey123 URL scheme strings to configure hyperlinks in an email, or include them as part of a web page.

Invoking a Custom URL Scheme call from a Web Map

Things get pretty interesting when Survey123 URL scheme links are used within an ArcGIS Web Map. This allows you to integrate Survey123 into other ArcGIS apps, by allowing users to launch Survey123 from the popup of a Web Map in Collector, Explorer or even a web application. This gets interesting for a couple of reasons:

  • First, you can use a map centric app to help the user find a particular asset or location, then easily launch Survey123 from that app to capture data using a smart form.
  • Second, you can use the existing attributes of a feature in the map and pass them into the form to prepopulate answers. This is extremely useful to ensure, for example, that the unique ID of an asset as identified in your map, is passed into Survey123.

To embed custom URL scheme calls within a Web Map, you will want to edit the popup of an existing layer. Choose the Configure Pop-up option in the layer’s menu.

Next, select the Custom Attribute display as shown in the next screenshot.

In a Custom Attribute display you can now embed your Custom URL scheme call as a hyperlink. You can ignore the warning indicating that the value is not valid.  If you prefer, you can also work directly using the source HTML view of the popup.

As shown below, you can reference attributes from the underlying feature in your Survey123 custom URL scheme by enclosing the name of the feature attribute within curly brackets.


With this technique, you will be populating the AssetID survey question with whatever value is present in the assetid attribute of the feature’s popup. This will ensure that captured data in Survey123 can always be associated back into the feature selected in the map.

A few quick tips when creating popups:

  • When passing text attributes with spaces, you will want to use the urlencode ArcGIS Arcade function. Otherwise, your links may get cut off at the first space encountered.
  • Field names are case sensitive in iOS. Ensure  you reference your feature service fields with the exact capitalization used in the feature service.
  • If you want to pass lat/lon values from attributes in your feature, be aware that the default formatting rules for the double data type cut-off decimal values to two. You will want to adjust the formatting rule to pass all decimal values to Survey123.

   1) Open the 'Configure pop-up dialog of your feature layer's and then select 'Configure Attributes' .
   2) Now select the attributes with your latitude and longitude values and pick the number of decimals you want to include in the Format drop-down option in the right side of the dialog.

  • If you want to pass lat/lon values from the geometry in a feature, you can add an Attribute Expression to your popup do dynamically get the lat/lon values from the geometry of your feature.

   1) Open the 'Configure pop-up dialog of your feature layer's and then select 'Configure Attributes'.
   2) Add a new Attribute Expression.
   3) Look for Geometry under the Globals tab and fetch Geometry($feature).x
   4) Use the Edit link at the top to give your expression a friendly name
   5) Repeat steps 2 through 4 to create a second expression for the y coordinate.

Once your Web Map is ready, you can next use it within multiple applications such as ArcGIS Explorer, Collector as well as your own web mapping apps.

Tip: Check Announcing a handy tool to generate Survey123 URLs if you would like to automate the generation of Survey123 Custom URLs for us in popups.

Invoking a Custom URL Scheme programmatically

In a web app or website, simply create an HTML link:

<a href='arcgis-survey123://?itemID=89bc8c7844e548e09baa3aad4695e78b'>Launch Survey123</a>

In QML AppStudio for ArcGIS:


In Java, using Android's Intent:

PackageManager manager = mContext.getPackageManager();

Intent i = manager.getLaunchIntentForPackage(

[This post was updated on October 30, 2018]

New Contributor II

Hi Ismael,

Thanks a bunch for this description! As you've asked I tried to configure the popup in my webmap as well. I do get a warning that it's an 'invalid url', or something, but it still allows it. Maybe you forgot to save the pop-up (button in the bottom left corner of the webmap) apart from just the webmap (top middle of the webmap)?

Anyways, so far I've tested a few of the ESRI sollotions to see if they work well with webmap pop-ups:

  • Collector: works great! Opens up Survey123 form and fills in parameters from the url
  • Webapp Builder: ditto.
  • Explorer: doesn't function as intended. Opens up browser instead, which is a dead end.

Thanks for your blog! It opens up a lot of opportunities for integrating Survey123 for us.

New Contributor II

I've done some more testing to see where the OpenURL link can be opened from. So far I've tested on an iPad Air 2 with iOS and a Samsung Galaxy S6 running Android.

Explorer for ArcGISfailfail
Collector for ArcGISfailsuccess
ArcGIS Webapp Buildersuccesssuccess
Occasional Contributor III

Thanks Ismael Chivite​ for the document above.

Here are my results:

Custom url works fine when in a feature table with instructions above on iPad.

Custom url does work with pop-up BUT with some good and some bad!  This is all Collector environment.

First the *BUG*, after you save the web map, the "arcgis-survey123://" is replaced with "#" in the config.  You must manually open up the config file and replace "#" with "arcgis-survey123://" AFTER you have saved the web map.  This will happen every time you save the web map and only when dealing with custom pop-ups.

The good thing about adding to the pop-up is you can specify which field to pull the data from.  For instance, after you add the field name in curly brackets {fieldname} to the URL, it will pull the data from that feature; field:AssetID=FF34001 would become field:AssetID={AssetID}. This seems to only work with pop-ups and not when you have the url in the feature table.

New Contributor III

Can you explain how to open and edit the config file? I am experiencing the same issue with the URL changing when I save the map but I am not sure to edit the config.

Thank you for any guidance you can provide!

Occasional Contributor

Love this...


We have successfully added a url-scheme link to the description field in Workforce. This provides a quick link (albiet potentially long and ugly string) which points to a specific Survey123 form. So now we can tailor a link from Workforce to Survey123, supporting each of our specific workforce assignment types. This will provide a solid alternative until Workforce can support this functionality through the action button.


Occasional Contributor III

It is the ItemIDs JSON in your arcgis portal contents folder.

New Contributor II

The good thing about adding to the pop-up is you can specify which field to pull the data from. For instance, after you add the field name in curly brackets {fieldname} to the URL, it will pull the data from that feature; field:AssetID=FF34001 would become field:AssetID={AssetID}. This seems to only work with pop-ups and not when you have the url in the feature table.

I'm not getting this method to work with ArcGIS Online. For instance if I configure the link like this in a custom pop-up:


it's not working.

if I add the full link in the feature table I can get it to work in WebApp Builder:


Somehow I'm not getting this method to work with Collector on Android either anymore.

Occasional Contributor III

After you add the link to the web map, save, go back to my contents, open the web map back up.  Check to see if arcgis-survey123:///?itemID=14b52d0cf8034975bc193751c67df72e&field:object_id={CODE} was replaced with #?itemID=14b52d0cf8034975bc193751c67df72e&field:object_id={CODE}. 

Saving blows up the link.

I am not sure how to fix this with ArcGIS Online but it can be done in portal.  I just tested again and it does work (after you crack open the JSON and fix the link.)

New Contributor II

Yup, you were right. It showed after re-opening the webmap. No idea how to work around this issue in AGOL either.

Esri Frequent Contributor

Quick note: Currently, ArcGIS Online and Portal for ArcGIS will 'sanitize' urls added into popups that do not use the http or https protocol. In our case at hand here, arcgis-survey123:// is not using http/s, so it will get removed as all of us found out already.  The sanity pass happens at the REST API level.   There are good reasons for this clean-up to happen.

We are currently in discussions to see how we can best handle this situation. Our goal is to allow you to use arcgis-survey123:// invocations within a popup and of course support field-value variables {myField} as you have already pursued.  Our plan is to have all of  this addressed in our next update to ArcGIS Online (September) and in Portal for ArcGIS 10.5.   In the meantime, there is really no way to make your Web Maps hold survey123 calls, except if you are lucky enough like Guido van der Kolk and can literally edit the JSON definition of the Web Map accessing the item OS directory in the machine where Portal for ArcGIS is installed.  We need to get creative here for a little while.

Occasional Contributor

We found a small hiccup in the use of url-scheme to open up Survey123 forms. When a form is opened using this method, it will always go to the outbox. Our expectation when the device is connected, and the user selects send now, the survey should be processed immediately into the AGO storage. 

Anyone else seeing this?

(Copied this to GitHub as issue)

Esri Frequent Contributor

I just updated the content of this post to adjust it to the status of things after the ArcGIS Online 4.3 release.

Important updates:

  • As of ArcGIS Online 4.3, you can now save a popup with a Survey123 custom url scheme link within a Web. Note that this still not possible in Portal for ArcGIS 10.4.1, but will be possible in version 10.5 (scheduled to be available around the end of 2016)
  • Explorer for ArcGIS does not support Survey123 custom url links in its current 10.2.10 version but a fix is coming in its next update (date to be determined).
New Contributor III

Is there a way to access the geometry (specifically, the coordinates) of an object to pass to the Survey123 custom URL scheme? I know it is possible to add fields for the X and Y coordinates, but these require maintenance since we update the locations of our features during field inspections. Thanks very much, these new features have been super helpful and exciting to implement.

Esri Frequent Contributor

Hi. Unfortunately not out of the box. You cannot dynamically get the X,Y coordinates of a point feature from your popup. However, you could get the X,Y coordinates from a feature using the ArcGIS API for Javascript, Python or something similar.  If you  provide some more details on the particulars of your workflow, we may come up with a workable solution.

New Contributor III

Hi Ismael,

We are using ArcGIS Online to map our storm and sewer networks. Field verification and initial mapping are completed using Collector. We also perform regular inspections on some features (such as manhole inspections) and use Survey123 to perform these repeated inspections. I used a custom attribute display in ArcGIS online to create the hyperlinks to launch Survey123 and set it to prepopulate some fields from the existing data (material, diameter, etc...). I would like to automatically set the location of the geopoint collected in Survey123 to match the coordinates of our existing point features or the coordinates of the centroids for existing line features but we periodically update these locations or add new features as we complete our field inspections. If there is a way to accomplish this, that would be great.

Thanks so much.

New Contributor

Hi Ismael,

I'm having a similar problem getting the form to launch. Collector launches Survey123 but not my form. Here is my URL:


and here is a screen cap of my form details:

I haven't upgraded to iOS 10 yet but still can't figure out why this isn't working for me.  Any help would be appreciated.



Esri Frequent Contributor

Hi. I hate it when computers take things so literally. Change the the parameter name to itemID and you will have a better chance. The parameter is called itemID, not ID. This link should work for you: arcgis-survey123://?itemID=44fd0897c4f741f3adc8ad6e824d0fbf

In my case, the link does not work (see screenshot below) because my user does not  have access to your form, but for you it should work.

New Contributor

Hello Ismael,

It’s amazing how well things work when you type the right things. That was easy. I think I need more sleep, can’t believe I didn’t catch that.

Problem solved, it works great. Thanks so much for your help.


Occasional Contributor III

Is there a time frame when the Custom URL will be working again, to launch Survey123 from Collector?

Occasional Contributor II

It works for me - I am able to launch a Survey from Collector. 

Occasional Contributor III

iOS or Android?

Occasional Contributor II

iOS - but I tried several times before I was succesful and I don´t know why it didn´t work immediately. I will post an answer when I figure it out.

Occasional Contributor III

I was able to get it to work. The issue with Collector crashing appears to only happen when the feature layer, from the same form that I am the custom URL is linked to, is on the web map.

Esri Frequent Contributor

Johan EkenstedtCarl HoltOscar Sepulveda III‌ 

We figured out why Collector crashes when loading feature layers made with Survey123 Connect.  We will fix this in our 1.10 release (tentatively scheduled mid-December 2016). In the meantime, here is a workaround:

-Login to ArcGIS.com or  your Portal for ArcGIS

-Go to My Contents and look for the feature layer associated with your Form (typically within a folder created by survey123)

-Open the details page of your feature layer

-In the Layers section, look for the Time Settings option and click on it (see screenshot below)

-Once the Time Settings dialog is open, disable time and save.

-If you need time enabled, go back to the Time Settings dialog, enable time and save.

Occasional Contributor III

I do not follow or see what you are saying on ArcGIS Online Portal?

Esri Frequent Contributor

Hi Carl. Sorry, I should have provided more context. I edited my original reply above and included step by step instructions as well as a screenshot.

Occasional Contributor III

I'm adding this for a colleague, Kim Sundeen (MP), having browser issues.


I’ve followed the instructions for taking my published survey123 form id and added it to the URL of arcgis-survey123://?itemID=9fcec8debb13408092605ac9687477e4. When opening this link from my phone, the link opens up Survey123 for ArcGIS and downloads the survey, but then won’t recognize that the survey has successfully downloaded. As the picture shows, I continue to receive the message stating “The Survey [my survey name] has not been downloaded.” Even when I can plainly see the survey is downloaded, the message remains at the bottom of the screen unless I close completely out of Survey123 and reopen it. The URL scheme process also will not pre-populate any fields I tried. Has anyone else experienced this issue? What is the solution or work-around?


Esri Frequent Contributor

Hi lookout123‌  When I try to download your survey, Survey123 tells me that my user has no permissions. Please do the following:

0- In your device, delete any instances of your Solar Preliminary Check List survey

1- Log into  http://survey123.arcgis.com with the credentials of the user that  published your survey

2- Select your survey and go into the Collaborate tab. Share your Survey publicly

3- Go back to your device and access the link to trigger the survey download

Occasional Contributor III

Hi Ismael,

Have you seen this behavior before?  We can share the survey publicly for testing, but I've made other surveys that don't require it to be public in order to use the url scheme.  I'll have Kim share the survey publicly and message back when it is ready for testing.



Occasional Contributor III

HI Ismael,

The survey is share publicly now if you had some time to try it.  Thanks again for your help!


Esri Frequent Contributor

Hi Brandon. I think you got the ID of the Survey wrong, because the app cannot find the item.

Have a look at https://community.esri.com/groups/survey123/blog/2016/11/10/getting-started-with-public-surveys and pay particular  attention to the Collaborate tab in survey123.arcgis.com   The Collaborate tab includes the exact url scheme call you need  to invoke  to launch  your public  survey.

Occasional Contributor III

Hi Ismael,

Sorry about that.  We had to change owners of the survey to allow it to be shared publicly which may have changed the itemID.  Try this arcgis-survey123://?itemID=21e1d9c90c974df7a0db0c7814c52af8 .  I copied it from the collaborate tab.



Esri Frequent Contributor

Thanks bkeinath‌. I can take it from here. I was able to repro.

New Contributor III

Hi! Ismael Chivite


I followed the steps you have shared about integrating survey123 with Workforce, for example, and you have not allowed me to perform the fields that I want to update. Below I leave a picture about the problem I have.

I have Android and the survey123 version is 1.9.24. I have administrator privileges and I have reviewed the fields that I want to integrate but still nothing. I hope you can help me, thanks in advance for any help you can offer me.

Thank you!!

New Contributor III

I think the problem is Workforce for android. It's a beta and I have version 0.2.1.

New Contributor III

Hi ichivite-esristaff,

I'm using custom URL's to populate fields with known values. However field values with special characters like '=' or ',' result in '%3D' or '%2C'. I've read that this has something to do with URL encoding but how can I fix this in an arcgis online webmap so the correct hyperlink is given without URL encoding?

For example: 'arcgis-survey123://?itemID=AAA&center=52.3780716382816,4.90005350773038' is converted into:  'arcgis-survey123://?itemID=AAA&center%3D52.3780716382816%2C4.90005350773038'

Thanks, Niels

Occasional Contributor

Any plans to add the URL parameters to the web version of Survey123?  Something like this:


Or is it possible already and I am just doing something incorrectly?

Esri Regular Contributor

Hi Scott Moore‌,

Thanks a lot for your feedback.

Would you mind sharing some user scenarios of these parameters from your perspective? It can help us to improve the design when we implement that.

Actually, we have the plan to add URL parameters to the Survey123 web app, please stay tuned with the Survey123 blog.

In the meantime,

* Set a default value for a question

* Set "Cache answer to this question" to true of a question

may help you somehow before we deliver the URL parameters feature.

New Contributor II


I am collecting plots for farmers using Collector  and fill related information using Survey123. I am expecting to have a table (scv) from Survey123 and polygon shapefile (containing area) from collector. Is there any way of automatically creating a unique ID (like the objectID, or globalID) which I can later use to link data from Survey 123 and data from collector ?  



Occasional Contributor


In order to pass existing attributes from a web map (via Collector) to a Survey123 form, is it necessary for the same feature service to be used? I've created a survey123 form using the advanced template and have managed to invoke this survey from a web map through Collector but have not had any success passing the attributes from the web map into Survey123.  When I create a new Survey123 form using the existing web map feature service and refer to this in the Collector popup, the attributes come across and my survey is prepopulated.  However, it's my understanding that you can't edit existing features using Survey123.  I don't want to create additional points with Survey123 within this same feature service.  Am I missing something basic here? Thanks.

Occasional Contributor

I appear to have solved my problem, i.e., I was able to configure a web map and use this within Collector to call Survey123 and prepopulate a new feature service (created by 123) with the data coming from the web map feature service.  My sources of error were varied and included: (1) spaces in the URL. Because I had many fields to pre-populate, I was typing the URL in Notepad with word wrap, then copying this into the URL link properties.  Doing so, however, introduced spaces into the string that caused issues with fields prepopulating. (2) Setting the readonly property to yes for text fields to prepopulate in 123 seemed to be an issue.  As a result, I removed the yes, i.e., did not make them readonly. (3) I also failed to download 123 surveys after making changes to them.  As a result, I was trying to prepopulate an old survey which didn't work. Hopefully this experience helps others.

New Contributor II

Referring to part 2 of Tony's post. Does anyone have a work around for this?

I would like to pre-populate a field (via URL link) that is set to readonly.  Currently, when setting the field to readonly, it prohibits the pre-population of the field.

Note: this only affects 'text' fields, 'decimal' and 'dateTime' fields are unaffected.


Esri Esteemed Contributor

I've been able to workaround this by creating a note question that has a calculate statement; the calculate statement is overridden by the incoming values.  

Occasional Contributor

Hello...any solution to this URL encoding issue raised by Niels? I'm also encountering this problem when pre-populating a survey with information separated by commas. So what should be AS,RP,TA,BS,TL,BF,BA,JP,EC,WB,WS becomes AS%2CRP%2CTA%2CBS%2CTL%2CBF%2CBA%2CJP%2CEC%2CWB%2CWS



Image of URL encoding issue when pre-populating survey with text separated by commas.

New Contributor II

So, did you find out what was happening? We are experiencing the same thing with some of our Surveys, but cannot seem to find the reason or pattern...

Occasional Contributor II

Does this custom URL work with Survey123 Edit?  Can I pull up an "edit" form base on my formID & my accountID field?  Thanks.

Esri Esteemed Contributor

Hi Helen,

We currently do not have a URL parameter to indicate that Survey123 should edit a feature rather than create a new entry.  We've added it as an enhancement to be addressed in a future release.

New Contributor III

Hi there! So thankful for all the information shared here. Our staff need to collect point, line and polygon geometries in Collector along with a lot of survey information that is much easier to manage in Survey123, so finding a way to combine the two is so helpful. Using the info here, I was able to successfully configure a web map, use it within Collector to call the correct Survey123 form and prepopulate a field with the Objectid of the desired feature from Collector. I think we found a problem today though. Many times, our staff may be going into areas without service, so the plan was to use offline maps in Collector. If more than one person is working offline though, each of them could be adding features that would have Objectids of e.g. 1, 2. 3 etc. and then when the data get sync'd up later, those Objectids may change. It doesn't look like that change gets replicated to Survey123 though. We tested that today and confirmed the problem.  Is there any way around this, aside from having different maps and different surveys for each user? Thanks!

Occasional Contributor II

I would use a feature service with GlobalID - and use that instead of Objectid.

I think GlobalID is added to a feature service in AGOL when you enable offline capabilities.

Occasional Contributor III

Hi Tara,  I would address this through creation of a Global ID in the feature class used in Collector and autopopulate that into your survey to create the relationship between the spatial feature and the survey result.  You may also want to pull in the name of the feature layer that you are going to join the survey123 data into. Typically it is not a good idea to use the Object Id to relate features.