Initiate Workflow

Endpoint

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

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

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

Optional Fields

Field	Type	Description
`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`
`user`	string	Ignored on this endpoint. The task is always attributed to the access token’s user

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 two 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/v2/workflows/vendor_contract_review/latest/initiate" \
  -H "Authorization: Bearer your_access_token" \
  -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"
      }
    ],
    "metadata": {
      "source": "vendor_portal",
      "priority": "high"
    }
  }'

import requests

workflow_id = "vendor_contract_review"
version = "latest"

url = f"https://platform.chamelio.ai/v2/workflows/{workflow_id}/{version}/initiate"
headers = {
    "Authorization": "Bearer your_access_token",
    "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"
        }
    ],
    "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/v2/workflows/${workflowId}/${version}/initiate`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_access_token',
      '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'
        }
      ],
      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": "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, when a currency or table value fails the workflow’s rules, or when 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.

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

{
  "detail": "Currency 'EUR' is not allowed for 'contract_value' (allowed: USD, GBP)"
}

{
  "detail": "Table 'line_items' row 0 has 3 cells, expected 4 (columns: ['Item', 'Quantity', 'Unit Price', 'Total'])"
}

{
  "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.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token lacks the required scope:

{
  "detail": "Insufficient scope; this endpoint requires: workflows:write"
}

Or when the user is not permitted to request this workflow:

{
  "detail": "You do not have access to this resource"
}

404 Not Found

Returned when the workflow or version does not exist.

{
  "detail": "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"
    }
  ]
}

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

{
  "detail": "Rate limit exceeded"
}

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, 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 - you cannot initiate on behalf of someone else here.

All required variables from the workflow schema must be provided in the variables array. Missing required variables 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:

User-initiated actions - Let a user start a workflow from your own interface, as themselves
Integration workflows - Trigger Chamelio workflows from your applications
Correct attribution - Ensure the requester recorded on the task is the real person
Permission-safe automation - Rely on Chamelio to reject workflows the user may not request

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

403 Forbidden

404 Not Found

422 Validation Error

429 Too Many Requests

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

​403 Forbidden

​404 Not Found

​422 Validation Error

​429 Too Many Requests

​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

403 Forbidden

404 Not Found

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases