> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Initiate Workflow (Flexible)
> Start a workflow with flexible key-value pairs and automatic type detection, as the access token's user
## Endpoint
```
POST /v2/workflows/{workflow_id}/{version}/initiate-simple
```
## Authentication
This endpoint requires an OAuth access token. Send it as a bearer token:
```bash theme={null}
Authorization: Bearer your_access_token
```
**Required scope:** `workflows:write`
The task is created **as the access token's user**, who must be at least a requester on the workflow.
The `user` field on the request body is ignored.
## Path Parameters
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------------------ |
| `workflow_id` | string | Yes | Unique identifier for the workflow |
| `version` | string | Yes | Version number (e.g., "1") or "latest" for the most recent version |
## Request Body
The request body must be a JSON object with the following fields:
### Required Fields
| Field | Type | Description |
| ------------ | ----- | ----------------------------------------------------------------- |
| `attributes` | array | List of simple key-value pairs for workflow variables (see below) |
### Optional Fields
| Field | Type | Description |
| ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `files` | array | List of files with base64 content (see File Format below) |
| `extra_attachments` | array | Additional files attached to the task but not mapped to any workflow variable. Same object shape as `files` |
| `metadata` | object | Key-value pairs (strings) to attach to the task |
| `auto_creation_of_extra_variables` | boolean | When `true`, attributes that matched no workflow field, plus `metadata` entries, are passed as extra variables so the workflow can auto-create them. Defaults to `false` |
| `user` | string | Ignored on this endpoint. The task is always attributed to the access token's user |
### Attribute Format
Each attribute is a simple object with `key` and `value` fields:
```json theme={null}
{
"key": "vendor_name",
"value": "Acme Corporation"
}
```
The system will match attributes to workflow variables using flexible matching:
1. Exact match by variable ID
2. Case-insensitive match by variable title
3. Normalized match (lowercase, spaces/underscores/hyphens ignored)
All values are provided as strings. The system will automatically convert them to the appropriate type based on the workflow schema.
### File Format
Files are provided separately from attributes:
```json theme={null}
{
"filename": "contract.pdf",
"base64_content": "JVBERi0xLjQKJeLjz9MK..."
}
```
Files are matched to workflow fields by order. Single file fields are filled first, in order. Any leftover files spill into the workflow's `multiple_files` variable if one exists; otherwise they are attached to the task as extra attachments. Ensure files in the array correspond to the order of file fields in your workflow.
Files are validated against the platform's supported file extensions. Files with unsupported extensions are skipped rather than coerced.
## When to Use This Endpoint
This endpoint is designed for scenarios where the integrating system or user **cannot maintain variable-specific mapping and control**. Use this endpoint when:
* **Generic integration systems** that handle multiple workflows without custom configuration for each
* **Low-code/no-code platforms** where users configure integrations through UI without coding
* **Form builders** that generate dynamic field mappings based on workflow schemas
* **Third-party tools** that need to integrate with workflows but can't be customized for each workflow's schema
* **Rapid prototyping** where you want to test workflows without setting up precise type mappings
* **Simple scripts** where maintaining detailed variable schemas adds unnecessary complexity
The flexible matching (by ID, title, or normalized name) means integrating systems can use human-readable labels without knowing the exact internal variable IDs.
If your integration requires precise control over variable types, file references, or needs to distinguish between fields with similar names, use the standard [Initiate Workflow](/api-reference/endpoint/v2/workflows/initiate) endpoint instead.
## Request Example
```bash cURL theme={null}
curl -X POST "https://platform.chamelio.ai/v2/workflows/vendor_contract_review/latest/initiate-simple" \
-H "Authorization: Bearer your_access_token" \
-H "Content-Type: application/json" \
-d '{
"attributes": [
{
"key": "vendor_name",
"value": "Acme Corporation"
},
{
"key": "contract_value",
"value": "150000.00"
},
{
"key": "reviewer_email",
"value": "legal@example.com"
},
{
"key": "urgent",
"value": "true"
}
],
"files": [
{
"filename": "acme_contract.pdf",
"base64_content": "JVBERi0xLjQKJeLjz9MK..."
}
]
}'
```
```python Python theme={null}
import requests
import base64
workflow_id = "vendor_contract_review"
version = "latest"
# Read and encode file
with open("acme_contract.pdf", "rb") as f:
file_content = base64.b64encode(f.read()).decode('utf-8')
url = f"https://platform.chamelio.ai/v2/workflows/{workflow_id}/{version}/initiate-simple"
headers = {
"Authorization": "Bearer your_access_token",
"Content-Type": "application/json"
}
payload = {
"attributes": [
{
"key": "vendor_name",
"value": "Acme Corporation"
},
{
"key": "contract_value",
"value": "150000.00"
},
{
"key": "reviewer_email",
"value": "legal@example.com"
}
],
"files": [
{
"filename": "acme_contract.pdf",
"base64_content": file_content
}
]
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript JavaScript theme={null}
const workflowId = 'vendor_contract_review';
const version = 'latest';
// Convert file to base64
const fileToBase64 = (file) => {
return new Promise((resolve, reject) => {
const reader = new FileReader();
reader.readAsDataURL(file);
reader.onload = () => resolve(reader.result.split(',')[1]);
reader.onerror = error => reject(error);
});
};
// Assuming you have a File object
const base64Content = await fileToBase64(fileObject);
const response = await fetch(
`https://platform.chamelio.ai/v2/workflows/${workflowId}/${version}/initiate-simple`,
{
method: 'POST',
headers: {
'Authorization': 'Bearer your_access_token',
'Content-Type': 'application/json'
},
body: JSON.stringify({
attributes: [
{
key: 'vendor_name',
value: 'Acme Corporation'
},
{
key: 'contract_value',
value: '150000.00'
},
{
key: 'reviewer_email',
value: 'legal@example.com'
}
],
files: [
{
filename: 'acme_contract.pdf',
base64_content: base64Content
}
]
})
}
);
const data = await response.json();
console.log(data);
```
## Response
### Success Response
**Status Code:** `200 OK`
```json theme={null}
{
"task_id": 12345,
"task_url": "https://app.chamelio.ai/b/workflows/tasks/12345",
"workflow_state_id": "wfs_abc123xyz",
"workflow_id": "vendor_contract_review",
"version": 1,
"status": "pending",
"message": "Workflow initiated successfully"
}
```
### Response Fields
| Field | Type | Description |
| ------------------- | --------------- | ----------------------------------------------------------------------------- |
| `task_id` | integer or null | Unique identifier for the created task. Use this to track task status |
| `task_url` | string or null | Link to the created task in the Chamelio app. `null` when no task was created |
| `workflow_state_id` | string | Internal workflow state identifier |
| `workflow_id` | string | Workflow identifier that was initiated |
| `version` | integer | Workflow version number that was used |
| `status` | string | Initial task status |
| `message` | string | Success confirmation message |
## Error Responses
### 400 Bad Request
Returned when the version format is invalid, the request structure is malformed, or the access token
has no user behind it.
`client_credentials` tokens act as the admin who created the application, so this applies only to
tokens issued before application creators were recorded.
```json theme={null}
{
"detail": "Invalid version format: invalid_version"
}
```
```json theme={null}
{
"detail": "client_credentials tokens are not associated with a user"
}
```
### 401 Unauthorized
Returned when the access token is missing, unknown, revoked, or expired, or when an `X-API-Key` was
sent instead of a bearer token. See [OAuth error responses](/api-reference/oauth-apps#error-responses).
```json theme={null}
{
"detail": "Invalid access token"
}
```
### 403 Forbidden
Returned when the token lacks the required scope:
```json theme={null}
{
"detail": "Insufficient scope; this endpoint requires: workflows:write"
}
```
Or when the user is not permitted to request this workflow:
```json theme={null}
{
"detail": "You do not have access to this resource"
}
```
### 404 Not Found
Returned when the workflow or version does not exist.
```json theme={null}
{
"detail": "Not found"
}
```
### 422 Validation Error
Returned when the request body is invalid or required variables are missing.
```json theme={null}
{
"detail": [
{
"loc": ["body", "attributes"],
"msg": "field required",
"type": "value_error.missing"
}
]
}
```
### 429 Too Many Requests
Returned when your organization exceeds its per-minute request limit.
```json theme={null}
{
"detail": "Rate limit exceeded"
}
```
### 500 Internal Server Error
Returned when workflow initiation fails due to a server error.
```json theme={null}
{
"detail": "Failed to initiate workflow"
}
```
## Comparison with `/initiate`
| Aspect | `/initiate` | `/initiate-simple` |
| ------------------ | ---------------------------------- | ----------------------------------------- |
| Input format | Typed `InputValue` objects | Simple `{key, value}` pairs |
| Variable matching | Exact `variable_id` only | Flexible: ID → title → normalized |
| File handling | Requires `file_id` or typed object | Base64 content, matched by order |
| Type specification | Explicit `type` field required | Auto-detected from schema |
| Use case | Precise control, file references | Systems without variable-specific mapping |
## Notes
Save the `task_id` from the response to track the workflow's progress using the
[Get Task](/api-reference/endpoint/v2/tasks/get) endpoint, or hand `task_url` to the user to open the
task in Chamelio.
The access token's user must be at least a requester on the workflow. If they are not, the request
returns `403`.
Use flexible attribute keys: "Vendor Name", "vendor\_name", and "vendor-name" will all match the same variable.
Files in the `files` array are matched to workflow file fields by position. The first file in the array is assigned to the first file field in the workflow, and so on. Files left over after all single file fields are filled go to the workflow's `multiple_files` variable if it has one, or are attached to the task as extra attachments otherwise.
Attributes that match no workflow field are dropped unless `auto_creation_of_extra_variables` is
`true`, in which case they are passed to the workflow as extra variables to create.
## Use Cases
This flexible endpoint is ideal for:
* **Generic integration platforms** - iPaaS solutions (Zapier, Make, Workato) that connect to multiple workflows without per-workflow configuration
* **Form builders** - Dynamic forms that adapt to workflow schemas without hardcoded field mappings
* **No-code tools** - Platforms where users configure integrations visually without access to variable IDs
* **Multi-tenant systems** - Applications serving multiple organizations with different workflow schemas
* **Rapid prototyping** - Quick testing without setting up precise variable mappings
**Key advantage**: Integrating systems don't need to maintain a mapping table between their field names and Chamelio's internal variable IDs. They can use human-readable labels directly.
For precise control over variable types, file references, or when you need to distinguish between similarly-named fields, use the standard [Initiate Workflow](/api-reference/endpoint/v2/workflows/initiate) endpoint.