Skip to main content

Run Record Action

POST 
/api/automation/record-actions/:workflow/run

Run a record-action workflow on one record, a selection of records, or every record matching a filter.

Required scope: settings:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Requires workflows.run, view permission on the resource, and a role allowed by the workflow. The workflow must be published, be a record action, and be bound to the resource sent.

Body

  • resource (required) - One of supplier, product, sales_order, purchase_order, customer. Must match the workflow's resource.
  • scope (required) - ids or filter.
  • ids (required when scope=ids) - array of distinct record ids, at least 1 and at most the workflow's max_records.
  • filters (required, may be empty, when scope=filter) - the same filter keys the resource's list endpoint accepts (e.g. search, archived, column filters such as name.contains, or a filter_groups tree). Runs on up to 10,000 matching records; archived suppliers and customers are excluded unless the filter mentions archived.
  • inputs (optional object) - values for the workflow's declared inputs (see inputs[] in List Record Actions). Validated against the inputs saved on the workflow: number -> numeric, boolean -> boolean, date -> date, select -> one of its options (an array when it allows several), text -> string up to 2000 chars. Required inputs must be present; omitted inputs with a literal default take that default. A value that is still an unresolved {{ ... }} expression counts as missing, so a required input left that way returns 422. Undeclared keys are dropped.

Responses

  • 201 - one record (scope=ids with a single id): the run was created and queued. Returns executions[] with its id, status and page url.
  • 202 - several records or a filter: a background job starts the runs. Returns tracked_job_id (follow it with the tracked job log endpoints in the Administration collection) and, for scope=ids, executions_count. Records over the hourly run limit are skipped and counted in the job summary.
  • 403 - missing permission or role.
  • 404 - the workflow, or the single record, does not exist.
  • 409 - this workflow is already running on that record; execution_id is the in-flight run.
  • 422 - validation errors, or the workflow changed (unpublished or no longer a record action) or runs on a different resource.
  • 423 - automation is turned off for the account.
  • 429 - rate limited: more than 60 run requests a minute for the account, or more than 1,000 record-action runs of this workflow in an hour. The body and the Retry-After header give the seconds to wait.

Request​

Responses​

Created

Response Headers
    Content-Type