canonical: https://jentic.com/apis/dataimporter.io/dataimporter

# DataImporter API

DataImporter is a data import platform that connects external sources (CSV files, FTP feeds, SaaS APIs) to a destination system using configurable field mappings and import jobs. The REST API exposes three core resources - connections, mappings, and imports - letting integrators automate the lifecycle of a data pipeline: register a source, define how its fields map to the destination schema, then trigger and monitor import runs. Bearer token auth keeps the surface simple to integrate.

## For AI agents

Create data source connections, define field mappings, and trigger or cancel import jobs across the DataImporter pipeline platform.

## Scope

Does not handle data scraping, BI dashboarding, or transformation logic beyond field mapping - use for source-to-destination import pipelines only.

## Capabilities

- Register a new data source connection via POST /connections
- List, update, or delete configured connections to manage the pipeline inventory
- Define field mappings between source columns and destination fields via POST /mappings
- Trigger an import run with a specific connection and mapping via POST /imports
- Monitor import job status with GET `/imports/{importId}`
- Cancel a long-running import via POST `/imports/{importId}/cancel`

## Use cases

### Automated Customer Data Onboarding

SaaS platforms onboarding new customers from legacy systems use DataImporter to programmatically register the customer's data source, attach a saved field mapping, and run an initial import - all without exposing the customer to the underlying ETL tooling. POST /connections registers the source, POST /mappings binds source columns to destination fields, and POST /imports kicks off the run. Engineering teams typically wire this into their onboarding flow in a couple of days.

Example prompt: Create a connection for an SFTP source, attach mapping ID 42, and trigger an import; poll GET `/imports/{importId}` until completion

### Recurring Data Sync Orchestration

Data ops teams trigger nightly or hourly imports through the API rather than the platform UI, integrating DataImporter into their orchestration layer (Airflow, Prefect, Dagster). POST /imports starts the job, GET `/imports/{importId}` streams status, and POST `/imports/{importId}/cancel` aborts a run that exceeds a time budget. The pattern keeps DataImporter as the execution engine while orchestration logic lives in the team's existing scheduler.

Example prompt: Trigger a nightly import for connection ID 'salesforce-prod', wait for completion, and report row counts

### Mapping Lifecycle Management

When a destination schema evolves, ops teams use the mapping endpoints to rotate field assignments without losing connection metadata. PUT `/mappings/{mappingId}` updates the field map, DELETE `/mappings/{mappingId}` removes a deprecated one, and GET /mappings lists everything currently in play. This avoids redoing connection configuration each time the target schema changes.

Example prompt: Update mapping 42 to add a new destination field 'lifecycle_stage' bound to source column 'stage', then re-run the linked import

### AI Agent Pipeline Operations

Operations agents monitor import health by calling DataImporter through Jentic: searching for stuck imports, cancelling runaway jobs, or restarting failed runs with adjusted mappings. Jentic isolates the bearer token in its vault, so the agent only handles connection IDs and mapping IDs.

Example prompt: List imports from the last 24 hours, identify any in 'running' state for over 60 minutes, and cancel them via POST `/imports/{importId}/cancel`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/connections` | Register a new data source connection |
| GET | `/connections` | List configured connections |
| POST | `/mappings` | Create a source-to-destination field mapping |
| PUT | `/mappings/{mappingId}` | Update an existing mapping |
| POST | `/imports` | Trigger a new import job run |
| GET | `/imports/{importId}` | Get the status of an import job |
| POST | `/imports/{importId}/cancel` | Cancel a running import |

## Key resources

- **Connections** — CRUD operations on data source connection definitions
- **Mappings** — CRUD operations on source-to-destination field mapping configurations
- **Imports** — Trigger, monitor, and cancel import job runs

## Why Jentic

- **Setup:** Wiring DataImporter by hand means learning its bearer auth against api.dataimporter.io/v1 and building the connection, mapping, and retry plumbing for import pipelines yourself. Through Jentic you install once, import the DataImporter API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** DataImporter puts the import job id in the URL path (`/imports/{importId}`), so a rule can pin your agent to reading and cancelling specific import jobs. You choose the operations it may call, so creating connections or mappings is not included unless you add those operations.
- **Credential handling:** Your DataImporter bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'trigger a data import' or 'cancel an import job', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Airtable API** — Airtable is a common destination for DataImporter pipelines that need a structured, queryable target.
- **Supabase API** — Supabase Postgres is another common destination for DataImporter feeds.
- **Apify** — Apify covers data collection from the web; DataImporter focuses on routing pre-existing data into destinations.

## FAQ

### What authentication does the DataImporter API use?

DataImporter uses HTTP bearer token authentication on every endpoint. Through Jentic, that bearer token is stored encrypted in your Jentic One instance and injected at call time, so the agent only ever handles connection and import IDs.

### Can I trigger an import job with the DataImporter API?

Yes. POST /imports starts a new import using a previously configured connection and mapping; the response returns an importId you can poll via GET `/imports/{importId}` or stop with POST `/imports/{importId}/cancel.`

### What are the rate limits for the DataImporter API?

Rate limits are not declared in the OpenAPI spec; check the DataImporter dashboard or contact support for plan-specific concurrency and monthly run quotas before scheduling tight loops.

### How do I create a new source connection through Jentic?

Search Jentic for 'create a data import connection', load the POST /connections operation, and execute it with your source configuration. Jentic injects the bearer token automatically and returns the new connectionId.

### Can I cancel a stuck import job via the API?

Yes. POST `/imports/{importId}/cancel` stops an in-flight import and is the right call when an upstream source hangs or the run exceeds its time budget.

### Does the DataImporter API expose mapping CRUD?

Yes. Full lifecycle is covered: GET /mappings lists configurations, POST /mappings creates one, PUT `/mappings/{mappingId}` updates, and DELETE `/mappings/{mappingId}` removes it. Mappings can be reused across multiple connections.

### Can I limit what my agent is allowed to do with the DataImporter API?

Yes. Because you run Jentic One yourself, your own rules decide which DataImporter operations and credentials the agent may use. Since DataImporter puts the job id in the URL path at `/imports/{importId}`, you can pin the agent to reading status with GET `/imports/{importId}` and stopping runs with POST `/imports/{importId}/cancel` while withholding creating connections or mappings. Those write operations are only available to the agent if you explicitly add them to its allowed set.