Saved imports

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.

15 endpoints

GET

Read provider import capabilities

GET /external/v1/imports/capabilities

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

Requirements

API scopes required:

imports:read

Responses

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

List saved imports

GET /external/v1/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.

Requirements

API scopes required:

imports:read

Request

Parameters

Name	Type	Description
integrationId	UUID	Limit the list to this connected integration.

Responses

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

200 OK

json

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

GET

Read a saved import

GET /external/v1/imports/:id

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.

Requirements

API scopes required:

imports:read

Request

Parameters

Name	Type	Description
id *	UUID	Saved import ID from the list or create response (path).

Responses

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

Create an import draft

POST /external/v1/imports

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.

Requirements

API scopes required:

imports:manage

Request

Request body (application/json)

integrationIdUUID

Required

Existing connection in the key’s workspace.

namestring

Required

Import name, 1–160 characters after trimming.

definitionobject

Required

Provider-specific import settings; the shared service validates and normalizes them.

sourceReviewobject | null

Optional reviewed source count: {exactCount: nonnegative integer}.

Responses

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 Request

POST

/external/v1/imports

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": []
  }
}

PATCH

Edit an import draft

PATCH /external/v1/imports/:id

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.

Requirements

API scopes required:

imports:manage

Request

Parameters

Name	Type	Description
id *	UUID	Saved import ID from the list or create response (path).

Request body (application/json)

definitionobject

Required

Complete provider-specific draft definition, not a partial field patch.

expectedRowVersioninteger

Required

Positive rowVersion from the latest saved-import read.

namestring

Replacement name, 1–160 characters after trimming.

sourceReviewobject | null

Optional {exactCount: nonnegative integer}.

Responses

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

Test the exact draft

POST /external/v1/imports/:id/test

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.

Requirements

API scopes required:

imports:manage

Request

Parameters

Name	Type	Description
id *	UUID	Saved import ID from the list or create response (path).

Responses

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 Request

POST

/external/v1/imports/:id/test

json

{}

Example Response

201 Created

json

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

POST

Activate a tested draft

POST /external/v1/imports/:id/activate

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.

Requirements

API scopes required:

imports:manage

Request

Parameters

Name	Type	Description
id *	UUID	Saved import ID from the list or create response (path).

Request body (application/json)

testRunIdUUID

Required

Successful Test run matching the current draft fingerprint and revision.

runPolicyenum

Required for first activation: on_demand, daily or weekly. Omit for a later revision to retain its existing policy; change scheduling separately.

timezonestring

Named time zone, at most 100 characters; validated by the shared schedule service.

Responses

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 Request

POST

/external/v1/imports/:id/activate

json

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

POST

Run an active import

POST /external/v1/imports/:id/runs

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.

Requirements

API scopes required:

imports:run

Request

Parameters

Name	Type	Description
id *	UUID	Saved import ID from the list or create response (path).

Request body (application/json)

researchWindowenum

Web research only: full_lookback or incremental. Other providers reject this option.

Responses

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 Request

POST

/external/v1/imports/:id/runs

json

{}

Example Response

201 Created

json

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

GET

List import runs

GET /external/v1/imports/:id/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.

Requirements

API scopes required:

imports:read

Request

Parameters

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

Responses

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

200 OK

json

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

GET

Read a run receipt

GET /external/v1/imports/:id/runs/:runId

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.

Requirements

API scopes required:

imports:read

Request

Parameters

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

Responses

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

200 OK

json

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

GET

Read item outcomes

GET /external/v1/imports/:id/runs/:runId/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.

Requirements

API scopes required:

imports:read

Request

Parameters

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

Responses

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

200 OK

json

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

POST

Retry a failed or partial run

POST /external/v1/imports/:id/runs/:runId/retry

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.

Requirements

API scopes required:

imports:run

Request

Parameters

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

Responses

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 Request

POST

/external/v1/imports/:id/runs/:runId/retry

json

{}

Example Response

201 Created

json

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

POST

Pause an import

POST /external/v1/imports/:id/pause

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.

Requirements

API scopes required:

imports:manage

Request

Parameters

Name	Type	Description
id *	UUID	Saved import ID from the list or create response (path).

Responses

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 Request

POST

/external/v1/imports/:id/pause

json

{}

POST

Resume a paused import

POST /external/v1/imports/:id/resume

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.

Requirements

API scopes required:

imports:manage

Request

Parameters

Name	Type	Description
id *	UUID	Saved import ID from the list or create response (path).

Responses

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 Request

POST

/external/v1/imports/:id/resume

json

{}

PATCH

Change the run policy

PATCH /external/v1/imports/:id/schedule

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.

Requirements

API scopes required:

imports:manage

Request

Parameters

Name	Type	Description
id *	UUID	Saved import ID from the list or create response (path).

Request body (application/json)

enabledboolean

Required

false selects on demand; true enables a permitted recurring policy.

presetenum

daily or weekly. If omitted on enable, the service uses the existing policy or its daily default.

timezonestring

Named time zone, at most 100 characters.

Responses

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 Request

PATCH

/external/v1/imports/:id/schedule

json

{
  "enabled": false
}