# 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.

Source: https://tadabase.com/docs/developers/imports-and-exports-api  
Status: Verified Nov 17, 2026. Checked against the current product

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](https://tadabase.com/docs/data/import-templates) and [Export templates](https://tadabase.com/docs/data/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](https://tadabase.com/docs-shots/developers-api-key-allow-import-export.webp)

## Imports

| Method and path | What it does |
| --- | --- |
| `GET imports` | Lists 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}/trigger` | Starts 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/queues` | Lists 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.

```bash
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"
```

| Parameter | Required | What it does |
| --- | --- | --- |
| `file_url` | Yes | The URL of the CSV file. Missing it answers `422` "The file URL is required" |
| `delimiter` | No | The column separator. Default `,` |
| `csv_header` | No | Which row holds the column names. Default `row_1` |
| `match_field` | No | To update existing records instead of adding new ones: the slug of the field to match on, such as `field_34` |
| `match_field_to_field` | No | The CSV column to compare with `match_field` |
| `match_field_case` | No | `1` (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 path | What it does |
| --- | --- |
| `GET exports/templates` | Lists export templates: `id`, `dataTableId`, `name` (100 per page, `?page=2` for the next) |
| `GET exports/templates/{templateId}` | One export template |
| `POST exports/templates/{templateId}/trigger` | Starts 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 exports` | Lists export files (50 per page) with their table and template |
| `GET exports/queues` | Lists 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

| Response | Cause |
| --- | --- |
| `412` with a plan message | Your 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 |

> **Note:** These responses report success in a `status` property (`success` or `error`), except `imports/status/{queueId}`, which uses `type`.
