Append (Feature Service)

  • URL:https://<catalog-url>/<serviceName>/FeatureServer/append(POST only)


Online feature service supports an append API that has the ability to upsert data. It is a high performance API capable of handling large volume of data. Upsert is a combination of insert and update, driven by the featureId. Upsert is used to add new features and updating existing features at the same time. If a feature in the source data matches an existing feature in the destination layer, the existing feature is updated with the values from the source. If no match, then a new feature is created based on the values from the source.

The Append currently supports featureId of type ObjectId and GlobalId. The target layer needs to have a destination field of one of these types.

Unique Index on Source Data FeatureId

The destination objectId or globalId fields do not need to be mapped to source fields of the same type. Source featureId can come from different field type as long as the values are acceptable destination featureId value.


  • Destination globalIdcan be mapped to the following field types: {GlobalId, Guid, string} types.
  • ObjectId can be mapped to the following field types: {short, long}.

Note: When appending with upsert=true, the append API checks for uniqueness of the source featureId. Currently it is not acceptable to append two source rows to the same destination row. The append API would return an error if more than one source feature share the same featureId.

Enable/disable Append Capability

Feature service Append capability must be enabled in order to be used by non-admin users. Organization administrators or service owner can use the append API without adding the Append capability to the feature service. The Append needs to be added to the service capabilities only if the service owner or organization administrators needs to allow non-admin user to append data to a feature service from different sources.

Organization administrators or service owner can enable or disable the Append capability on existing feature service using the feature service updateDefinition API as shown in th example below.


{"capabilities":"Query, Append"}

The Append capability does not require any editing capabilities enabled. Features will be inserted or updated when upsert=true as part of the append operation without having the administrator to add Create or Update capabilities to the feature service.


A feature service and layer returns supportsAppend metadata property. When this property is absent or is false, the Append capability cannot be added to the feature service and the feature service does not support the Append operation even for the organization administrators or feature service owner.


{"supportsAppend" : true}

Sync/Append Capability

The Append capability is not currently supported if the feature service has Sync or ChangeTracking capabilities enabled and vise-versa; i.e., Sync or ChangeTracking cannot be enabled on the feature service if the service has Append capability enabled.

This Append is blocked for a couple of reasons:

  • The ESRI sync engines might not be able to support syncing the changes from the append operation. The append operation might be using a very low level database API taht might prevent the use of triggers to track the changes from the append operation. Online feature service sync engine relies on triggers to track the edit changes.
  • The volume of changes from append might be quite large for the syncing process and it will be better for the client to recreate the replica after append.

Views/Append Capability

The Append capability can be enabled on views.

Preserve FeatureId

The source featureId (ObjectId or GlobalId) are only preserved when using append with upsert=true. When upsert is false, all new reows created will have its new ObjectId or GlobalId allocated by the system.

Feature Service Metadata

The feature service metadata are updated after adding or updating data using the append API. The extent and lastEditDate of the feature service will be updated.


Append supports geocoding geometry from CSV and Excel data. Cost and billing of geocoding is the same cost and billing of geocoding during publishing data as a feature service.

Editor Tracking and Ownership-Based Access Control (OBAC)

Editor tracking is currently supported with feature service append API. The CreationDate and EditDate, Editor, Creator are populated based on the user who is calling append. Editor tracking fields are set when inserting or updating existing features. The creator and the editor fields will be set to the append user.

Service owner and administrators will bypass any OBAC set on the feature service. For non-owner, admin, if "allowsUpdateToOthers" is set to false on the feature service, the append user can only update his/her features or features owned by anonymous users.

OBAC is not currently supported and will be supported in future release. The UX is currently allowing only the owner/admin of the feature service to append data.

Appending MultiPatch Data (Online Feature Service 6.1)

Appending/upserting data to multipatch feature service is supported. In online feature service 6.1, the client can turn on Append capability on multipatch feature service using the feature service updateDefinition admin API. Similar to non-multipatch feature service, ObjectId, GlobalId, or any other fields with unique index can be used to upsert data to multipatch feature service.

The Append API would return an error when a client tries to append non-multipatch geometry data into a feature service that stores multipatch geometries.

Request Parameters


Description: The list of layers and table to upload.

Syntax: layers=[<layer1>, <layer2>, <layer3>]

Example: layers=0,1,2 or layers=[0,1,2]


Description: This is needed only if the source contains more than one table or if you need to specify field mapping for the destination layer. Used to map source data to a destination layer. The layerMappings contains fieldMappings object that is optional.

Syntax: layerMappings=[{"id" : <layerID>, "sourceTableName" : <"tableName">, "fieldMappings" : [{"name" : <"targetName">, "sourceName" : <"sourceName">}, ...]

Examples: layerMappings=[{"id" : 0, "sourceTableName" : "Countries"}]


Description: Only feature collection is supported. Append supports all formats through the uploadId.


Description: (Optional) Used to specify whether the edits needs to be applied as updates if the features already exists. The default value is false and ObjectId is used by default.

Values: true | false


Description: The ID for the uploaded item that contains the source file. Used in conjunction with editUploadFormat.

Example: appendUploadId=0c6b928f590f49ebac04761bab413e49

UploadId can be passed to append API if analyzing the data is not needed. Any upload items are temporary items and will be cleaned by the system. The feature service uploads API supports single upload item to 10M and multi-part uploads for more then 10M size file.



Description: The ID for the geowarehouse item that contains the source file. Used in conjunction with editsUploadFormat.

Example: appendItemId=894d8c12438v4baaac164b636f7e1e2f

The source file can be added as an item to ArcGIS portal and the itermId can be passed to the append API. The itemId can be used to analyze the source data file to know information about source fields name and provide a UX to map the source fields to the destination layer fields. The item added using portal addItem API is permeant item and would need to be cleaned up (if needed) by the caller after the append operation is finished.

Example: https://portal server Url/sharing/rest/content/users/userName/addItem


Description: The source append data format. The default is featureCollection format.

Values: sqllite | shapefile | filegdb | featureCollection | geojson | csv | excel


Description: (Optional) Used to specify whether the upsert edits needs to be rolled back in case of failure. The default value is false.

Value: true | false


Description: The response format. The default value is html.

Value: json | html

Example Usage

Example 1 (Append feature level): Appending data from shape file to feature service.<tenant>/ArcGIS/rest/services/USA/FeatureServer/append?

  • layers: 0
  • upsert: false
  • useGlobalIds: false
  • appendItemId: 0c6b928f590f49ebac04761bab413e49
  • appendUploadformat: shapefile
  • rollbackOnFailure: true
  • f: html

JSON Response Example


"status": "processing",

"statusMessage": "Job Status for jobId: b62e9db7-507c-443d-3473-8a1f7a7e9fac",

"itemId": "cc7ddbc1e33440688d3110c885fa0b30"


JSON Response Example

Example 2 (Check job status):<tenant>/ArcGIS/rest/services/USA/FeatureServer/ append/jobs/b62e9db7-507c-443d-3473-8a1f7a7e9fac?

JSON Response Example


"layerName": "CITIES",

"submissionTime": 1520876908117,

"lastUpdatedTime": 1520876913647,

"recordCount": 2,

"status": "Completed"


Example 3 (Append feature level):<tenant>/ArcGIS/rest/services/USA/FeatureServer/append?

  • layers: 0
  • layerMappings: [{"id":0,"sourceTableName":"USA"}]
  • upsert: false
  • useGlobalIds: false
  • appendUploadId: 0c6b928f590f49ebac04761bab413e49
  • appendUploadformat: filegdb
  • rollbackOnFailure: true
  • f: html

JSON Response Example


"status": "processing",

"statusMessage": "Job Status for jobId: feeahh1e-e32c-45bf-680c-f4ed70569081",

"itemId": "aa7gdww1e55200527d3110c634fa0b30"