Skip to main content

Endpoint

Authentication

This endpoint requires an OAuth access token. Send it as a bearer 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

Request Body

The request body must be a JSON object with the following fields:

Required Fields

Optional Fields

Attribute Format

Each attribute is a simple object with key and value fields:
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:
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 endpoint instead.

Request Example

Response

Success Response

Status Code: 200 OK

Response Fields

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.

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.

403 Forbidden

Returned when the token lacks the required scope:
Or when the user is not permitted to request this workflow:

404 Not Found

Returned when the workflow or version does not exist.

422 Validation Error

Returned when the request body is invalid or required variables are missing.

429 Too Many Requests

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

500 Internal Server Error

Returned when workflow initiation fails due to a server error.

Comparison with /initiate

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.
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 endpoint.