> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/api/smart-connectors.md).

# Smart Connectors

## 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":{"type":"object","additionalProperties":{},"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":{"type":"object","additionalProperties":{},"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":""}}}}}}
```

## Send webhook data

> Send inbound webhook data to a Webhook SmartConnector's endpoint. The request body and query string are accepted as-is and queued for asynchronous processing; the connector run is created in the background. The response is returned immediately with an empty body and does not include an execution ID. Only connectors of type webhook accept requests at this endpoint, and the request body is limited to 250 KB and must be UTF-8 encoded.

```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":{"SmartConnectorWebhookErrorResponse":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}},"paths":{"/api/smart-connectors/{connector_identifier}/webhook":{"post":{"operationId":"smart_connectors_webhook_create","description":"Send inbound webhook data to a Webhook SmartConnector's endpoint. The request body and query string are accepted as-is and queued for asynchronous processing; the connector run is created in the background. The response is returned immediately with an empty body and does not include an execution ID. Only connectors of type webhook accept requests at this endpoint, and the request body is limited to 250 KB and must be UTF-8 encoded.","summary":"Send webhook data","parameters":[{"in":"path","name":"connector_identifier","schema":{"type":"string"},"required":true},{"in":"query","name":"example_param","schema":{"type":"string"},"description":"Example query parameter. Any query parameter is accepted."}],"tags":["smart-connectors"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}},"application/x-www-form-urlencoded":{"schema":{"type":"object","additionalProperties":{}}},"multipart/form-data":{"schema":{"type":"object","additionalProperties":{}}},"application/xml":{"schema":{"type":"object","additionalProperties":{}}},"text/html":{"schema":{"type":"object","additionalProperties":{}}},"text/csv":{"schema":{"type":"object","additionalProperties":{}}}}},"responses":{"201":{"description":"Webhook accepted and queued for asynchronous processing. The response body is empty."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartConnectorWebhookErrorResponse"}}},"description":"The request was rejected. Returned when the SmartConnector is not of type webhook, the request body exceeds the 250 KB limit, or the request body is not UTF-8 encoded."}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.kizen.com/api/smart-connectors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.