URL

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

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

with the following substitutions:

  • Replace {appId} with the GUID of the AppSheet app.

App ID
  • Replace {tableName} with the name of the table. Note that the table name should be URL-encoded.

Table name

Specifying Application Access Key When Invoking from a Webhook

The API ApplicationAccessKey must be present in every API call.


If you invoke the API from a workflow or report webhook action to access an app owned by you, the system automatically adds an HTTP header containing the ApplicationAccessKey.

If you invoke the API from a workflow or report webhook action access an application not owned by you, you must explicitly specify an HTTP header containing the ApplicationAccessKey for that application, and enclose the value in quotes. For example:

applicationAccessKey: "bA2SK-l5kzd-SdvFb-mqIe6-gBT8a-CXp3D-cjCYB-oiJ6U"

Specifying Application Access Key When Not Invoking from a Webhook

If you are invoking the API from something other than a workflow or report webhook action, you must specify the ApplicationAccessKey.

It is best to specify the ApplicationAccessKey in the HTTP headers because this is most secure. It is specified in the form:

ApplicationAccessKey=<applicationAccessKey>

For example:

ApplicationAccessKey=bA2SK-l5kzd-SdvFb-mqIe6-gBT8a-CXp3D-cjCYB-oiJ6U

If you must explicitly specify the ApplicationAccessKey but cannot do so in the HTTP headers, you can provide it in the HTTP query string. This is less secure than using HTTP headers. It is specified in the form:

https://api.appsheet.com/api/v2/apps/{appId}/tables/{tableName}/Action?applicationAccessKey=<applicationAccessKey>

For example:

https://api.appsheet.com/api/v2/apps/{appId}/tables/{tableName}/Action?applicationAccessKey=bA2SK-l5kzd-SdvFb-mqIe6-gBT8a-CXp3D-cjCYB-oiJ6U

If the ApplicationAccessKey is specified in both the HTTP headers and the HTTP query string, the value in the HTTP headers is used.


Application Access Key Validation

When the API is invoked, the ApplicationAccessKey is compared to the enabled Application Access Keys listed in Manage >> Integrations:

Application access keys

If the ApplicationAccessKey does not match any of the enable keys, the HTTP request is rejected and logged to the audit history.

HTTP Body

For example:

{
"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"
}
]
}

The API HTTP body specifies:

Actions

The name of the action to perform. Select one of the following values:

  1. Add: Adds a new row to the table.

  2. Delete: Deletes existing rows from the table.

  3. Edit: Updates existing rows in the table.

  4. Find: Reads an existing row of the table.

  5. Or specify the name of an existing data-change action for the table.

Properties

The properties of the API request are in JSON format. These properties are optional.

  • Locale
    The locale of the client making the request. For example, en-US indicates English, United States. If this value is not specified, Locale defaults to en-US.

    The Locale is used when validating Date, DateTime, Decimal, Percent, Price, and Time 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.

  • Location
    The latitude and longitude of the client making the request.

    This value is used for ChangeLocation columns. For example 47.623098, -122.330184 represents Seattle, Washington in the US. If not specified, Location defaults to 0.000000, 0.000000.

  • RunAsUserEmail
    The user email address of the person taking the action. The action is performed under the user ID of the user email address you specify. If this value is not specified, the action is performed under the user ID of the application owner.

    If you are performing an action against a table that uses data partitions and the partition expression is based on a USEREMAIL() value, you should specify the user email value here.

  • Timezone
    The timezone of the client making the request. For example, Pacific Standard Time indicates Pacific Standard Time in the United States and Canada. If not specified, Timezone defaults to UTC.

  • UserSettings
    The user setting to be used when performing the action. If not specified, no user settings are used.

    If you are performing an action against a table that uses data partitions and the partition expression is based on USERSETTINGS() values, you should specify those values here.

Rows

Include each column name and its intended value, in JSON format.

For all actions except Add, the row's key column name and value must be explicitly included.

For an Add action, the new row's key column must be given an explicit value, or enough other column values must be provided to allow the key column value to be generated according to the key column's definition. For instance, if the key column's Initial value expression is blank, the key column value must be provided explicitly. If the Initial value expression generates the key column value using other columns of the row, values for those other columns must be provided. If Initial value simply uses UNIQUEID() (for instance) to generate the key column value, the key column may be omitted.

Column constraints, if present in the column's definition, are enforced on column values provided through API calls: only a column allowed to change (per Editable_If) may be changed; a required column (per Required_If) must have a non-blank value; a non-blank value must be valid (per Valid_If).

For an Add action, for each column not included in the API call, the column's Initial value expression will be used to give the column a value.

For an action that modifies an existing row, for each column not included in the API call, the column's Reset on edit? setting will be checked and Initial value applied if indicated. Otherwise, the column's value will be unchanged.

Row Column Values

Each column's values must be suitable for the its column type.

The value for a Yes/No column can be specified in several equivalent ways.
All of the following values are equivalent ways of specifying "True".
Field values within quotes are case insensitive. For example, "TRUE, "True", "true", "TruE" are equivalent.

"MyBool": true 
"MyBool": "True"
"MyBool": "true"
"MyBool": "T"
"MyBool": "t"
"MyBool": "Yes"
"MyBool": "yes"
"MyBool": "Y"
"MyBool": "y"


All of the following values are equivalent ways of specifying "False".
Field values within quotes are case insensitive. For example, "FALSE, "False", "false", "FalsE" are equivalent.

"MyBool": false 
"MyBool": "False"
"MyBool": "false"
"MyBool": "F"
"MyBool": "f"
"MyBool": "No"
"MyBool": "no"
"MyBool": "N"
"MyBool": "n"

Special Characters in JSON

The following JSON special characters must be escaped when they appear in column names or column values.

Character

Escaped JSON Value

Backslash

\\

Backspace

\b

Carriage Return

\r

Double Quote

\"

Form Feed

\f

Newline

\n

Tab

\t

API Response HTTP Status Codes

The API returns the following HTTP status codes.

  1. 200 Success

  2. 400 Bad Request
    a. The Application Access Key is missing.
    b. The AppId is missing.
    c. The Post body contains invalid data.

  3. 403 Forbidden
    a. The Web API is not enabled for this application.
    b. The Application Access Key is invalid.

  4. 404 Not Found
    a. The application specified by the AppId cannot be found.

  5. 500 Internal Server Error
    a. An unexpected error occurred.

Did this answer your question?