Add records to a table

Add one or more new records to a table using the API.

See also: Example: Copy newly added records

URL

Use a URL in the following form to invoke the API:

POST https://api.appsheet.com/api/v2/apps/{appId}/tables/{tableName}/Action

Where:

• {appId} specifies the GUID of the AppSheet application. You can obtain the {appId} from the Manage > Integrations > IN pane.
• {tableName} specifies the name of the table.

Request body

The HTTP request body contains:

• The Action name Add.
• Optional properties such as Locale, Location, Timezone, and UserId.
  The Locale is used when validating Date, Time, DateTime, Decimal, Percent, and Price data values. For example, when Locale is en-US, date values must be entered in MM/DD/YYYY format. When Locale is en-GB, date values must be entered in DD/MM/YYYY format.
• One or more Rows elements.
  Each individual Row value must normally include the key field values of the record to be added. However, if the key field contains an Initial value, you can omit the key field value. For example, you should omit the key field value when the key field has an Initial value of UNIQUEID() or RANDBETWEEN(). The system will initialize the key field to the Initial value.
  
  Each Row value may contain field values of other fields in the added record. In the following example, the key fields of the record are FirstName and LastName.
  
  When you wish to add two or more rows, it is more efficient to add all of the rows in a single API call than to add each row in a separate API call. Using a single API call is significantly more efficient because we make few calls to the data provider.

{
"Action": "Add",
"Properties": {
   "Locale": "en-US",
   "Location": "47.623098, -122.330184",
   "Timezone": "Pacific Standard Time",
   "UserSettings": {
      "Option 1": "value1",
      "Option 2": "value2"
   }
},
"Rows": [
{
"FirstName": "Jan",
"LastName": "Jones",
"Age": 33,
"Department": "Accounting",
"Street": "110 Beach Blvd",
"City": "Newport Beach",
"State": "CA",
"Zip": 92661,
"Home Phone": 4257868765,
"Fax": 4253214432,
"Date Hired": "10/31/2014",
"Arrived": "8:15:25",
"Departed": "18:30:33",
"Last Review": "08/31/2017 23:59:59",
"Rating": 0.9950,
"Salary": 3333.45,
"Image": "http://images6.fanpop.com/image/photos/36300000/Emilia-Clarke-image-emilia-clarke-36399128-460-276.jpg"
},
{
"FirstName": "Ian",
"LastName": "Ivans",
"Age": 22,
"Department": "Payroll",
"Street": "118 E Oceanfront",
"City": "Newport Beach",
"State": "CA",
"Zip": 92661,
"Home Phone": 4257868148,
"Fax": 4253217798,
"Date Hired": "09/30/2014",
"Arrived": "7:40:25",
"Departed": "19:22:33",
"Last Review": "09/30/2017 23:59:59",
"Rating": 0.9750,
"Salary": 4444.45,
"Image": "http://images4.fanpop.com/image/photos/16300000/Christopher-Walken-3-christopher-walken-16367376-720-480.jpg"
}
]
}

Response body

The API returns the added rows in the HTTP response body.

{
  "Rows": [
{
"_RowNumber": 10,
"FirstName": "Jan",
"LastName": "Jones",
"Age": 33,
"Department": "Accounting",
"Street": "110 Beach Blvd",
"City": "Newport Beach",
"State": "CA",
"Zip": 92661,
"Home Phone": 4257868765,
"Fax": 4253214432,
"Date Hired": "10/31/2014",
"Arrived": "8:15:25",
"Departed": "18:30:33",
"Last Review": "08/31/2017 23:59:59",
"Rating": 0.9950,
"Salary": 3333.45,
"Image": "http://images6.fanpop.com/image/photos/36300000/Emilia-Clarke-image-emilia-clarke-36399128-460-276.jpg"
},
{
"_RowNumber": 11,
"FirstName": "Ian",
"LastName": "Ivans",
"Age": 22,
"Department": "Payroll",
"Street": "118 E Oceanfront",
"City": "Newport Beach",
"State": "CA",
"Zip": 92661,
"Home Phone": 4257868148,
"Fax": 4253217798,
"Date Hired": "09/30/2014",
"Arrived": "7:40:25",
"Departed": "19:22:33",
"Last Review": "09/30/2017 23:59:59",
"Rating": 0.9750,
"Salary": 4444.45,
"Image": "http://images4.fanpop.com/image/photos/16300000/Christopher-Walken-3-christopher-walken-16367376-720-480.jpg"
}
]
}

Response HTTP status codes

See Response HTTP status codes in Invoke an action.

What happens when a record is added?

1. All fields are initialized to initial values and all app formulas are computed.
2. The field values you specify in the request are applied.
3. App formulas are computed and change fields are updated.
4. Required, Required_If, and Valid_If conditions are enforced.
5. The record or records are added to the table.
6. Automation workflows, if any, are invoked.
7. The added record or records are returned in the HTTP content.