Run imports and exports through the API

Start a saved import template with a CSV file URL or run an export template through the API, then check the run's status and download the file.

  • Verified Nov 17, 2026
  • Classic builder
  • Available on: Business Pro, Business Elite

On this page
  1. Before you start
  2. Imports
  3. Start an import
  4. Check an import
  5. Exports
  6. Run an export and download the file
  7. Common problems

Run the import and export templates you saved in the builder from your own code: send a CSV file to an import template, or start an export template and download the file when it is ready.

Before you start #

  • Imports and exports through the API are on the Business Pro and Business Elite plans.
  • On the API key in Settings > API Keys, turn on Allow Import, Allow Export or both. Without the switch, calls answer 412 with "The method being used is disabled for this API key."
  • Create the template first in the builder. The API runs templates; it does not create them. See Import templates and Export templates.
  • These endpoints are only on version 1.1 of the API: every URL starts with https://api.tadabase.io/api/v1.1/{appId}/.
The API key form in Settings with the Allow Export and Allow Import switches highlighted

Imports #

Method and pathWhat it does
GET importsLists import templates: id, name, data_table_id, created_at, updated_at. Optional dataTableId, page and limit (default 10)
GET imports/{templateId}One import template
POST imports/{templateId}/triggerStarts an import with the template
POST imports/{templateId}/trigger/{recordId}Starts an import and connects the imported records to that record, when the template's connection setting uses the record the import is run from
GET imports/status/{queueId}The progress of one import run
GET imports/queues/{queueId}The full details of one import run
GET imports/queuesLists import runs. Optional data_table_id, status, page and limit (default 10)

Start an import #

The file must be a CSV file at a URL the server can download. The template decides which columns go into which fields.

Shell
curl -X POST https://api.tadabase.io/api/v1.1/YOUR_APP_ID/imports/TEMPLATE_ID/trigger \
  -H "X-Tadabase-App-Id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET" \
  -d "file_url=https://example.com/customers.csv"
ParameterRequiredWhat it does
file_urlYesThe URL of the CSV file. Missing it answers 422 "The file URL is required"
delimiterNoThe column separator. Default ,
csv_headerNoWhich row holds the column names. Default row_1
match_fieldNoTo update existing records instead of adding new ones: the slug of the field to match on, such as field_34
match_field_to_fieldNoThe CSV column to compare with match_field
match_field_caseNo1 (default) matches without regard to case, 0 is case sensitive
JSON
{
  "status": "success",
  "queue_id": "kN8Q3wPrJ1",
  "msg": "Import has been started."
}

The import runs in the background. Keep the queue_id to check on it.

Check an import #

Call GET imports/status/{queueId}:

JSON
{
  "type": "success",
  "item": {
    "status": "Running",
    "complete": 40,
    "start_at": "2026-11-17 09:15:02",
    "end_at": null,
    "progress": { "records": 250, "completed": 100, "success": 98, "failure": 2 }
  }
}

status is To Be Run while the import waits, Running while it works, then Complete or Error. progress counts the rows read, the rows done, and how many succeeded and failed. Poll every few seconds rather than in a tight loop.

Exports #

Method and pathWhat it does
GET exports/templatesLists export templates: id, dataTableId, name (100 per page, ?page=2 for the next)
GET exports/templates/{templateId}One export template
POST exports/templates/{templateId}/triggerStarts an export with the template
POST exports/templates/{templateId}/trigger/{recordId}Starts an export limited to the records connected to that record, when the template is set to include only connected records
GET exports/queues/{queueId}The status and complete of one export run
GET exports/{exportId}One export file, with a download link once it is ready
GET exportsLists export files (50 per page) with their table and template
GET exports/queuesLists every export run with its status and complete

Run an export and download the file #

  1. Start the export Call POST exports/templates/{templateId}/trigger. The answer has status: success and a queue_id. If the same template is already waiting or running, you get its queue_id and the message "Already in Queue." instead of a new run.
  2. Wait for it to finish Call GET exports/queues/{queueId} until status is Complete. It is Queue while waiting and Running while it works; Error means it failed.
  3. Get the file Call GET exports/{queueId} (the run and the file share an ID). Once the file exists, fileSignedUrl holds a download link that works for 10 minutes. Download it right away, or call the endpoint again for a fresh link.
JSON
{
  "status": "success",
  "item": {
    "id": "kN8Q3wPrJ1",
    "status": "Complete",
    "complete": 100,
    "fileUrl": "...",
    "fileSignedUrl": "https://..."
  }
}

Exports through the API produce CSV files.

Common problems #

ResponseCause
412 with a plan messageYour plan does not include imports or exports through the API, or the template is over your plan's template count
412 "The method being used is disabled for this API key."Allow Import or Allow Export is off on the key
Import answers status: error "Failed to retrieve the csv file."The server could not download file_url. Check that the URL is public and returns the CSV itself
"The export template was not found."The template ID is wrong
"Already in Queue."That export template is already waiting or running; use the queue_id in the answer

Was this page helpful?

Something wrong or missing on this page? Tell us.