Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial
Developer API
Resources

Data tables ​

Refer to the following sections to programmatically manage data tables and their records using APIs:

Rate limits ​

Data table resources have the following rate limits:

TypeResourceLimit
AllAll Data tables endpoints60 requests per minute

Data center base URLs ​

Each data center (DC) has a dedicated base URL. Use the base URL that matches your workspace region. Sample requests in this section use the US base URL.

The following example shows the data-tables base URL modified for each data center:

Data centerBase URL
UShttps://data-tables.workato.com
EUhttps://data-tables.eu.workato.com
JPhttps://data-tables.jp.workato.com
SGhttps://data-tables.sg.workato.com
AUhttps://data-tables.au.workato.com
ILhttps://data-tables.il.workato.com
CNhttps://data-tables.workatoapp.cn
KRhttps://data-tables.kr.workato.com
Trialhttps://data-tables.trial.workato.com

Workato returns a 403 Forbidden error if you call an endpoint that doesn't match your workspace data center.

Table management APIs ​

You can use the following endpoints to manage and structure data tables:

Base URL:

https://YOUR_DATA_CENTER/api

REGIONAL BASE URLS

You must use the dedicated base URL that matches your workspace region. Refer to Data center URLs for more information.

Quick reference ​

TypeResourceDescription
GET/api/data_tablesList all data tables.
GET/api/data_tables/:data_table_idGet data table by ID.
POST/api/data_tablesCreates a data table.
PUT/api/data_tables/:data_table_idUpdates a data table.
DELETE/api/data_tables/:data_table_idDeletes a data table.
POST/api/data_tables/:data_table_id/truncateTruncates a data table.

List data tables ​

Returns a list of all data tables in your workspace.

bash
GET https://YOUR_DATA_CENTER/api/data_tables

URL parameters ​

NameTypeDescription
pageinteger
optional		Page number of the data tables to fetch. Defaults to 1.
per pageinteger
optional		Page size. Defaults to 100. Maximum is 100.

Sample request ​

shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/data_tables'
      -H 'Authorization: Bearer <api_token>'

Response ​

View a sample response
json
{
    "data": [
        {
            "id": "f4d2e85d-c7f4-4877-8f16-6643a4b3fb23",
            "name": "Resume screening",
            "schema": [
                {
                    "type": "string",
                    "name": "application_id",
                    "optional": true,
                    "field_id": "8f4a57d6-f524-47f2-ae59-be1a80dc2dd5",
                    "hint": "Greenhouse application ID",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "string",
                    "name": "candidate_id",
                    "optional": true,
                    "field_id": "b3f6f50a-6431-4cd4-af2c-f88a7b291bce",
                    "hint": "Greenhouse candidate ID",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "string",
                    "name": "job_id",
                    "optional": true,
                    "field_id": "cdf319f0-2bde-4048-bde6-4c862e7737bd",
                    "hint": "Greenhouse job ID",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "string",
                    "name": "department",
                    "optional": true,
                    "field_id": "25256ad2-5297-46e3-960b-f340af9d292f",
                    "hint": "Hiring department",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "string",
                    "name": "recruiter",
                    "optional": true,
                    "field_id": "38a85051-a12c-4f0b-a308-7e8cd5c68e78",
                    "hint": "Recruiter name",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "string",
                    "name": "task_name",
                    "optional": true,
                    "field_id": "a305f5b1-df86-4f3f-a434-db142c9f5b95",
                    "hint": "Workflow stage",
                    "metadata": {},
                    "multivalue": false
                }
            ],
            "folder_id": 24468824,
            "created_at": "2025-04-04T11:35:04.544-07:00",
            "updated_at": "2025-04-04T11:55:50.473-07:00"
        },
        {
            "id": "fb0b03f3-2e5a-4a05-a483-4ee3092805c5",
            "name": "Intake form",
            "schema": [
                {
                    "type": "string",
                    "name": "Description",
                    "optional": true,
                    "field_id": "b3545fa7-600c-4ed0-ab04-6e4a866db158",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "string",
                    "name": "Review comments",
                    "optional": true,
                    "field_id": "9db1ae98-01f2-4da5-9003-058d8ce80475",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "number",
                    "name": "Rate",
                    "optional": true,
                    "field_id": "7b98b819-f8bc-4376-9eb1-ef18c5ca9ae1",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "string",
                    "name": "Notes",
                    "optional": true,
                    "field_id": "35885b91-ee7e-453e-a4f9-d41c88e74521",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "boolean",
                    "name": "pass",
                    "optional": true,
                    "field_id": "4b0f3ac7-0dad-4628-85a8-85583c9a09d9",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "string",
                    "name": "Reviewer",
                    "optional": true,
                    "field_id": "a1913ee5-6342-4176-8e25-8c4787286fee",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "file",
                    "name": "Resume",
                    "optional": true,
                    "field_id": "8853cfa6-9e69-4b57-98cb-5264497b1dac",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "string",
                    "name": "Email",
                    "optional": true,
                    "field_id": "fea109b6-95c2-41a9-9075-000aa4e54b6a",
                    "metadata": {},
                    "multivalue": false
                }
            ],
            "folder_id": 21138015,
            "created_at": "2024-10-04T08:40:24.349-07:00",
            "updated_at": "2025-04-03T10:02:37.905-07:00"
        },
        {
            "id": "d263710a-e7cc-418f-bbc5-aacf76667418",
            "name": "PTO requests",
            "schema": [
                {
                    "type": "string",
                    "name": "Name",
                    "optional": false,
                    "field_id": "4cd59a12-ae0c-40fa-8896-fd259b271fd9",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "string",
                    "name": "Description",
                    "optional": true,
                    "field_id": "06e65f37-81eb-4093-8219-f8b14b2b23e8",
                    "metadata": {},
                    "multivalue": false
                },
                {
                    "type": "string",
                    "name": "Review comments",
                    "optional": true,
                    "field_id": "cb1589c6-2537-43f8-bd5d-6776b310d080",
                    "metadata": {},
                    "multivalue": false
                }
            ],
            "folder_id": 17415752,
            "created_at": "2024-09-26T20:49:04.147-07:00",
            "updated_at": "2024-09-26T20:49:04.222-07:00"
        }
    ]
}

Get data table by ID ​

Returns the data table associated with the ID you specify.

bash
GET https://YOUR_DATA_CENTER/api/data_tables/:data_table_id

URL parameters ​

NameTypeDescription
data_table_idinteger
required		Provide the ID of a specific data table.

Sample request ​

shell
curl  -X GET 'https://YOUR_DATA_CENTER/api/data_tables/:data_table_id'
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
    "data": {
        "id": "db4b8544-8de8-4c6d-83bd-e487f6616ccc",
        "name": "Expense reports",
        "schema": [
            {
                "type": "string",
                "name": "Expense type",
                "optional": false,
                "field_id": "1ec0c3c7-abcd-4bca-bab5-efa51da56635",
                "metadata": {},
                "multivalue": false
            },
            {
                "type": "number",
                "name": "Cost",
                "optional": true,
                "field_id": "b3545fa7-600c-4ed0-ab04-6e4a866db158",
                "metadata": {},
                "multivalue": false
            },
            {
                "type": "date",
                "name": "Date of purchase",
                "optional": true,
                "field_id": "9db1ae98-01f2-4da5-9003-058d8ce80475",
                "metadata": {},
                "multivalue": false
            },
            {
                "type": "integer",
                "name": "Priority",
                "optional": true,
                "field_id": "7b98b819-f8bc-4376-9eb1-ef18c5ca9ae1",
                "metadata": {},
                "multivalue": false
            },
        ],
        "folder_id": 1124996,
        "created_at": "2025-05-16T13:30:09.835+08:00",
        "updated_at": "2025-05-16T13:30:09.835+08:00"
    }
}

Record import status ​

The response also includes a records_import_status object while a record import is in progress, and for up to 24 hours after it completes or until it's dismissed. Automated pipelines can use this object to detect a failed import:

NameTypeDescription
filenamestringThe file name provided when starting the import.
total_bytesintegerThe total size of the file in bytes.
total_recordsintegerThe total number of records in the file.
statusstringThe import status, such as in_progress, completed, or failed.
processed_recordsintegerThe number of records processed so far.
etastringThe estimated time of completion. Present when status is in_progress.
completed_atstringThe time the import completed. Present when status is completed.
failed_atstringThe time the import failed. Present when status is failed.
is_internal_errorbooleanIndicates whether a failure is due to an internal Workato error rather than an error in the imported data. Present when status is failed.
errorstringA human-readable description of the failure. Present when status is failed.
error_record_idxintegerThe 0-based index of the record that caused the failure. Present when status is failed.
error_detailsobjectContains details about the failure. Present when status is failed. Refer to Error codes for the possible values.

The following example shows a completed import:

json
{
  "data": {
    "records_import_status": {
      "filename": "bank_report.csv",
      "total_bytes": 3005,
      "total_records": 18,
      "status": "completed",
      "processed_records": 18,
      "completed_at": "2026-07-09T17:44:42.877+00:00"
    }
  }
}
Error codes ​

The response contains an error_details object when status is failed, which contains an error_code field with one of the following values:

Error codeAdditional fieldsDescription
MAX_TABLE_SIZE_EXCEEDEDmax_table_size_bytesThe import would exceed the maximum table size.
MAX_NUM_RECORDS_EXCEEDEDmax_num_recordsThe import would exceed the maximum number of records per table.
MAX_DOCUMENT_SIZE_EXCEEDEDmax_document_size_bytesA record would exceed the maximum record size.
TEXT_VALUE_TOO_LONGfield_id, field_name, max_text_value_charsA text value exceeds the maximum number of characters allowed for the field.

LIMITS

Refer to Data tables - Limits for the size and record limits that apply to imports.

Failed import example

The import failed in the following example because a text value exceeds the maximum number of characters allowed for the description field:

json
{
  "data": {
    "records_import_status": {
      "filename": "bank_report.csv",
      "total_bytes": 15295,
      "total_records": 1,
      "status": "failed",
      "processed_records": 0,
      "failed_at": "2026-07-13T17:05:10.565+00:00",
      "is_internal_error": false,
      "error": "value in field \"description\": text is too long (15000 characters, max allowed: 10000)",
      "error_record_idx": 0,
      "error_details": {
        "error_code": "TEXT_VALUE_TOO_LONG",
        "field_id": "4b01d22e-b888-4d1d-b90c-7c78ad75424d",
        "field_name": "description",
        "max_text_value_chars": 10000
      }
    }
  }
}

Create data table ​

Creates a data table in a folder you specify.

bash
POST https://YOUR_DATA_CENTER/api/data_tables

Payload ​

NameTypeDescription
namestring
required		The name of the data table to create.
folder_idinteger
required		Provide the ID of the folder where you plan to create the data table.
schemaarray
required		Supply an array of nested elements to define your table structure. You must supply the column name, data type, and whether the column is required.
schema[type]boolean, date, date_time, integer, number, string, file, relation
required		The data type of the column you plan to create.
schema[name]string
required		The name of the column you plan to create.
schema[optional]integer, boolean
required		Indicates if the column is required or optional. Must be either true, false, 1, or 0.
schema[field_id]Must match regular expression: /\h{8}-\h{4}-\h{4}-\h{4}-\h{12}/
optional		Unique Universal Identifier (UUID) of the column. Must follow this format: f47ac10b-58cc-4372-a567-0e02b2c3d479.
schema[hint]string
optional		Provide a hint to help your end users populate entries in a data column. The hint displays as a tooltip when you hover over the column in the user interface.
schema[default_value]variable
optional		The default value of the column. Must match the data type of the column specified in the request.
schema[metadata]hash
optional		Data table metadata.
schema[relation]hash
optional		Indicates that this table links to another data table.
schema[relation][table_id]string
optional		The ID of the data table linked to this table.
schema[relation][field_id]string
required		The column ID of a linked data table.
schema[multivalue]boolean optionalIndicates whether the column accepts multi-value input.

Sample request ​

shell
curl  -X POST 'https://YOUR_DATA_CENTER/api/data_tables' \
	  -H 'Authorization: Bearer <api_token>' \
	  -H 'Content-Type: application/json' \
	  -d '{
            "name": ":name",
            "folder_id": :folder_id_value,
            "schema": [
                {
                    "type": ":type",
                    "name": ":name",
                    "optional": :true_or_false,
                    "multivalue": :true_or_false,
                    "relation": {
                        "table_id": ":table_id",
                        "field_id": ":field_id"
                    }
            ]
      }

Response ​

json
{
    "data": {
        "id": "52d97443-1dbd-4ae0-9cd9-99ac2d020977",
        "name": "Expense reports 4",
        "schema": [
            {
                "type": "string",
                "name": "Expense type",
                "optional": false,
                "field_id": "76ddbd6f-35ea-4884-bb97-cecac5d4abc7",
                "metadata": {},
                "multivalue": true,
                "relation": {
                    "table_id": "2507a39a-6847-4857-88ed-c3b9c8302e02",
                    "field_id": "900454f4-5b3d-4670-bc3c-d640915156f2"
            }}
        ]
    }
}

Update data table ​

Updates a data table you specify.

bash
PUT https://YOUR_DATA_CENTER/api/data_tables/:data_table_id

URL parameters ​

NameTypeDescription
data_table_idstringThe ID of the data table you plan to update. You can use the List data tables endpoint to retrieve data table IDs.

Payload ​

NameTypeDescription
namestring
required		The name of the data table to create.
folder_idstring
optional		Provide the ID of the folder where you plan to create the data table.
schemaarray
required		Supply an array of nested elements to define your table structure. You must supply the column name, data type, and whether the column is required.
schema[type]boolean, date, date_time, integer, number, string, file, relation
required		The data type of the column you plan to create.
schema[name]string
required		The name of the column you plan to create.
schema[optional]integer, boolean
required		Indicates if the column is required or optional. Must be either true, false, 1, or 0.
schema[field_id]Must match regular expression: /\h{8}-\h{4}-\h{4}-\h{4}-\h{12}/
optional		Unique Universal Identifier (UUID) of the column. Must follow this format: f47ac10b-58cc-4372-a567-0e02b2c3d479.
schema[hint]string
optional		Provide a hint to help your end users populate entries in a data column. The hint displays as a tooltip when you hover over the column in the user interface.
schema[default_value]variable
optional		The default value of the column. Must match the data type of the column specified in the request.
schema[metadata]hash
optional		Data table metadata.
schema[relation]hash
optional		Indicates that this table links to another data table.
schema[relation][table_id]string
optional		The ID of the data table linked to this table.
schema[relation][field_id]string
required		The column ID of a linked data table.
schema[multivalue]boolean optionalIndicates whether the column accepts multi-value input.

Sample request ​

shell
curl  -X PUT 'https://YOUR_DATA_CENTER/api/data_tables/:data_table_id' \
	  -H 'Authorization: Bearer <api_token>' \
	  -H 'Content-Type: application/json' \
	  -d '{
            "name": ":name",
            "folder_id": :folder_id_value,
            "schema": [
                {
                    "type": ":type",
                    "name": ":name",
                    "optional": :true_or_false,
                    "multivalue": :true_or_false,
                    "relation": {
                        "table_id": ":table_id",
                        "field_id": ":field_id"
                    }
            ]
      }

Response ​

json
{
    "data": {
        "id": "52d97443-1dbd-4ae0-9cd9-99ac2d020977",
        "name": "Expense reports updated",
        "schema": [
            {
                "type": "string",
                "name": "Expense type",
                "optional": false,
                "field_id": "318b18ca-bb5f-426c-adb1-74eb2fc06641",
                "default_value": [],
                "metadata": {},
                "multivalue": true
            },
            {
                "type": "date",
                "name": "Date",
                "optional": true,
                "field_id": "97a960ee-022b-4a69-bcdb-74bb4c3d524d",
                "metadata": {},
                "multivalue": false
            },
            {
                "type": "boolean",
                "name": "Status",
                "optional": true,
                "field_id": "66b7f251-b874-4d87-a974-c18260a6a8fb",
                "metadata": {},
                "multivalue": false
            },
            {
                "type": "date_time",
                "name": "Check-in",
                "optional": true,
                "field_id": "6c119dad-3d08-427d-bac2-27536aedebad",
                "metadata": {},
                "multivalue": false
            },
            {
                "type": "file",
                "name": "Reciept",
                "optional": true,
                "field_id": "a6e5360f-5b5e-4261-9967-4160bd80e1a0",
                "metadata": {},
                "multivalue": false
            },
            {
                "type": "integer",
                "name": "Length of stay in days",
                "optional": true,
                "field_id": "bea282f0-fc78-4847-b7c8-a93587835faa",
                "metadata": {},
                "multivalue": false
            },
            {
                "type": "number",
                "name": "Cost",
                "optional": true,
                "field_id": "7d438888-5e04-4b70-b7b1-e54cdc42e877",
                "metadata": {},
                "multivalue": false
            },
            {
                "type": "relation",
                "name": "Budget",
                "optional": true,
                "field_id": "ebe23be4-d388-42fd-922b-0fb4e57abc08",
                "metadata": {},
                "relation": {
                    "table_id": "2507a39a-6847-4857-88ed-c3b9c8302e02",
                    "field_id": "900454f4-5b3d-4670-bc3c-d640915156f2"
                },
                "multivalue": false
            }
        ],
        "folder_id": 75509,
        "created_at": "2025-05-21T14:56:49.173-07:00",
        "updated_at": "2025-05-21T15:36:23.701-07:00"
    }
}

Delete data table ​

Deletes a data table you specify.

bash
DELETE https://YOUR_DATA_CENTER/api/data_tables/:data_table_id

URL parameters ​

NameTypeDescription
data_table_idinteger
required		Data table ID.

Sample request ​

shell
curl -X DELETE 'https://YOUR_DATA_CENTER/api/data_tables/:data_table_id'
     -H 'Authorization: Bearer <api_token>'

Response ​

json
{
    "data": {
        "status": "success"
    }
}

Truncate data table ​

Truncates a data table you specify. Truncating a data table deletes all data from a data table, but doesn't effect the table structure.

bash
POST https://YOUR_DATA_CENTER/api/data_tables/:data_table_id/truncate

URL parameters ​

NameTypeDescription
data_table_idinteger
required		Data table ID.

Sample request ​

shell
curl  -X POST 'https://YOUR_DATA_CENTER/api/data_tables/:data_table_id/truncate'
      -H 'Authorization: Bearer <api_token>'

Response ​

json
{
    "data": {
        "status": "success"
    }
}

Record manipulation APIs ​

You can use the following endpoints to create, delete, and update data table records. Refer to the OpenAPI Specification for additional information.

Base URL: https://data-tables.workato.com

REGIONAL BASE URLS

You must use the dedicated base URL that matches your workspace region. Refer to Data center URLs for more information.

Quick reference ​

TypeResourceDescription
POST/api/v1/tables/:data_table_id/queryQueries records using filters you specify.
POST/api/v1/tables/:data_table_id/recordsCreates a new record.
PUT/api/v1/tables/:data_table_id/records/:record_idUpdates an existing record.
DELETE/api/v1/tables/:data_table_id/records/:record_idDeletes a record you specify.
POST/api/v1/tables/:data_table_id/fields/:field_id/fileGenerates a link to upload a file.
GET/api/v1/tables/:data_table_id/records/:record_id/fields/:field_id/fileGenerates a link to download a file.

Query records (v1) ​

Queries records in a data table based on filters you specify.

bash
POST https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/query

URL parameters ​

NameTypeDescription
data_table_idstringThe ID of the data table you plan to update. You can use the List data tables endpoint to retrieve data table IDs.

Payload ​

NameTypeDescription
selectarray
optional		Provide the list of columns to be retrieved from the data table.
wherehash
optional		Set of conditions to filter the records with. Refer to the where clause section for more information.
orderstring or hash
optional		The column to order the results with. Provide either a string, or a hash for more advanced ordering configuration. Detailed breakdown of the hash structure can be found below.
timezone_offset_secsinteger
optional		The time zone offset for query. Required if the query includes comparison of a date-time field to a date value.
limitinteger
optional		Limits the number of records to return per page. The maximum is 200.
continuation_tokenstring
optional		Provide the next page token from previous page's request to fetch the next set of results of the same query.

INFO

The following meta-fields can be used in order parameters with the fields you created: $record_id, $created_at, and $updated_at.

where field structure ​

A basic where clause uses the following format:

{ <field>: { <operator>: <value> } }

You can set the <value> to a primitive value or an object.

The following table lists available operator values:

OperatorDescriptionExample
$eqEqual{ "name": { "$eq": "Josh" } }
$neNot equal{ "status": { "$ne": "inactive" } }
$gteGreater than or equal to{ "score": { "$gte": 75 } }
$gtGreater than{ "score": { "$gt": 90 } }
$lteLess than or equal to{ "amount": { "$lte": 13 } }
$ltLess than{ "amount": { "$lt": 10 } }
$inIn (returns records where value matches any of the items in the <value>){ "name": { "$in": ["Josh", "Bob", "Alice"] } }
$starts_withStarts with{ "email": { "$starts_with": "admin@" } }
Compound conditions ​

You can combine multiple conditions with $and compound operator using the format { "$and": [ <condition1>, <condition2>, ... ] }. For example:

json
{
  "$and": [
    {
      "name": "Josh"
    },
    {
      "id": {
        "$lte": 13
      }
    }
  ]
}

Alternatively, you can use the equivalent short-hand notation for the $and operator. For example:

json
{
  "name": "Josh",
  "id": { "$lte": 13 }
}
order field hash structure ​

You must use the following structure when you provide a hash for the order field:

json
{
  "by": <field>,
  "direction": "asc" | "desc",
  "case_sensitive": true | false
}

Sample request ​

shell
curl  -X POST 'https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/query' \
	  -H 'Authorization: Bearer <api_token>' \
	  -H 'Content-Type: application/json' \
	  -d '{
            "select": [":select_column_1", ":select_column_2"],
            "where":
                {
                    ":where_field_1": { "$gt": :where_value_1 },
                    ":where_field_2": ":where_value_2"
                },
            "order": ":order",
            "limit": :limit_value,
            "timezone_offset_secs": :timezone_offset_secs_value
        }'

Response ​

json
{
  "schema": [
    [ // Metafields
      { "name": "$record_id" },
      { "name": "$created_at" },
      { "name": "$updated_at" }
    ],
    [ // Fields
      { "name": "Name", "id": "2507a39a-6847-4857-88ed-c3b9c8302e02" },
      { "name": "Address", "id": "4705a22b-9139-6482-332a-ca2dd2d03sd3" },
      ...
    ]
  ],
  "data": [
    [ // Record 1
      [ // Metafields
        "e9498300-1ea3-4bf0-bdea-ffe58c101bcf",
        "2025-08-19T17:53:48.073+00:00",
        "2025-08-19T17:53:48.073+00:00"
      ],
      [ // Fields
        "Ann-Marie Tan",
        "5 Pennsylvania Ave. S320123"
      ]
    ],
    [ // Record 2
      [ // Metafields
        "900454f4-5b3d-4670-bc3c-d640915156f2",
        "2025-08-19T17:53:48.073+00:00",
        "2025-08-19T17:53:48.073+00:00"
      ],
      [ // Fields
        "John Paul Lim",
        "8 Somapah Road S210492"
      ]
    ],
    ...
  ],
  "count": 2,
  "limit": 10
}

Create record (v1) ​

Creates a record in a specified data table.

bash
POST https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/records

URL parameters ​

NameTypeDescription
data_table_idstringThe ID of the data table where you plan to create the record. You can use the List data tables endpoint to retrieve data table IDs.

Payload ​

The structure of the request payload is a key-value pair of each field. You can specify fields by their UUIDs (dollar-escaped) or names. Fields not listed in the schema are replaced with default values. Extra fields that aren't included in the schema are ignored.

Sample request ​

shell
curl  -X POST 'https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/records' \
	  -H 'Authorization: Bearer <api_token>' \
	  -H 'Content-Type: application/json' \
	  -d '{
            "document":
            {
                ":field_name_1": ":field_value_1",
                ":field_name_2": :field_value_2,
                ":$field_id_uuid": :field_value_3,
                ":field_name_date": ":field_value_date",
                ":field_name_relation":
                    {
                        "record_id": ":record_id"
                    },
                ":field_name_file":
                    {
                        "filename": ":filename",
                        "upload_id": ":upload_id"
                    }
            }
        }'

Response ​

json
{
    "data": {
        "record_id": "ab0189ca-fadf-4382-a48b-e157d966078f",
        "created_at": "2025-07-10T15:55:02.661+00:00",
        "updated_at": "2025-07-10T15:55:02.661+00:00",
        "document": [
            {
                "field_id": "42d62e3b-895d-43db-b8f7-cbb62dac71dd",
                "field_name": "name",
                "value": "Josh"
            },
            {
                "field_id": "2dca773b-eb67-4201-924d-4ccb9d577e99",
                "field_name": "multivalue",
                "value": [1,2,3]
            },
            {
                "field_id": "28c00d59-7dbe-4134-85be-937513500500",
                "field_name": "age",
                "value": 13
            },
            {
                "field_id": "0489bb65-7072-404f-9bba-e3e94a2a527b",
                "field_name": "date",
                "value": "2022-02-01"
            },
            {
                "field_id": "d6f103d9-575f-41b9-9ef0-b70e8fe38cc8",
                "field_name": "relation",
                "value": {
                    "record_id": "7a13304c-14cf-4e98-be31-331ccdb2b253",
                    "value": "Parent"
                },
            },
            {
                "field_id": "f71f1f67-0de5-422c-be73-b27b12f442c4",
                "field_name": "file",
                "value": {
                    "filename": "birth_certificate.txt"
                },
            }
        ]
    }
}

Update record (v1) ​

Updates a record in a specified data table.

bash
PUT https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/records/:record_id

URL parameters ​

NameTypeDescription
data_table_idstringThe ID of the data table where the record resides. You can use the List data tables endpoint to retrieve data table IDs.
record_idstringThe ID of the record to be updated.

Payload ​

The structure of the request payload is a key-value pair of each field. You can specify fields by their UUIDs (dollar-escaped) or names. Fields not listed in the schema aren't updated. Extra fields that aren't included in the schema are ignored.

Sample request ​

shell
curl  -X PUT 'https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/records/:record_id' \
	  -H 'Authorization: Bearer <api_token>' \
	  -H 'Content-Type: application/json' \
	  -d '{
            "document":
            {
                ":field_name_1": ":field_value_1",
                ":field_name_2": :field_value_2,
                ":$field_id_uuid": :field_value_3,
                ":field_name_date": ":field_value_date",
                ":field_name_relation":
                    {
                        "record_id": ":record_id"
                    },
                ":field_name_file":
                    {
                        "filename": ":filename",
                        "upload_id": ":upload_id"
                    }
            }
        }'

Response ​

json
{
    "data": {
        "record_id": "ab0189ca-fadf-4382-a48b-e157d966078f",
        "created_at": "2025-07-10T15:55:02.661+00:00",
        "updated_at": "2025-07-10T15:55:02.661+00:00",
        "document": [
            {
                "field_id": "42d62e3b-895d-43db-b8f7-cbb62dac71dd",
                "field_name": "name",
                "value": "Josh"
            },
            {
                "field_id": "2dca773b-eb67-4201-924d-4ccb9d577e99",
                "field_name": "multivalue",
                "value": [1,2,3]
            },
            {
                "field_id": "28c00d59-7dbe-4134-85be-937513500500",
                "field_name": "age",
                "value": 13
            },
            {
                "field_id": "0489bb65-7072-404f-9bba-e3e94a2a527b",
                "field_name": "date",
                "value": "2022-02-01"
            },
            {
                "field_id": "d6f103d9-575f-41b9-9ef0-b70e8fe38cc8",
                "field_name": "relation",
                "value": {
                    "record_id": "7a13304c-14cf-4e98-be31-331ccdb2b253",
                    "value": "Parent"
                },
            },
            {
                "field_id": "f71f1f67-0de5-422c-be73-b27b12f442c4",
                "field_name": "file",
                "value": {
                    "filename": "birth_certificate.txt"
                },
            }
        ]
    }
}

Delete record (v1) ​

Deletes a record in a specified data table.

bash
DELETE https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/records/:record_id

URL parameters ​

NameTypeDescription
data_table_idstringThe ID of the data table where the record resides. You can use the List data tables endpoint to retrieve data table IDs.
record_idstringThe ID of the record to be updated.

Sample request ​

shell
curl -X DELETE 'https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/records/:record_id'
     -H 'Authorization: Bearer <api_token>'

Response ​

Workato returns status code 200 without a response payload if the deletion is successful.

Generates a link to upload a file for file-type columns. Use the resulting upload_id when you create or update a record.

bash
POST https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/fields/:field_id/file
NameTypeDescription
data_table_idstringThe ID of the data table where the record resides. You can use the List data tables endpoint to retrieve data table IDs.
field_idstringThe ID of the file column for the file to be uploaded.
shell
curl  -X POST 'https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/fields/:field_id/file' \
	  -H 'Authorization: Bearer <api_token>' \
	  -H 'Content-Type: application/json'
json
{
  "data" : {
    "upload_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://file-storage.workato.com/sharing/files?sign=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJXb3JrYXRvRmlsZXMiLCJhdWQiOiJ3b3JrYXRvX2ZpbGVzIiwiZXhwIjoxNzUzOTUzNTUzLCJuYmYiOjE3NTM5NTI2NTMsInN1YiI6IjY5MjY1OCIsImp0aSI6IjBmMzY4N2EyLTUzNGUtNGIxMC1iODQzLTk4NmU1MWI2YTI1MCIsIm9iaiI6eyJtZXRob2QiOiJHRVQiLCJyZXNvdXJjZSI6ImY0YWE3OWU0MjlhZjNjNGRhNTcwMGU0NTYxMTY3MzM2ZjMzOTJmNzNkZDQ0ZjhjMGExMTk4MDI5MmViNzE2NjMiLCJjb25zdHJhaW50cyI6eyJmaWxlX21heF9ieXRlcyI6bnVsbCwiZmlsZV9wYXRoIjoiL1Rlc3RpbmcvMi1zdGVwLWxvZ2luLWVucm9sbG1lbnQyMDI1LTA2LTI3VDAyMzE0Ni5odG1sIiwiZmlsZV90dGwiOm51bGwsIm5hbWVzcGFjZSI6ImFkYXB0ZXIiLCJzaGFyaW5nX2FwaV9raW5kIjoicHVibGljIiwidXNlcl9pZCI6NjkyNjU4fX19.0p-NuNaQxCs_VaTaWsQGg5aS3BwCGSrHSQOVh5xb-jXQAaHAv_RSnUs6ymV9IHMVZM2P1ikodSDGtyn7pqZItw"
  }
}

Download file from the record (v1) ​

Generates a link to download the file in the file-type column of a record.

bash
GET https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/records/:record_id/fields/:field_id/file

URL parameters ​

NameTypeDescription
data_table_idstringThe ID of the data table where the record resides. You can use the List data tables endpoint to retrieve data table IDs.
record_idstringThe ID of the record linked to the file.
field_idstringThe ID of the file column of the file to be downloaded.

Sample request ​

shell
curl -X GET 'https://YOUR_DATA_CENTER/api/v1/tables/:data_table_id/fields/:field_id/file'
     -H 'Authorization: Bearer <api_token>'

Response ​

Workato returns a 303 status code with the download URL inside the LOCATION header if the request is successful.

Record import APIs ​

You can use the following endpoints to import records into a data table from a file.

The following example shows a typical import flow:

Import flow
1

Create a file upload link to request a signed URL for the file.

2

Upload the file to the returned URL, sending the raw file bytes as the body.

3

Optional. Describe the uploaded file to inspect the detected columns and record count before importing.

4

Add any missing columns to the table with the Update data table endpoint. The table must already contain the columns you map to. Importing into a table with no matching columns fails.

5

Start the import, mapping file columns to table fields.

6

Monitor the import through the records_import_status field of the Get data table by ID endpoint.

7

Dismiss the import to clear the import state, or call it earlier to cancel.

REGIONAL BASE URLS

You must use the dedicated base URL that matches your workspace region. Refer to Data center URLs for more information.

Quick reference ​

TypeResourceDescription
POST/api/v1/tables/:data_table_id/records/import/file/upload_linkCreates a link to upload a file.
POST/sharing/filesUploads the file to the signed link.
DELETE/api/v1/tables/:data_table_id/records/import/fileDeletes the uploaded file.
GET/api/v1/tables/:data_table_id/records/import/fileDescribes the uploaded file.
POST/api/v1/tables/:data_table_id/records/import/startStarts importing records from the uploaded file.
DELETE/api/v1/tables/:data_table_id/records/importDismisses or cancels the import.

Creates a signed link you use to upload a file for import.

Base URL: https://data-tables.workato.com

POST /api/v1/tables/:data_table_id/records/import/file/upload_link
NameTypeDescription
data_table_idstring
required		The ID of the data table to import records into. You can use the List data tables endpoint to retrieve data table IDs.
NameTypeDescription
file_formathash
required		The format of the file to upload.
file_format[format]string
required		The file format. Only csv is currently supported.
file_format[has_header]boolean
required		Whether the file has column labels in the first row.
file_format[delimiter]string
required		The character used to separate values in a row. Accepted values are comma, semicolon, space, tab, colon, and pipe.
file_format[quote]string
required		The character used to quote values that contain the delimiter character or newlines. Accepted values are double and single.
file_format[encoding]string
required		The text encoding name. Supported encodings are those defined in the WHATWG Encoding Standard. For example, utf-8.
shell
curl -X POST 'https://data-tables.workato.com/api/v1/tables/58408ccc-e209-491b-9873-4549b5fa48df/records/import/file/upload_link' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "file_format": {
             "format": "csv",
             "has_header": true,
             "delimiter": "comma",
             "quote": "double",
             "encoding": "utf-8"
           }
         }'

Returns 201 Created with the signed Workato Files URL you use to upload the file.

json
{
  "data": {
    "url": "https://file-storage.workato.com/sharing/files?sign=<signed_token>"
  }
}
Import already in progress

The request returns a 400 Bad Request error with the IMPORT_STATE_ERROR code in the following example because an import is already in progress for the table:

json
{
  "errors": [
    { "code": "IMPORT_STATE_ERROR", "title": "import already in progress" }
  ]
}
Table not found

The request returns a 404 Not Found error in the following example because the data table doesn't exist or is outside your scope:

json
{
  "errors": [
    { "code": "TABLE_NOT_FOUND" }
  ]
}

Upload file ​

Upload the file to the signed URL returned by Create file upload link. This endpoint doesn't require an Authorization header. The signature in the URL authorizes the request.

Base URL: https://file-storage.workato.com

POST /sharing/files

Query parameters ​

NameTypeDescription
signstring
required		The authorizing signature returned by Create file upload link.

Payload ​

Send the raw file bytes as the request body.

Sample request ​

shell
curl -X POST 'https://file-storage.workato.com/sharing/files?sign=<signed_token>' \
     -H 'Content-Type: text/csv' \
     --data-binary @data.csv

Response ​

json
{
  "file_id": "7d1ac9a4-2a6c-4951-b97a-9ab22c722500",
  "mime_type": "text/csv",
  "path": "/csv_import.4546638.c9228d13-f394-44ff-a3a2-13e04a70ea9c.csv",
  "size": 3005,
  "version_id": null
}

Delete uploaded file ​

Deletes the file that was uploaded for import. Use this to cancel before starting an import.

Base URL: https://data-tables.workato.com

DELETE /api/v1/tables/:data_table_id/records/import/file

URL parameters ​

NameTypeDescription
data_table_idstring
required		The ID of the data table from which to delete the uploaded file.

Sample request ​

shell
curl -X DELETE 'https://data-tables.workato.com/api/v1/tables/58408ccc-e209-491b-9873-4549b5fa48df/records/import/file' \
     -H 'Authorization: Bearer <api_token>'

Response ​

Returns 200 OK with an empty data object.

json
{
  "data": {}
}
No uploaded file

The request returns a 400 Bad Request error with the IMPORT_STATE_ERROR code in the following example because a file wasn't uploaded for import:

json
{
  "errors": [
    { "code": "IMPORT_STATE_ERROR", "title": "import file not found" }
  ]
}
Table not found

The request returns a 404 Not Found error in the following example because the data table doesn't exist or is outside your scope:

json
{
  "errors": [
    { "code": "TABLE_NOT_FOUND" }
  ]
}

Describe uploaded file ​

Returns the columns and record count detected in the uploaded file so you can review them before starting the import.

Base URL: https://data-tables.workato.com

GET /api/v1/tables/:data_table_id/records/import/file

URL parameters ​

NameTypeDescription
data_table_idstring
required		The ID of the data table from which to describe an uploaded file.

Sample request ​

shell
curl -X GET 'https://data-tables.workato.com/api/v1/tables/58408ccc-e209-491b-9873-4549b5fa48df/records/import/file' \
     -H 'Authorization: Bearer <api_token>'

Response ​

json
{
  "data": {
    "columns": [
      {
        "column_id": "col1",
        "label": "report_date",
        "optional": false,
        "type": "date",
        "valid_types": ["date", "string"]
      },
      {
        "column_id": "col9",
        "label": "amount",
        "optional": false,
        "type": "number",
        "valid_types": ["number", "string"]
      }
    ],
    "file_format": {
      "delimiter": "comma",
      "encoding": "utf-8",
      "format": "csv",
      "has_header": true,
      "quote": "double"
    },
    "num_records": 18
  }
}
No uploaded file

The request returns a 400 Bad Request error with the IMPORT_STATE_ERROR code in the following example because a file wasn't uploaded for import:

json
{
  "errors": [
    { "code": "IMPORT_STATE_ERROR", "title": "import file not found" }
  ]
}
Table not found

The request returns a 404 Not Found error in the following example because the data table doesn't exist or is outside your scope:

json
{
  "errors": [
    { "code": "TABLE_NOT_FOUND" }
  ]
}

Start import ​

Starts importing records from the uploaded file into the table.

PREREQUISITES

The Start import endpoint has the following prerequisites:

  • Upload a file with the Upload file endpoint.
  • Ensure all table columns exist in the target destination. Add any missing columns with the Update data table endpoint before starting the import.

Base URL: https://data-tables.workato.com

POST /api/v1/tables/:data_table_id/records/import/start

URL parameters ​

NameTypeDescription
data_table_idstring
required		The ID of the data table to import records into.

Payload ​

NameTypeDescription
filenamestring
required		The file name shown in the UI for this import.
fieldsarray
required		The mapping between file columns and table fields. Each entry maps one file column to one table field. All required table fields must be mapped, and the column and field data types must be compatible.
fields[field_id]string
conditional		The ID of the target table field. Provide either field_id or field_name.
fields[field_name]string
conditional		The name of the target table field. Provide either field_id or field_name.
fields[file_column_index]integer
conditional		The 0-based index of the source file column. Provide either file_column_index or file_column_label.
fields[file_column_label]string
conditional		The label of the source file column. You can use this only when the column label is unique in the file. Provide either file_column_index or file_column_label.
modestring
required		The import behavior. Accepted values are assert_table_empty, truncate_table, and append. Refer to Import modes for more information.
Import modes ​

The following import modes are supported:

ModeBehavior
assert_table_emptyThe import proceeds only if the table is empty. Otherwise, it returns an error.
truncate_tableAll existing records are deleted before importing. Requires the Truncate a data table permission.
appendRecords are appended to the existing records in the table.

Sample request ​

shell
curl -X POST 'https://data-tables.workato.com/api/v1/tables/58408ccc-e209-491b-9873-4549b5fa48df/records/import/start' \
     -H 'Authorization: Bearer <api_token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "filename": "data.csv",
           "fields": [
             { "field_name": "report_date", "file_column_label": "report_date" },
             { "field_name": "amount", "file_column_label": "amount" },
             { "field_name": "currency", "file_column_label": "currency" }
           ],
           "mode": "append"
         }'

Response ​

Returns 202 Accepted with an empty data object when the import is successfully initiated. Track import progress with the records_import_status field of the Get data table by ID endpoint.

json
{
  "data": {}
}
Import can't be started

The request returns a 400 Bad Request error with the IMPORT_STATE_ERROR code when the import can't start. For example, when a file wasn't uploaded, an import is already in progress, or the table isn't empty in assert_table_empty mode. The table isn't empty in the following example:

json
{
  "errors": [
    { "code": "IMPORT_STATE_ERROR", "title": "table has records" }
  ]
}
Incompatible field mapping

The request returns a 400 Bad Request error with the IMPORT_SCHEMA_ERROR code when the mapping is invalid. For example, due to an unknown column, a duplicate mapping, or an unmapped required field. A file column type doesn't match the target field type in the following example:

json
{
  "errors": [
    { "code": "IMPORT_SCHEMA_ERROR", "title": "column \"Name\" (index 0) is not compatible with the type \"date\" of table field \"date_registered\" (9a2d5844-a983-43c7-b7c0-217c570b445a)" }
  ]
}
Table not found

The request returns a 404 Not Found error in the following example because the data table doesn't exist or is outside your scope:

json
{
  "errors": [
    { "code": "TABLE_NOT_FOUND" }
  ]
}

Dismiss import ​

Dismisses the import state after an import completes, or cancels an in-progress import.

Base URL: https://data-tables.workato.com

DELETE /api/v1/tables/:data_table_id/records/import

URL parameters ​

NameTypeDescription
data_table_idstring
required		The ID of the data table from which to dismiss or cancel an import.

Sample request ​

shell
curl -X DELETE 'https://data-tables.workato.com/api/v1/tables/58408ccc-e209-491b-9873-4549b5fa48df/records/import' \
     -H 'Authorization: Bearer <api_token>'

Response ​

Returns 200 OK with an empty data object.

json
{
  "data": {}
}
No import to dismiss

The request returns a 400 Bad Request error with the IMPORT_STATE_ERROR code in the following example because no imports have started for the table:

json
{
  "errors": [
    { "code": "IMPORT_STATE_ERROR", "title": "import not started" }
  ]
}
Table not found

The request returns a 404 Not Found error in the following example because the data table doesn't exist or is outside your scope:

json
{
  "errors": [
    { "code": "TABLE_NOT_FOUND" }
  ]
}

Last updated: