space.vars.smartconnector Flow API to trigger a space.vars.smartconnector run programmatically. This is the primary programmatic entry point for space.vars.smartconnector execution. It accepts an input file, initiates either a dry run or a live run against the specified space.vars.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 space.vars.smartconnector Flow API when you need to:
* Trigger a space.vars.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 space.vars.entities to space.vars.Kizen\_company\_name
### Start SmartConnector Flow API Behavior
{% hint style="info" %}
**Note:** Live runs require an active space.vars.smartconnector. Dry runs are permitted regardless of status. Unlike Webhook space.vars.smartconnectors, which queue incoming executions while inactive, all other space.vars.smartconnector types do not queue runs while inactive. A run submitted against an inactive non-webhook space.vars.smartconnector will return an error rather than waiting to process.
{% endhint %}
| 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 space.vars.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 space.vars.smartconnector type: fileupload, webhook, activity, schedule, or bulkaction |
space.vars.smartconnector
* Attempting to run a space.vars.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 space.vars.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](/docs/concepts/smartconnectors/smartconnector-apis/upload-files-for-smartconnector-runs.md).
***
## Start SmartConnector Flow Endpoints
Want to try the API out? Visit our [Swagger](https://app.go.kizen.com/api/docs/public/swagger#/smart-connectors/smart_connectors_start_connector_flow_create) docs.
## POST /api/smart-connectors/{connector\_identifier}/start-connector-flow
> Start the smart connector flow. For bulk action connectors, pass entity\_records\_set\_key from a bulk action summary to run on selected records.
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"security":[{"businessId":[],"userId":[],"apiKey":[]}],"components":{"securitySchemes":{"businessId":{"type":"apiKey","in":"header","name":"X-BUSINESS-ID"}},"schemas":{"SmartConnectorFlowStartRunRequest":{"type":"object","properties":{"source_file_id":{"type":"string","format":"uuid","writeOnly":true,"nullable":true,"description":"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_id":{"type":"string","format":"uuid","writeOnly":true,"nullable":true,"description":"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_run":{"type":"boolean","default":false,"description":"When true, validates the input file without committing changes (dry run). When false, performs a live run that writes records."},"disable_diff_check":{"type":"boolean","default":false,"description":"When true, skips the connector's diff-check validation."},"trigger_type":{"allOf":[{"$ref":"#/components/schemas/TriggerTypeEnum"}],"default":"fileupload","description":"How the run was triggered. Defaults to fileupload for programmatic file-based runs.\n\n* `fileupload` - File Upload\n* `webhook` - Webhook\n* `activity` - Activity\n* `schedule` - Schedule\n* `bulkaction` - Bulk Action"},"sql_parameters":{"description":"Parameters passed to the connector's SQL script, merged over the connector's configured defaults."},"entity_records_set_key":{"type":"string","nullable":true,"minLength":1,"description":"Cache key from bulk action summary containing selected record IDs. Only for bulk action connectors."}}},"TriggerTypeEnum":{"enum":["fileupload","webhook","activity","schedule","bulkaction"],"type":"string","description":"* `fileupload` - File Upload\n* `webhook` - Webhook\n* `activity` - Activity\n* `schedule` - Schedule\n* `bulkaction` - Bulk Action"},"SmartConnectorFlowStartRun":{"type":"object","properties":{"is_dry_run":{"type":"boolean","default":false,"description":"When true, validates the input file without committing changes (dry run). When false, performs a live run that writes records."},"disable_diff_check":{"type":"boolean","default":false,"description":"When true, skips the connector's diff-check validation."},"trigger_type":{"allOf":[{"$ref":"#/components/schemas/TriggerTypeEnum"}],"default":"fileupload","description":"How the run was triggered. Defaults to fileupload for programmatic file-based runs.\n\n* `fileupload` - File Upload\n* `webhook` - Webhook\n* `activity` - Activity\n* `schedule` - Schedule\n* `bulkaction` - Bulk Action"},"sql_parameters":{"description":"Parameters passed to the connector's SQL script, merged over the connector's configured defaults."},"entity_records_set_key":{"type":"string","nullable":true,"description":"Cache key from bulk action summary containing selected record IDs. Only for bulk action connectors."},"execution_id":{"type":"string","format":"uuid","readOnly":true,"description":"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."}},"required":["execution_id"]}}},"paths":{"/api/smart-connectors/{connector_identifier}/start-connector-flow":{"post":{"operationId":"smart_connectors_start_connector_flow_create","description":"Start the smart connector flow. For bulk action connectors, pass entity_records_set_key from a bulk action summary to run on selected records.","parameters":[{"in":"path","name":"connector_identifier","schema":{"type":"string"},"required":true},{"in":"query","name":"ordering","schema":{"type":"string","enum":["connector_type","created_at","custom_object__name","last_used_at","name","stats__used_count","status"]},"description":"Which field to use when ordering the results. Prepend with '-' for descending order."}],"tags":["smart-connectors"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartConnectorFlowStartRunRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartConnectorFlowStartRun"}}},"description":""}}}}}}
```
### Start SmartConnector Schemas
## The SmartConnectorFlowStartRun object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"SmartConnectorFlowStartRun":{"type":"object","properties":{"is_dry_run":{"type":"boolean","default":false,"description":"When true, validates the input file without committing changes (dry run). When false, performs a live run that writes records."},"disable_diff_check":{"type":"boolean","default":false,"description":"When true, skips the connector's diff-check validation."},"trigger_type":{"allOf":[{"$ref":"#/components/schemas/TriggerTypeEnum"}],"default":"fileupload","description":"How the run was triggered. Defaults to fileupload for programmatic file-based runs.\n\n* `fileupload` - File Upload\n* `webhook` - Webhook\n* `activity` - Activity\n* `schedule` - Schedule\n* `bulkaction` - Bulk Action"},"sql_parameters":{"description":"Parameters passed to the connector's SQL script, merged over the connector's configured defaults."},"entity_records_set_key":{"type":"string","nullable":true,"description":"Cache key from bulk action summary containing selected record IDs. Only for bulk action connectors."},"execution_id":{"type":"string","format":"uuid","readOnly":true,"description":"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."}},"required":["execution_id"]},"TriggerTypeEnum":{"enum":["fileupload","webhook","activity","schedule","bulkaction"],"type":"string","description":"* `fileupload` - File Upload\n* `webhook` - Webhook\n* `activity` - Activity\n* `schedule` - Schedule\n* `bulkaction` - Bulk Action"}}}}
```
## The SmartConnectorFlowStartRunRequest object
```json
{"openapi":"3.0.3","info":{"title":"Kizen API","version":"1.0.0"},"components":{"schemas":{"SmartConnectorFlowStartRunRequest":{"type":"object","properties":{"source_file_id":{"type":"string","format":"uuid","writeOnly":true,"nullable":true,"description":"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_id":{"type":"string","format":"uuid","writeOnly":true,"nullable":true,"description":"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_run":{"type":"boolean","default":false,"description":"When true, validates the input file without committing changes (dry run). When false, performs a live run that writes records."},"disable_diff_check":{"type":"boolean","default":false,"description":"When true, skips the connector's diff-check validation."},"trigger_type":{"allOf":[{"$ref":"#/components/schemas/TriggerTypeEnum"}],"default":"fileupload","description":"How the run was triggered. Defaults to fileupload for programmatic file-based runs.\n\n* `fileupload` - File Upload\n* `webhook` - Webhook\n* `activity` - Activity\n* `schedule` - Schedule\n* `bulkaction` - Bulk Action"},"sql_parameters":{"description":"Parameters passed to the connector's SQL script, merged over the connector's configured defaults."},"entity_records_set_key":{"type":"string","nullable":true,"minLength":1,"description":"Cache key from bulk action summary containing selected record IDs. Only for bulk action connectors."}}},"TriggerTypeEnum":{"enum":["fileupload","webhook","activity","schedule","bulkaction"],"type":"string","description":"* `fileupload` - File Upload\n* `webhook` - Webhook\n* `activity` - Activity\n* `schedule` - Schedule\n* `bulkaction` - Bulk Action"}}}}
```
***
## What's Next?
Continue with the [SmartConnector Webhook Trigger API](/docs/concepts/smartconnectors/smartconnector-apis/smartconnector-webhook-trigger-api.md) to learn how to trigger a Webhook SmartConnector by delivering inbound webhook payloads to its endpoint, the equivalent entry point for webhook-triggered connectors.