Start SmartConnector Flow API

Audience: Developers, Integrators

Purpose: Documents the endpoint used to trigger a SmartConnector run programmatically, including how to upload an input file, specify dry run vs. live run mode, and monitor the resulting execution.

Overview

Use the Start SmartConnector Flow API to trigger a SmartConnector run programmatically. This is the primary programmatic entry point for SmartConnector execution. It accepts an input file, initiates either a dry run or a live run against the specified SmartConnector, and returns an execution ID you can use to monitor progress while the run processes in the background.

Why Use This API?

You can use the Start SmartConnector Flow API when you need to:

• Trigger a SmartConnector run as part of an automated workflow, for example when a file lands in a storage bucket, a CI/CD job completes, or an external system generates a new data export
• Replace a manual file upload workflow with a programmatic one for recurring imports that follow a predictable schedule or are triggered by external events
• Run a dry run programmatically to validate data before committing a live run. Use the is_dry_run flag to process the file and produce full output without writing any Records to Kizen

Start SmartConnector Flow API Behavior

Note: Live runs require an active SmartConnector. Dry runs are permitted regardless of status. Unlike Webhook SmartConnectors, which queue incoming executions while inactive, all other SmartConnector types do not queue runs while inactive. A run submitted against an inactive non-webhook SmartConnector will return an error rather than waiting to process.

Behavior	Detail
Accepted File Types	CSV and Excel files. XLSX is recommended. Most Excel file types are accepted
Run Mode	Controlled by the is_dry_run flag in the request body. Set to true for a dry run, false for a live run
Execution Model	Returns immediately with an execution ID. The run processes asynchronously in the background
Diff Checking	Enabled by default. Pass disable_diff_check: true to force a full re-ingestion
SQL Parameters	Pass runtime parameter values via the sql_parameters Object for connectors that use parameterized SQL
Trigger Type	Use trigger_type to identify how the run was initiated. Use the value that matches your SmartConnector type: fileupload, webhook, activity, schedule, or bulkaction

Error Conditions

The following conditions return an error response:

• Attempting a live run on an inactive SmartConnector
• Attempting to run a SmartConnector that has not been fully configured. The API returns a specific error identifying which configuration step is incomplete
• Invalid file format
• Insufficient permissions to run the SmartConnector

---

Input File

Triggering a SmartConnector run programmatically does not require uploading an input file beforehand. If no file is passed, the run defaults to the SmartConnector's sample file. To run against a new file, first upload it to Kizen's file storage and pass the returned file reference as source_file_id in the request body.

For the full upload workflow and code examples, see Upload Files for SmartConnector Runs.

---

Start SmartConnector Flow Endpoints

Want to try the API out? Visit our Swagger docs.

post

Start the smart connector flow. For bulk action connectors, pass entity_records_set_key from a bulk action summary to run on selected records.

Authorizations

X-API-KEYstringRequired

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

Path parameters

connector_identifierstringRequired

Query parameters

orderingstring · enumOptional

Which field to use when ordering the results. Prepend with '-' for descending order.

Possible values:

Body

source_file_idstring · uuid · nullableWrite-onlyOptional

UUID of the uploaded input file (S3 object) to run the connector against. Upload a CSV or XLSX file via the presigned upload flow with source=smart_connector_import and pass the returned s3object_id here. If omitted, the connector's reference input file is used.

reprocess_execution_idstring · uuid · nullableWrite-onlyOptional

UUID of a previous execution to reprocess. When provided, the connector reruns using that execution's input file and metadata, and source_file_id is ignored.

is_dry_runbooleanOptional

When true, validates the input file without committing changes (dry run). When false, performs a live run that writes records.

Default: false

disable_diff_checkbooleanOptional

When true, skips the connector's diff-check validation.

Default: false

trigger_typestring · enumOptional

• fileupload - File Upload
• webhook - Webhook
• activity - Activity
• schedule - Schedule
• bulkaction - Bulk Action

Possible values:

sql_parametersanyOptional

Parameters passed to the connector's SQL script, merged over the connector's configured defaults.

entity_records_set_keystring · min: 1 · nullableOptional

Cache key from bulk action summary containing selected record IDs. Only for bulk action connectors.

Responses

200Success

application/json

is_dry_runbooleanOptional

When true, validates the input file without committing changes (dry run). When false, performs a live run that writes records.

Default: false

disable_diff_checkbooleanOptional

When true, skips the connector's diff-check validation.

Default: false

trigger_typestring · enumOptional

• fileupload - File Upload
• webhook - Webhook
• activity - Activity
• schedule - Schedule
• bulkaction - Bulk Action

Possible values:

sql_parametersanyOptional

Parameters passed to the connector's SQL script, merged over the connector's configured defaults.

entity_records_set_keystring · nullableOptional

Cache key from bulk action summary containing selected record IDs. Only for bulk action connectors.

execution_idstring · uuidRead-onlyRequired

ID of the created execution. Use it to monitor progress via the Execution Status API or to cancel the run via the Cancel Execution API.

post/api/smart-connectors/{connector_identifier}/start-connector-flow

POST /api/smart-connectors/{connector_identifier}/start-connector-flow HTTP/1.1
X-API-KEY: YOUR_API_KEY
X-BUSINESS-ID: YOUR_BUSINESS_ID
X-USER-ID: YOUR_USER_ID
Content-Type: application/json
Accept: */*
Content-Length: 249

{
  "source_file_id": "123e4567-e89b-12d3-a456-426614174000",
  "reprocess_execution_id": "123e4567-e89b-12d3-a456-426614174000",
  "is_dry_run": false,
  "disable_diff_check": false,
  "trigger_type": "fileupload",
  "sql_parameters": null,
  "entity_records_set_key": "text"
}

200Success

{
  "is_dry_run": false,
  "disable_diff_check": false,
  "trigger_type": "fileupload",
  "sql_parameters": null,
  "entity_records_set_key": "text",
  "execution_id": "123e4567-e89b-12d3-a456-426614174000"
}

Start SmartConnector Schemas

---

What's Next?

Continue with the SmartConnector Webhook Trigger API to learn how to trigger a Webhook SmartConnector by delivering inbound webhook payloads to its endpoint, the equivalent entry point for webhook-triggered connectors.

Related Topics

• SmartConnector APIs
• Running a SmartConnector
• Building with SmartConnectors (Topic Coming Soon)