Initiate Workflow

Endpoint

POST /workflows/{workflow_id}/{version}/initiate

Authentication

This endpoint requires authentication via API key. Include your API key in the X-API-Key header:

X-API-Key: ca_your_api_key_here

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
`variables`	array	List of input values for workflow variables (see InputValue types below)

Optional Fields

Field	Type	Description
`user`	string	Email address of the user initiating the workflow. If not provided, workflow is attributed to the API key owner
`metadata`	object	Key-value pairs (strings) to attach to the task for tracking and filtering
`auto_creation_of_extra_variables`	boolean	When `true`, `metadata` entries are passed as extra variables so the workflow can auto-create them. Defaults to `false`
`extra_files`	array	Files to attach to the task without mapping them to a workflow variable. Each entry is an object with `filename` and `base64_content`

InputValue Types

Each variable value must include variable_id, type, and value. The type determines the value format:

Type	Description	Value Format	Example
`text`	Text string	string	`"Acme Corporation"`
`number`	Numeric value	string (numeric)	`"50000.00"`
`number_with_currency`	Monetary amount	string (numeric), or an object with `value` and `currency`	`"50000.00"` or `{"value": "50000.00", "currency": "EUR"}`
`boolean`	True/false	`"true"` or `"false"`	`"true"`
`date`	Date	ISO 8601 format	`"2025-01-15"`
`email`	Email address	string (email)	`"john@example.com"`
`select`	Dropdown selection	string (option value)	`"high_priority"`
`multi_select`	Multiple dropdown selections	array of strings (option values)	`["legal", "finance"]`
`file`	File upload	object with `value`, plus `file_id` or `base64_content`, and optional `file_extension`	See below
`multiple_files`	Multiple file uploads	object with a `files` array	See below
`user_entity`	User reference	string (email)	`"manager@example.com"`
`business`	Business entity	string (name/identifier)	`"Legal Department"`
`dynamic_list`	List of values	array of strings	`["Acme Corp", "Globex"]`
`dynamic_table`	Table	array of rows, each an object or a list of cells	See below

File InputValue

For file inputs, you have three options: Option 1: Reference previously uploaded file

{
  "variable_id": "contract_file",
  "type": "file",
  "value": "contract.pdf",
  "file_id": "doc_12345"
}

Option 2: Include base64 content

{
  "variable_id": "contract_file",
  "type": "file",
  "value": "contract.pdf",
  "file_extension": "pdf",
  "base64_content": "JVBERi0xLjQKJeLjz9MK..."
}

Multiple Files InputValue

For variables that accept several files, use type: "multiple_files" and provide a files array. Each entry has the same shape as a single File InputValue - value (the filename) plus either a file_id reference or file_extension + base64_content. You can mix references and uploads within the same array.

{
  "variable_id": "supporting_docs",
  "type": "multiple_files",
  "files": [
    {
      "value": "appendix_a.pdf",
      "file_id": "doc_123"
    },
    {
      "value": "appendix_b.pdf",
      "file_extension": "pdf",
      "base64_content": "JVBERi0xLjQKJeLjz9MK..."
    }
  ]
}

Number With Currency InputValue

For monetary fields, use type: "number_with_currency". Send value as a plain amount to use the field’s default currency:

{
  "variable_id": "contract_value",
  "type": "number_with_currency",
  "value": "50000.00"
}

To set the currency explicitly, send value as an object with value and currency:

{
  "variable_id": "contract_value",
  "type": "number_with_currency",
  "value": {
    "value": "50000.00",
    "currency": "EUR"
  }
}

Field	Type	Description
`value`	string or number	Numeric amount (e.g., `"50000.00"` or `50000`)
`currency`	string	ISO 4217 currency code. If the field restricts its currencies, the code must be one of the field’s `currencies` in the workflow schema; a field with no `currencies` list accepts any supported code

A plain amount uses the field’s default_currency. If the field has no default currency, the amount is saved without a currency, so send the object form when the currency matters.

Supported currency codes

USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY, SEK, NZD, MXN, SGD, HKD, NOK, KRW, TRY, INR, RUB, BRL, ZAR, DKK, PLN, TWD, THB, MYR, IDR, HUF, CZK, ILS, CLP, PHP, AED, COP, SAR, RON, BGN, ARS, VND, UAH, PKR, EGP, NGN, BDT, QAR, KWD, OMR, BHD, PEN, CRC, DOP

A code outside this list fails request validation with a 422. A supported code that the field doesn’t allow, or a currency on a variable that isn’t part of the workflow, returns a 400.

Dynamic Table InputValue

For table fields, use type: "dynamic_table" and send value as an array of rows. The column names and their order come from the variable’s columns in the workflow schema. Each row can be an object keyed by column name:

{
  "variable_id": "line_items",
  "type": "dynamic_table",
  "value": [
    { "Item": "Laptop", "Quantity": 2, "Unit Price": 1200 },
    { "Item": "Monitor", "Quantity": 3, "Unit Price": 300 }
  ]
}

Or a list of cells in column order. A list row must have exactly one cell per column, including formula columns, so pass null for those. In this example Total is a formula column:

{
  "variable_id": "line_items",
  "type": "dynamic_table",
  "value": [
    ["Laptop", 2, 1200, null],
    ["Monitor", 3, 300, null]
  ]
}

You can mix both row forms in the same table. Cells can be strings, numbers, booleans, or null. Each cell is saved as a string: booleans become "true" or "false", and null becomes an empty string.

A list row whose cell count doesn’t match the table’s columns returns a 400.

Request Example

curl -X POST "https://platform.chamelio.ai/workflows/vendor_contract_review/latest/initiate" \
  -H "X-API-Key: ca_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": [
      {
        "variable_id": "vendor_name",
        "type": "text",
        "value": "Acme Corporation"
      },
      {
        "variable_id": "contract_value",
        "type": "number",
        "value": "150000.00"
      },
      {
        "variable_id": "reviewer_email",
        "type": "email",
        "value": "legal@example.com"
      },
      {
        "variable_id": "contract_file",
        "type": "file",
        "value": "acme_contract.pdf",
        "file_id": "doc_789"
      },
      {
        "variable_id": "urgent",
        "type": "boolean",
        "value": "true"
      }
    ],
    "user": "john.doe@example.com",
    "metadata": {
      "source": "vendor_portal",
      "priority": "high"
    }
  }'

import requests

workflow_id = "vendor_contract_review"
version = "latest"

url = f"https://platform.chamelio.ai/workflows/{workflow_id}/{version}/initiate"
headers = {
    "X-API-Key": "ca_your_api_key_here",
    "Content-Type": "application/json"
}

payload = {
    "variables": [
        {
            "variable_id": "vendor_name",
            "type": "text",
            "value": "Acme Corporation"
        },
        {
            "variable_id": "contract_value",
            "type": "number",
            "value": "150000.00"
        },
        {
            "variable_id": "reviewer_email",
            "type": "email",
            "value": "legal@example.com"
        },
        {
            "variable_id": "contract_file",
            "type": "file",
            "value": "acme_contract.pdf",
            "file_id": "doc_789"
        }
    ],
    "user": "john.doe@example.com",
    "metadata": {
        "source": "vendor_portal"
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const workflowId = 'vendor_contract_review';
const version = 'latest';

const response = await fetch(
  `https://platform.chamelio.ai/workflows/${workflowId}/${version}/initiate`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'ca_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      variables: [
        {
          variable_id: 'vendor_name',
          type: 'text',
          value: 'Acme Corporation'
        },
        {
          variable_id: 'contract_value',
          type: 'number',
          value: '150000.00'
        },
        {
          variable_id: 'reviewer_email',
          type: 'email',
          value: 'legal@example.com'
        },
        {
          variable_id: 'contract_file',
          type: 'file',
          value: 'acme_contract.pdf',
          file_id: 'doc_789'
        }
      ],
      user: 'john.doe@example.com',
      metadata: {
        source: 'vendor_portal'
      }
    })
  }
);

const data = await response.json();
console.log(data);

Response

Success Response

Status Code: 200 OK

{
  "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": "in_progress",
  "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 (typically `"in_progress"` or `"pending"`)
`message`	string	Success confirmation message

Error Responses

400 Bad Request

Returned when the version format is invalid or request structure is malformed.

{
  "detail": "Invalid version format: invalid_version"
}

On this endpoint, a currency or table value that fails the workflow’s rules currently also returns "Invalid version format: {version}", even when the version is valid. This covers a currency the field doesn’t allow, a currency on a variable that isn’t part of the workflow, and a list row with the wrong number of cells. Check those values if you get this error with a valid version. Initiate Workflow (Flexible) returns the specific message instead.

401 Unauthorized

Returned when authentication fails. See the authentication errors section for details.

{
  "detail": "Invalid API key"
}

404 Not Found

Returned when the workflow or version doesn’t exist.

{
  "detail": "Workflow not found"
}

422 Validation Error

Returned when the request body is invalid or variables don’t match the workflow schema.

{
  "detail": [
    {
      "loc": ["body", "variables", 0, "value"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

500 Internal Server Error

Returned when workflow initiation fails due to a server error.

{
  "detail": "Failed to initiate workflow"
}

Notes

Save the task_id from the response to track the workflow’s progress using the Get Task endpoint.

All required variables from the workflow schema must be provided in the variables array. Missing required variables will result in a 422 error.

Use the metadata field to add custom tracking information like source system, request ID, or priority level for filtering and reporting.

Use Cases

This endpoint is useful for:

Automated workflow triggering - Start workflows from external systems or events
Integration workflows - Trigger Chamelio workflows from your applications
Bulk processing - Initiate multiple workflow instances programmatically
User-initiated actions - Allow end users to start workflows through custom interfaces

Overview

API Key Access

OAuth App Access

MCP (beta)

Webhooks

Endpoint

Authentication

Path Parameters

Request Body

Required Fields

Optional Fields

InputValue Types

File InputValue

Multiple Files InputValue

Number With Currency InputValue

Dynamic Table InputValue

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

422 Validation Error

500 Internal Server Error

Notes

Use Cases

Overview

API Key Access

OAuth App Access

MCP (beta)

Webhooks

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Required Fields

​Optional Fields

​InputValue Types

​File InputValue

​Multiple Files InputValue

​Number With Currency InputValue

​Dynamic Table InputValue

​Request Example

​Response

​Success Response

​Response Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​404 Not Found

​422 Validation Error

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Path Parameters

Request Body

Required Fields

Optional Fields

InputValue Types

File InputValue

Multiple Files InputValue

Number With Currency InputValue

Dynamic Table InputValue

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

422 Validation Error

500 Internal Server Error

Notes

Use Cases