Report

Survey123 reports allow you to turn your survey responses into richly formatted printable documents. For more information on creating reports directly in the Survey123 website and see Report templates. Behind the website, there is an API that manages this capability, and you can use this API directly in your own scripts and apps.

The same limitations that apply to report creation in the website, apply to report creation with the API.

URL:	https://survey123.arcgis.com/api/featureReport
Operation:	quickReference, createSampleTemplate, checkTemplateSyntax, createReport, createSampleReport, jobs/<jobId>, queryJobs, estimateCredits

The most common workflow is to submit a report generation job and then retrieve the results. The steps to complete this workflow are as follows.

Submit the report request using the createReport/submitJob endpoint. The response will include a jobId with which you can track this request.
Make a request at jobs/ to check the status of the job. Once finished, the job will have a jobStatus of esriJobSucceeded, esriJobPartialSucceeded or esriJobFailed.
Repeat the previous step at intervals of approximately 5 to 10 seconds, until one of the identified jobStatus values appears.
If the jobStatus is either esriJobSucceeded or esriJobPartialSucceeded, you can then download the output files. Either a URL to the file will be present in the resultInfo property for each file, or an identifier which corresponds to the itemID of the file in ArcGIS Online.

Quick Reference

URL:	https://survey123.arcgis.com/api/featureReport/quickReference
Method:	GET
Operation:	None

An operation to create samples of report template syntax depending on the input feature layer and survey item info. This assists the template author to create a report template.

Request parameters

Parameter	Required	Details
featureLayerUrl	true	The feature layer or table URL which contains the underlying data.
surveyItemId	false	Survey itemID, if present, will take survey question types into consideration when generating the result.
token	false	An access token that identifies the authenticated user with the portal. Required when survey is not shared to Everyone (Public).
portalUrl	false	URL of the portal where the survey item is hosted. If not supplied, default is https://www.arcgis.com/.
locale	false	The ISO 639-1 code to localize the date and time in the regional format. See Set language and region for supported languages and formats.
f	false	Supported value is `html`.

Response

A hosted HTML page containing samples of report template syntax.

Create Sample Template

URL:	https://survey123.arcgis.com/api/featureReport/createSampleTemplate
Method:	POST only
Operation:	None

An operation to create the default Word document template with placeholder, for authors to get started.

Request parameters

Parameter	Required	Details
featureLayerUrl	true	Feature layer or table URL, will return a Word document that includes placeholders for all fields in both main layer or table and all related layers or tables.
surveyItemId	false	Survey itemId, if presents, return a Word document generated by the Survey123 website.
token	true	The token to access all resources if needed.
portalUrl	false	Default is www.arcgis.com. The portal which includes the survey item.
outputFormat	false	Supported value is `docx`.
contentType	false	Specify which sections to include in the template. Accepted types are `individual`, `summary`, and `summaryIndividual`. Default is `individual` .

Response

The binary file of the generated sample template.

Check Template Syntax

URL:	https://survey123.arcgis.com/api/featureReport/checkTemplateSyntax
Method:	POST only
Operation:	None

A sync operation to check syntax which may lead to failure to generate a report, in a given report template file.

Request parameters

Parameter	Required	Details
templateFile	true	The report template file which syntax to be checked.
featureLayerUrl	true	Feature layer or table URL which contains the underlying data schema.
surveyItemId	false	Survey itemId, if presents, will check the syntax from a survey perspective, such as Image question can be found by attachment's keywords property.
token	true	The token to access all resources if needed.
portalUrl	false	Default is www.arcgis.com. The portal which includes the survey item.

Response example

A JSON object which contains an array of syntax errors.

Use dark colors for code blocksCopy
{
  "success": true,
  "individualSectionCount": 1,
  "summarySectionCount": 2,
  "details": [
    {
      "type": "(if feasible) pre-defined error type",
      "description": "error description 1"
    },
    {
      "type": "pre-defined error type",
      "description": "error description 2"
    }
  ]
}

Create Report

URL:	https://survey123.arcgis.com/api/featureReport/createReport
Method:	POST only
Operation:	`submitJob`

A task resource that represents a report printing tool based on a Word document template that can be leveraged by any feature layer in a feature service.

Request parameters

Parameter	Required	Details
featureLayerUrl	true	Feature layer or table URL.
queryParameters	true	A JSON object whose value will be passed to the query operation which filters features/records to be printed. If the filtered result has more than one record, the request will be considered as a batch printing. One individual report will be generated for each record. Supported list: `where`, `objectIds`, `orderByFields`, `resultRecordCount`. Syntax: `{"<supportedParam>": "<value>"}`. For example: `{"where": "STATUS = 'broken'","orderByFields":"inspectionDate DESC","resultRecordCount":10}`
templateItemId	true	The print template itemId, item type `Microsoft Word` is required.
token	true	The token to access all resources in the account.
portalUrl	false	Default is www.arcgis.com. The portal which includes the print template item, survey item, webmap item etc.
f	false	Supported value is `json`.
mergeFiles	false	Specify if print multiple records into a single report file (merged mode) or multiple files (split mode), and if in merge mode, start the next record on a new page or continue with the current page. Note: A merged file larger than 500MB will be split into mulitple files. `none`: Print multiple records in split mode, each record becomes a separated report file. This is the default value if `mergeFiles` is not specified in the request. `nextPage`: Print multiple records in merge mode, the content of the next record starts on the next new page. `continuous`: Print multiple records in merge mode, the content of the next record starts on the same page of the previous record.
outputFormat	false	Supported values are `docx` and `pdf`.
outputReportName	false	Specify the file name (without extension) of the result report file. For example, if `outputFormat` is `pdf`, input: "abc" -> output: "abc.pdf"; input: "abc.docx" -> output: "abc.docx.pdf". If `packageFiles` is true, `outputReportName` will be used for report files inside the packaged file. If `mergeFiles` is either `nextPage` or `continuous`, `outputReportName` will be used as the merged file name.
outputPackageName	false	Specify the file name (without extension)of the packaged file when `packageFiles` is `true`, for example, `<outputPackageName>.zip`.
packageFiles	false	Default is `auto`, which leaves the serverside to automatically decide whether to package generated report(s) as a .zip file depending on the output files count. A package larger than 500MB will be splitted into mulitple packages. The value is always `true` for `arcgis` storage service due to it does not have capability to package multiple files dynamically before downloading.
uploadInfo	false	A JSON object specifies additional storage service where the printed file(s) should be uploaded to for future access. If it's not specified, the printed file(s) will only be available to download for 24 hours. Syntax: `{"type": "<storage service>", "parameters": <JSON object>}`. `type`: which storage service the result file(s) will be uploaded to, only `arcgis` is available. `parameters`: all parameters which are needed to upload file(s) to the storage service. `conflictBehavior`: how to handle the conflict when a file already exists in the storage with the same report name. Available values: `rename`: default value. Rename the newly created report file/package to another name by adding a `<timestamp>` postfix. `replace`: replace the existing file. `fail`: make the request fail with an error message. For example: `{"type": "arcgis", "parameters": {"title": "item title here", "folderId": "folder id here"}}`
surveyItemId	false	Provides additional information on survey structure. For example, Multiple Choice questions require this parameter in order to access information on list labels.
webmapItemId	false	(Legacy: Replaced by map and mapScale) Specify the base map for printing task when printing a point/polyline/polygon. This takes precedence over the map set for each question inside a survey.
mapScale	false	Specify the map scale when printing, the map will center on the feature geometry.
map	false	Specifies the web map item ID when printing the map image.
utcOffset	false	Specify the time zone info when printing date/datetime in server-side. Acceptable formats are "±hh:mm", "±hhmm" and "±hh". UTC time will be used if not specified.
locale	false	The ISO 639-1 code to localize the date and time in the regional format. See Set language and region for supported languages and formats.
asyncPattern	false	If presents and the value is `true`, the response will work in the Asynchronous Request-Reply pattern.
#### Response example

When the operation is submitJob and f is json, the result is a job resource.

Use dark colors for code blocksCopy
{
  "jobId": "jc6a83a54037f49f88ad13d380296c727",
  "jobStatus": "esriJobSubmitted",
  "submitted": 213789327439821,
  "inputInfo": {
    "jobType": "createReport",
    "parameters": {
      "featureLayerUrl": "",
      "queryParameters": { "objectIds": "37, 462" },
      "templateItemId": "",
      "portalUrl": "",
      "f": "",
      "outputFormat": "",
      "outputReportName": "",
      "surveyItemId": "",
      "utcOffset": "",
      "packageFiles": true,
      "uploadInfo": {
        "type": "arcgis",
        "parameters": {
          "title": "item title",
          "folderId": ""
        }
      }
    }
  }
}

Create Sample Report

URL:	https://survey123.arcgis.com/api/featureReport/createSampleReport
Method:	POST only
Operation:	`submitJob`

A similar task resource to createReport for creating test sample report and refining a report template before generating any formal report.

Request parameters

Parameter	Required	Details
featureLayerUrl	true	Feature layer or table URL.
queryParameters	true	A JSON object whose value will be passed to the query operation which filters features/records to be printed. If the filtered result has more than one record, the request will be considered as a batch printing. One individual report will be generated for each record. Supported list: `where`, `objectIds`. Syntax: `{"<supportedParam>": "<value>"}`. For example: `{"where": "CITY_NAME = 'Barrington'"}` or `{"objectIds": "37, 462"}`
templateItemId	true	The print template itemId, item type `Microsoft Word` is required.
token	true	The token to access all resources in the account.
portalUrl	false	Default is www.arcgis.com. The portal which includes the print template item, survey item, webmap item etc.
f	false	Supported value is `json`.
mergeFiles	false	Specify if print multiple records into a single report file (merged mode) or multiple files (split mode), and if in merge mode, start the next record on a new page or continue with the current page. Note: A merged file larger than 500MB will be split into mulitple files. `none`: Print multiple records in split mode, each record becomes a separated report file. This is the default value if `mergeFiles` is not specified in the request. `nextPage`: Print multiple records in merge mode, the content of the next record starts on the next new page. `continuous`: Print multiple records in merge mode, the content of the next record starts on the same page of the previous record.
outputReportName	false	Specify the file name (without extension) of the result report file. For example, if `outputFormat` is `pdf`, input: "abc" -> output: "abc.pdf"; input: "abc.docx" -> output: "abc.docx.pdf". If `packageFiles` is true, `outputReportName` will be used for report files inside the packaged file. If `mergeFiles` is either `nextPage` or `continuous`, `outputReportName` will be used as the merged file name.
surveyItemId	false	Provides additional information on survey structure. For example, Multiple Choice questions require this parameter in order to access information on list labels.
webmapItemId	false	(Legacy: Replaced by map and mapScale) Specify the base map for printing task when printing a point/polyline/polygon. This takes precedence over the map set for each question inside a survey.
mapScale	false	Specify the map scale when printing, the map will center on the feature geometry.
map	false	Specifies the web map item ID when printing the map image.
utcOffset	false	Specify the time zone info when printing date/datetime in server-side. Acceptable formats are "±hh:mm", "±hhmm" and "±hh". UTC time will be used if not specified.
locale	false	The ISO 639-1 code to localize the date and time in the regional format. See Set language and region for supported languages and formats.
asyncPattern	false	If presents and the value is `true`, the response will work in the Asynchronous Request-Reply pattern.

Response example

When the operation is submitJob and f is json, the result is a job resource.

Use dark colors for code blocksCopy
{
  "jobId": "jc6a83a54037f49f88ad13d380296c727",
  "jobStatus": "esriJobSubmitted",
  "submitted": 213789327439821,
  "inputInfo": {
    "jobType": "createSampleReport",
    "parameters": {
      "featureLayerUrl": "",
      "queryParameters": { "objectIds": "37, 462" },
      "templateItemId": "",
      "portalUrl": "",
      "f": "",
      "outputReportName": "",
      "surveyItemId": "",
      "utcOffset": ""
    }
  }
}

Jobs

URL:	https://survey123.arcgis.com/api/featureReport/jobs/<jobId>
Method:	GET
Operation:	None

The job resource provides basic information about the job such as the job ID, status, and messages. Additionally, if the job has successfully completed, it provides information about the results as well as the input parameters.

Request parameters

Parameter	Required	Details
token	true	The token of the named account.
portalUrl	false	Default is www.arcgis.com.
f	false	Supported value is `json`.
asyncPattern	false	If presents and the value is `true`, the response will work in the Asynchronous Request-Reply pattern.

Response parameters

Parameter	Details
jobId	The requested job ID
jobStatus	The main job status. The following values are supported: `esriJobSubmitted`， `esriJobExecuting`，`esriJobSucceeded`，`esriJobPartialSucceeded` and `esriJobFailed`
jobStatusInfo	Only available when `jobStatus` is `esriJobExecuting` and `esriJobFailed`, reflects the underlying status of a batch printing job. Syntax: `{"jobStatusInfo": {"detailedStatus": "<detailedStatus>", "startTime": <startTime>, "progress": <progress>}}`. `detailedStatus`: the following values are supported `preparing`, `prepared`, `printing`, `printed`, `printFailed`, `merge`, `merging`, `mergeFailed`, `pdfConverting`, `pdfConverted`, `pdfConvertFailed`, `packaging`, `packaged`, `packageFailed`, `uploading` and `uploadFailed`. `startTime`: available for `esriJobExecuting`, the unix time when this specific phase started. `progress`: available for `esriJobExecuting`, a double value smaller than 1 indicates the completed progress of this phase.
submitted	The unix time when the job is accepted by the server
completed	The unix time when the job finishes processing on server-side. Only available for `esriJobSucceeded`, `esriJobPartialSucceeded` or `esriJobFailed`
resultInfo	A JSON object contains all the information related to the job result. It varies according to the `jobType` of the `inputInfo`. See the table below for details.
inputInfo	Syntax: `{"jobType": "<operation>", "parameters": <JSON object>}`. `jobType`: the requested operation, for example: `createReport` or `createSampleReport`. `parameters`: a JSON object contains all request parameters to the submitJob method.
messages	A JSON array of string. Detailed messages which describes the `jobStatus`.

The following table shows details of the resultInfo object when jobType of inputInfo is createReport.

Property	Details
title	The instance name of the job in case it will show up in the client-side UI. Usually, it's the item/file title in `uploadInfo`, or `outputReportName` if `uploadInfo` is not specified.
totalCount	Available when `jobStatus` is `esriJobExecuting`, `esriJobSucceeded`, `esriJobPartialSucceeded` or `esriJobFailed`. The count of records in the survey or the feature layer which are needed to generate report for.
succeededObjectIds	Available when `jobStatus` is `esriJobSucceeded`, `esriJobPartialSucceeded` or `esriJobFailed`. The array of object id for the record which report has been generated successfully.
failedObjectIds	Available when `jobStatus` is `esriJobSucceeded`, `esriJobPartialSucceeded` or `esriJobFailed`. The array of object id for the record which report has not been generated successfully.
resultFiles	Only available when `jobStatus` is `esriJobSucceeded` or `esriJobPartialSucceeded`, an array of `resultFile` object, which syntax is: `{"resultFiles": [{"id": "<resultFileId>", "url": "resultFileUrl", "objectIds": [<arrayOfObjectIdContainedInTheFile>]},...]}`. `id`: Available when `uploadInfo` is specified. A string represents the file or itemId of the result file which has been uploaded to the storage service. `url`: Available when `uploadInfo` is not specified. A string represents the download URL of the generated result file. `objectIds`: An array of object id, contains corresponding object ids whose generated report is included in this result file. Array length will be 1 if `mergeFiles` and `packageFiles` are `false` and >=1 if `mergeFiles` or `packageFiles` is `true`. `name`: the result filename contains extension. `size`: the result file size in bytes. Notes: `resultFiles` array length will equal to `recordsCount` if `mergeFiles` and `packageFiles` are `false`, otherwise, will be <totalSizeOfAllSingleReport>/<maxSizePerMergedFile>+1 or <totalSizeOfAllSingleReport>/<maxSizePerPackage>+1. `resultFile` file type will be a .zip package if `packageFiles` is `true`, otherwise, will be `docx` or `pdf` which supported by `outputFormat`.
details	Available when `jobStatus` is `esriJobSucceeded`, `esriJobPartialSucceeded` or `esriJobFailed`. An array of JSON object, which syntax is `{"objectId": <object id>, "status": "<current processing status>", "success": <is report generated successfully>, "messages": <message array>}`, represents the details of the report generating result for each record. Note: only records contained in `failedObjectIds` will appear. `objectId`: The object id of the record to generate report for. `status`: The last status of the report generating result for this record. The following values are supported: `submitted`, `printing`, `printed`, `printFailed`, `merge`, `merging`, `mergeFailed`, `pdfConverting`, `pdfConverted`, `pdfConvertFailed`, `packaging`, `packaged`, `packageFailed`, `uploading`, `uploaded`, `uploadFailed` and `chargeCreditsFailed`, package related statuses are available when `packageFiles` is `true`, upload related statuses are available when `uploadInfo` is specified. `success`: A general indicator of the final status. Record will show up here only when this value is `false` (contained in `failedObjectIds`). `messages`: Detailed messages.

Response example

Use dark colors for code blocksCopy
{
  "inputInfo": {
    "parameters": {
      "f": "json",
      "surveyItemId": "254c5d0c5c914672ba6751a6aaf1f543",
      "utcOffset": "||-08:00",
      "templateItemId": "e8d2d21aad3441f381f54d04deb3ce37",
      "featureLayerUrl": "https://services9.arcgis.com/QqYTCcI9gte4fVq0/arcgis/rest/services/service_2db7c94efd6c40fb9e6d857522cda321/FeatureServer/0",
      "queryParameters": {
        "objectIds": "126",
        "orderByFields": "||EditDate DESC, objectid ASC"
      },
      "outputReportName": "Sample Report"
    },
    "jobType": "createReport"
  },
  "submitted": 1609972524524,
  "jobId": "d7b97706dcc34ec1b4430f66239f72fe",
  "resultInfo": {
    "title": "Sample Report"
  },
  "jobStatus": "esriJobExecuting",
  "jobStatusInfo": {
    "detailedStatus": "preparing",
    "progress": 0,
    "startTime": 1577865600000
  }
}

Query Jobs

URL:	https://survey123.arcgis.com/api/featureReport/queryJobs
Method:	GET
Operation:	None

An operation to retrieve submitted jobs to the createReport task. Only the latest 10 jobs of the user will be returned.

Request parameters

Parameter	Required	Details
username	true	The user which to query against.
token	true	The token of the named account.
portalUrl	false	Default is www.arcgis.com.
surveyItemId	false	If specified, only jobs submitted to this survey will be returned.
featureLayerUrl	false	If specified, only jobs submitted to this feature layer will be returned.
f	false	Supported value is `json`.

Response example

An array of simplified job resource which resultInfo only contains title and totalCount.

Use dark colors for code blocksCopy
{
    "jobs": [{
            "jobId": "JE30155054C2C416EA3CF6C88A40B94FF",
            "jobStatus": "esriJobSucceeded",
            ...//all same properties as result of jobStatus, however, only title and totalCount will be included in resultInfo
        },
        {
            "jobId": "JE30155054C2C416EA3CF6C88A40B94FF",
            "jobStatus": "esriJobExecuting",
            ...//all same properties as result of jobStatus, however, only title and totalCount will be included in resultInfo
        },
        {
            "jobId": "JE30155054C2C416EA3CF6C88A40B94FF",
            "jobStatus": "esriJobFailed",
            ...//all same properties as result of jobStatus, however, only title and totalCount will be included in resultInfo
        }
    ]
}

Cancel Jobs

URL:	https://survey123.arcgis.com/api/featureReport/jobs/<jobId>/cancel
Method:	POST
Operation:	None

An operation to cancel creatReport or createSampleReport task.

Request parameters

Parameter	Required	Details
token	true	The token of the named account.
portalUrl	false	Default is www.arcgis.com.
f	false	Supported value is `json`.

Response example

A JSON object which contains the cancel result or error message.

Use dark colors for code blocksCopy
{
  "success": true | false,
  "jobId": "jc6a83a54037f49f88ad13d380296c727",
  "submitted": 213789327439821,
  "cancelled": 213789327439821, //only available when success is true
  "inputInfo": {
    "jobType": "createReport | createSampleReport",
    "parameters": {
      "featureLayerUrl": "",
      "queryParameters": "",
      "templateItemId": "",
      "portalUrl": "",
      "f": "",
      "outputFormat": "",
      "outputReportName": "",
      "surveyItemId": "",
      "utcOffset": "",
      "packageFiles": true,
      "uploadInfo": {
        "type": "arcgis",
        "parameters": {
          "title": "item title",
          "folderId": ""
        }
      }
    }
  },
    "resultInfo": {
    "title": "001_basemap of geopoint",
    "totalCount": 1
  }
}

Remove Jobs

URL:	https://survey123.arcgis.com/api/featureReport/jobs/<jobId>/remove
Method:	POST
Operation:	None

An operation to remove an existing task from the rencent tasks list.

Request parameters

Parameter	Required	Details
token	true	The token of the named account.
portalUrl	false	Default is www.arcgis.com.
f	false	Supported value is `json`.

Response example

A JSON object which contains the cancel result or error message.

Succeeded

Use dark colors for code blocksCopy
{
  "success": true,
  "jobId": "jc6a83a54037f49f88ad13d380296c727",
  "submitted": 213789327439821,
  "removed": 213789327439821,
  "inputInfo": {
    "jobType": "createReport | createSampleReport",
    "parameters": {
      "featureLayerUrl": "",
      "queryParameters": "",
      "templateItemId": "",
      "portalUrl": "",
      "f": "",
      "outputFormat": "",
      "outputReportName": "",
      "surveyItemId": "",
      "utcOffset": "",
      "packageFiles": true,
      "uploadInfo": {
        "type": "arcgis",
        "parameters": {
          "title": "item title",
          "folderId": ""
        }
      }
    }
  },
  "resultInfo": {
    "title": "001_basemap of geopoint",
    "totalCount": 1
  }

}

Failed

Use dark colors for code blocksCopy
{
    "success": false,
    "error": {
        "message": "Failed to remove job for e13a4706dc594f6d89a5b3f366f2f3ca. ",
        "code": "301",
        "details": [
             "job not exist"
         ]
    }
}

Estimate Credits

URL:	https://survey123.arcgis.com/api/featureReport/estimateCredits
Method:	GET
Operation:	None

An operation to estimate how many credits are required for a task with the given parameters.

Request parameters

Parameter	Required	Details
featureLayerUrl	true	Feature layer or table URL which contains the underlying data schema.
queryParameters	true	A JSON object whose value will be passed to the query operation which filters records to be printed. If the filtered result has more than one record, the request will be considered as a batch printing. One individual report will be generated for each record. Supported list: `where`, `objectIds`. Syntax: `{"<supportedParam>": "<value>"}`. For example, `{"where": "CITY_NAME = 'Barrington'"}` or `{"objectIds": "37, 462"}`
templateItemId	true	The print template itemId, item type `Microsoft Word` is required.
token	true	The token to access all resources in the account.
surveyItemId	false	Provides additional information on survey structure. For example, Multiple Choice questions require this parameter in order to access information on list labels.
portalUrl	false	Default is www.arcgis.com. The portal which includes the input resources.
f	false	Supported value is `json`.

Response example

A JSON object which contains the estimation result or error message.

Succeeded

Use dark colors for code blocksCopy
{
  "success": true,
  "resultInfo": {
    "totalRecords": 3,
    "cost": 7.5
  }
}

Failed

Use dark colors for code blocksCopy
{
  "success": false,
  "messages": []
}