AppSheet icon

AppSheet

Interact with the AppSheet API to add, read, update, delete records, or invoke a custom action on table records.

Actions7

Upsert Records

AI-generated

Summary

Upsert records into an AppSheet table, creating new rows or updating existing ones based on key fields.

Inputs

  • region — AppSheet region domain to use in the API URL (Global or EU).
  • tableName (required) — Name of the AppSheet table (URL-encoded if needed).
  • upsertRecords — Records to upsert, each containing key/value field pairs.
  • upsertKeyFields — Field names that uniquely identify a record in the table.
  • upsertBatchSize — Number of records per request; set to 0 to send all at once.
  • upsertDryRun — If true, only calculate what would be created or updated without actually performing the operation.

Output shape

object containing created (number), updated (number), createdRecords (array), updatedRecords (array)

When dryRun is true only the summary fields are returned; otherwise the object reflects actual created and updated records after batch processing.

Examples

Example 1: Upsert a new customer record in the EU region

region=eu.appsheet.com, tableName=Customers, upsertRecords=[{record:{fields:{Email:{value:'john@example.com'},Name:{value:'John Doe'}}}], upsertKeyFields=[{fieldName:'Email'}], upsertBatchSize=0, upsertDryRun=false

Example 2: Dry-run upsert to preview changes

region=www.appsheet.com, tableName=Orders, upsertRecords=[{record:{fields:{OrderID:{value:'12345'},Status:{value:'Pending'}}}], upsertKeyFields=[{fieldName:'OrderID'}], upsertDryRun=true

Example 3: Batch upsert of 500 records with batch size 100

region=eu.appsheet.com, tableName=Products, upsertRecords=[{...}], upsertKeyFields=[{fieldName:'ProductID'}], upsertBatchSize=100, upsertDryRun=false

Links

Discussion