---
title: "Saved imports API reference"
canonical_url: https://zentrik.ai/docs/api/imports
markdown_url: https://zentrik.ai/docs/api/imports.md
last_reviewed: 2026-10-12
---

# Saved imports API reference

Use workspace API keys to create a draft, Test it, activate its reviewed revision and run it without a signed-in session. Read, Run/Retry and management are separate grants: imports:read, imports:run and imports:manage. The key creator must still be an active writer for Run/Retry and an Owner/Admin for management. Existing Account keys do not inherit these grants. Keep a controlled first run on demand, verify its actual outcomes and preserved relationships, then decide whether to schedule it. No endpoint changes provider credentials or grants source writeback.

- Human reference: https://zentrik.ai/docs/api/imports
- Complete Markdown index: https://zentrik.ai/docs/api/index.md
- Base URL: `https://zentrik.ai/api`
- Authentication: `Authorization: Bearer YOUR_API_KEY`
- Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions

## GET /external/v1/imports/capabilities — Read provider import capabilities

Operation ID: `get-import-capabilities`

Read the supported providers, destinations and import options before configuring a definition. This read does not call a provider or start an import.

Required API key scopes: `imports:read`

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Saved configuration, capabilities or requested receipt data. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

---

## GET /external/v1/imports — List saved imports

Operation ID: `list-saved-imports`

Return the saved-import definitions in the key’s workspace as an array. Optionally select one connection. This list does not include legacy connection-managed operations or execute providers.

Required API key scopes: `imports:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `integrationId` | UUID | No | Limit the list to this connected integration. |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Saved configuration, capabilities or requested receipt data. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

### Example response

```json
[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "displayName": "Reviewed Account refresh",
    "rowVersion": 1,
    "scheduleType": "manual",
    "configuration": {
      "state": "draft"
    }
  }
]
```

---

## GET /external/v1/imports/:id — Read a saved import

Operation ID: `get-saved-import`

Read the saved draft, active revision, rowVersion, cursor and run policy. Inspect the actual normalized definition before Test. Later mapping-profile edits do not silently change its tested revision.

Required API key scopes: `imports:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Saved configuration, capabilities or requested receipt data. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

---

## POST /external/v1/imports — Create an import draft

Operation ID: `create-saved-import`

Create a manual saved-import draft for an existing connection. The definition follows that provider’s capability contract. Replace the illustrative IDs below with IDs from your workspace. A draft is not an active import or a successful import result.

Required API key scopes: `imports:manage`

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `integrationId` | UUID | Yes | Existing connection in the key’s workspace. |
| `name` | string | Yes | Import name, 1–160 characters after trimming. |
| `definition` | object | Yes | Provider-specific import settings; the shared service validates and normalizes them. |
| `sourceReview` | object \| null | No | Optional reviewed source count: {exactCount: nonnegative integer}. |

### Example request

```json
{
  "integrationId": "33333333-3333-4333-8333-333333333333",
  "name": "Reviewed Account refresh",
  "definition": {
    "object": "Account",
    "mappingProfileId": "44444444-4444-4444-8444-444444444444",
    "fieldMappings": {
      "name": "Name"
    },
    "overwritePolicy": "fill_blank",
    "linkedAccountsOnly": true,
    "createMissingAccounts": false,
    "maxRows": 10,
    "pageSize": 10,
    "syncDeals": false,
    "syncContacts": false,
    "revenueStrategy": "none",
    "snapshotProperties": []
  }
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Success | Created configuration or accepted action/run receipt; inspect its state before reporting completion. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

---

## PATCH /external/v1/imports/:id — Edit an import draft

Operation ID: `edit-saved-import`

Save a new draft without changing the active revision or schedule. Supply the rowVersion just read; a stale version returns 409. Test the changed draft again before activation.

Required API key scopes: `imports:manage`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `definition` | object | Yes | Complete provider-specific draft definition, not a partial field patch. |
| `expectedRowVersion` | integer | Yes | Positive rowVersion from the latest saved-import read. |
| `name` | string | No | Replacement name, 1–160 characters after trimming. |
| `sourceReview` | object \| null | No | Optional {exactCount: nonnegative integer}. |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Saved configuration, capabilities or requested receipt data. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

---

## POST /external/v1/imports/:id/test — Test the exact draft

Operation ID: `test-saved-import`

Queue a bounded test of the current draft and return its durable run ID. Use an empty JSON body. Poll the receipt until succeeded; queued is not completion. The test uses its own first-run boundary, not the active import’s cursor. A Salesforce Account Test does not execute the context follow-up that a real Run performs.

Required API key scopes: `imports:manage`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |

### Example request

```json
{}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Success | Created configuration or accepted action/run receipt; inspect its state before reporting completion. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

### Example response

```json
{
  "id": "22222222-2222-4222-8222-222222222222",
  "operationId": "11111111-1111-4111-8111-111111111111",
  "status": "queued"
}
```

---

## POST /external/v1/imports/:id/activate — Activate a tested draft

Operation ID: `activate-saved-import`

Activate only a successful Test for this exact current draft. The first activation requires an explicit on_demand, daily or weekly decision. Existing active imports retain their policy: omit runPolicy when activating a new revision and change scheduling through the schedule endpoint. Entitlements, connection ownership and staff-managed cadence remain enforced.

Required API key scopes: `imports:manage`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `testRunId` | UUID | Yes | Successful Test run matching the current draft fingerprint and revision. |
| `runPolicy` | enum | No | Required for first activation: on_demand, daily or weekly. Omit for a later revision to retain its existing policy; change scheduling separately. |
| `timezone` | string | No | Named time zone, at most 100 characters; validated by the shared schedule service. |

### Example request

```json
{
  "testRunId": "22222222-2222-4222-8222-222222222222",
  "runPolicy": "on_demand",
  "timezone": "America/Los_Angeles"
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Success | Created configuration or accepted action/run receipt; inspect its state before reporting completion. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

---

## POST /external/v1/imports/:id/runs — Run an active import

Operation ID: `run-saved-import`

Queue one run of the active tested revision and return a run ID. Use {} for ordinary imports. Completion, not queue acceptance, establishes the outcome. Another Run advances the saved cursor; it is not a replay. Resolve a lost POST response from history before sending another request.

Required API key scopes: `imports:run`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `researchWindow` | enum | No | Web research only: full_lookback or incremental. Other providers reject this option. |

### Example request

```json
{}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Success | Created configuration or accepted action/run receipt; inspect its state before reporting completion. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

### Example response

```json
{
  "id": "22222222-2222-4222-8222-222222222222",
  "operationId": "11111111-1111-4111-8111-111111111111",
  "status": "queued"
}
```

---

## GET /external/v1/imports/:id/runs — List import runs

Operation ID: `list-saved-import-runs`

Read a keyset page of this import’s Test and execution receipts as {items, nextCursor}. Reads never start provider work. Back off polling when the result does not change.

Required API key scopes: `imports:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |
| `limit` | integer | No | Page size, 1–100. Default 25. |
| `cursor` | string | No | Previous nextCursor, at most 1,024 characters. Continue until nextCursor is null. |
| `status` | enum | No | queued, running, succeeded, partial, failed or canceled. |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Saved configuration, capabilities or requested receipt data. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

### Example response

```json
{
  "items": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "operationId": "11111111-1111-4111-8111-111111111111",
      "status": "queued"
    }
  ],
  "nextCursor": null
}
```

---

## GET /external/v1/imports/:id/runs/:runId — Read a run receipt

Operation ID: `get-saved-import-run`

Read the exact run’s state, counts, saved scope, starting/ending cursor and failure information. The run must belong to both this import and the key’s workspace. succeeded, partial, failed and canceled are terminal; partial is not a full success.

Required API key scopes: `imports:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |
| `runId` | UUID | Yes | Run ID belonging to this saved import (path). |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Saved configuration, capabilities or requested receipt data. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

### Example response

```json
{
  "id": "22222222-2222-4222-8222-222222222222",
  "operationId": "11111111-1111-4111-8111-111111111111",
  "status": "succeeded",
  "examinedCount": 10,
  "createdCount": 0,
  "updatedCount": 10,
  "failedCount": 0
}
```

---

## GET /external/v1/imports/:id/runs/:runId/items — Read item outcomes

Operation ID: `list-saved-import-run-items`

Read bounded per-record outcomes and destination identities as {items, nextCursor}. Use these with the run totals to verify coverage and identify rows that need review. The run must belong to this saved import.

Required API key scopes: `imports:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |
| `runId` | UUID | Yes | Run ID belonging to this saved import (path). |
| `limit` | integer | No | Page size, 1–100. Default 25. |
| `cursor` | string | No | Previous nextCursor, at most 1,024 characters. Continue until nextCursor is null. |
| `status` | enum | No | created, updated, unchanged, skipped or failed. |

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Saved configuration, capabilities or requested receipt data. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

### Example response

```json
{
  "items": [],
  "nextCursor": null
}
```

---

## POST /external/v1/imports/:id/runs/:runId/retry — Retry a failed or partial run

Operation ID: `retry-saved-import-run`

Retry only a failed or partial run. Use {}. The new run links to the original receipt and reuses its saved scope and starting cursor, not the latest draft or a new date window. Do not use Retry to replay a succeeded run.

Required API key scopes: `imports:run`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |
| `runId` | UUID | Yes | Run ID belonging to this saved import (path). |

### Example request

```json
{}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Success | Created configuration or accepted action/run receipt; inspect its state before reporting completion. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

### Example response

```json
{
  "id": "22222222-2222-4222-8222-222222222222",
  "operationId": "11111111-1111-4111-8111-111111111111",
  "status": "queued",
  "retryOfRunId": "55555555-5555-4555-8555-555555555555"
}
```

---

## POST /external/v1/imports/:id/pause — Pause an import

Operation ID: `pause-saved-import`

Pause future execution of an active import. Use {}. Preserve the tested revision, records, receipts and saved cadence; this is not a delete or cancellation of an already running job.

Required API key scopes: `imports:manage`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |

### Example request

```json
{}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Success | Created configuration or accepted action/run receipt; inspect its state before reporting completion. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

---

## POST /external/v1/imports/:id/resume — Resume a paused import

Operation ID: `resume-saved-import`

Resume a paused import with an active tested revision. Use {}. Restore its saved cadence at the next permitted window; provider support, current plan entitlement and completed-history restrictions still apply.

Required API key scopes: `imports:manage`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |

### Example request

```json
{}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Success | Created configuration or accepted action/run receipt; inspect its state before reporting completion. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |

---

## PATCH /external/v1/imports/:id/schedule — Change the run policy

Operation ID: `schedule-saved-import`

Set on-demand execution with enabled=false, or enable the daily/weekly customer preset for an active tested import. This does not alter mappings or reset the cursor. Workspace entitlements and staff-owned schedules remain enforced. Arbitrary intervals, next-run overrides and actor overrides are rejected.

Required API key scopes: `imports:manage`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Saved import ID from the list or create response (path). |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | Yes | false selects on demand; true enables a permitted recurring policy. |
| `preset` | enum | No | daily or weekly. If omitted on enable, the service uses the existing policy or its daily default. |
| `timezone` | string | No | Named time zone, at most 100 characters. |

### Example request

```json
{
  "enabled": false
}
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Saved configuration, capabilities or requested receipt data. | — |
| 400 | Invalid request | Malformed identity, invalid option or unsupported request field. | — |
| 401 | Authentication required | Missing, expired, disabled or invalid API key. | — |
| 403 | Access required | Missing scope or the key creator no longer has the required active workspace role. | — |
| 404 | Not found | The connection, saved import or run is not available in this workspace/import scope. | — |
| 409 | Review required | Stale draft/Test, execution conflict, ownership conflict, plan limit or protected schedule. | — |
| 429 | Rate limit | Wait for Retry-After and use bounded backoff for reads; reconcile uncertain writes before retrying. | — |