| name | survey123-js-api |
| description | Embed ArcGIS Survey123 forms into web applications using the Survey123 Web Form JavaScript API. Use when users need to (1) embed Survey123 surveys in webpages, (2) interact with survey forms programmatically, (3) handle survey submissions and events, (4) set question values dynamically, (5) implement authentication for private/org-shared surveys, (6) customize survey appearance, (7) analyze or modify survey definitions (form.json), or (8) handle complex question types and validation. |
Survey123 JS API
Embed and interact with ArcGIS Survey123 forms in web applications using the Survey123 Web Form JavaScript API.
Overview
The Survey123 JS API allows you to embed Survey123 surveys into webpages using only the ArcGIS Online form item ID. The API provides methods to control form behavior, handle events, and manage authentication.
Quick Start
Basic Embedding
<!DOCTYPE html>
<html>
<head>
<title>Survey123 Embed</title>
<script src="https://survey123.arcgis.com/api/jsapi"></script>
</head>
<body>
<div id="surveyDiv"></div>
<script>
const webform = new Survey123WebForm({
container: "surveyDiv",
itemId: "YOUR_SURVEY_ITEM_ID",
});
</script>
</body>
</html>
Key Constructor Options
container: DOM element ID or element referenceitemId: ArcGIS Online survey form item IDtoken: (Optional) Access token for authenticated surveysportalUrl: (Optional) Custom portal URL (defaults to ArcGIS Online)clientId: (Optional) OAuth client ID for authentication
Authentication
Built-in Authentication
The Survey123 JS API's embedded iframe automatically detects if a survey requires authentication. If the user is unauthenticated, it will display a Sign In button directly within the iframe. Clicking this button initiates the ArcGIS OAuth2 flow. This is the simplest way to handle authentication.
Manual Authentication
If you need to handle authentication manually (e.g., to manage tokens yourself or for a custom UX), follow the OAuth 2.0 flow:
- Redirect to ArcGIS OAuth authorize page
- Receive authorization code/token
- Pass token to Survey123 API
See references/authentication.md for a detailed guide on both automatic and manual authentication methods.
Setting Credentials
webform.setCredential({
token: "YOUR_ACCESS_TOKEN",
server: "https://www.arcgis.com/sharing/rest",
});
Core Methods
Form Lifecycle
on('formLoaded', callback) - Triggered when form loadson('formSubmit', callback) - Before form submissionon('formSubmitted', callback) - After successful submissionon('formFailed', callback) - On form load/submit failure
Question Interaction
setQuestionValue(value) - Set question values dynamicallygetQuestionValue() - Get current question valuesgetQuestions() - Get all questions in JSON formatscrollTo(questionName) - Scroll to specific question
Event Handling
webform.on("formSubmit", (data) => {
console.log("Form submitted:", data);
});
webform.off("formSubmit", callback);
Repeat Questions
addRepeat(options) - Add repeat recordsdeleteRepeat(options) - Delete repeat recordsgetRepeatCount(questionName) - Get repeat count
Geometry Questions
setGeopoint(geopoint) - Set geopoint question valuesetGeometry(geometry) - Set map question geometry- Supports GeoJSON, Esri Geometry, or XLSForm formats
Common Patterns
Pre-populate Survey
webform.on("formLoaded", () => {
webform.setQuestionValue({
field_name: "John Doe",
email: "john@example.com",
location: { x: -118.2437, y: 34.0522 },
});
});
Handle Submission
webform.on("formSubmitted", (response) => {
console.log("Submission successful:", response);
});
Multi-language Support
IMPORTANT: Get language list from formLoaded event's data.form.locales, NOT from getLanguages().
Each locale object has { code, label, isDefault?, isCustomLocale?, isActive? }.
Pass locale.code to setLanguage().
webform.on("formLoaded", (data) => {
const locales = data.form.locales || [];
locales.forEach((locale) => {
console.log(`${locale.label} (${locale.code})`);
});
});
webform.setLanguage("es-mx");
Reference Documentation
Resources
