An automation watches one kind of change (an item updated, a document issued), checks it against your conditions, and then sends a mail or an SMS, calls one of your webhooks, or updates a field. You build it on the Automations screen or through API v2, try it on a real record without sending anything, and read its run log afterwards.
automations:read /
automations:write by name: * does not grant them, because an
automation sends messages and changes records.
A trigger, conditions, and up to ten actions run in order:
{
"name": "Thank-you SMS on an invoice-receipt",
"trigger": { "event": "document.issued" },
"conditions": { "match": "all", "rules": [
{ "field": "type_id", "op": "eq", "value": 320 },
{ "field": "total", "op": "gt", "value": 0 }
]},
"actions": [
{ "type": "sms", "template_id": 4, "to": "recipient" },
{ "type": "webhook", "webhook_id": "wh_8d1e…" }
]
}POST /api/v2/automations with that body creates it (201, id
au_…). Everything is checked against the catalogue first: a wrong event, field,
operator, template or webhook is a 422 naming the exact place, e.g.
actions.0.template_id.
The triggers are the webhook events, plus
document.created (a document's first save, a draft included). Conditions can also
read the record's custom fields, as custom.<key>.
GET /api/v2/automations/catalogue lists them, each with its fields (in API v2
names, with their type) and the actions it allows.
| Operator | Matches when the field… |
|---|---|
| eq, ne | equals / does not equal the value: numbers as numbers, text ignoring case |
| lt, gt, lte, gte | is less / greater (or equal) |
| contains, starts_with | contains / starts with the text, ignoring case |
| empty, not_empty | has no value / has one |
| changed | changed in this save (an .updated event); with a value, changed to it |
match: "all" needs every rule, "any" one of them. No rules: every event.
| Type | Settings | What it does |
|---|---|---|
template_id (optional), to: recipient or an address, attach_pdf | The document's mail, rendered from a mail template, the PDF attached. Document events only. | |
| sms | template_id, to: recipient or a number | The SMS template, rendered for the document. Document events only. |
| webhook | webhook_id | One of your v2 webhooks is sent the event: signed, retried, in its delivery log. |
| update_field | field, value | Sets the record's field (the value may hold {{sku}}-style fields of the record). The record's own rules apply. |
| make_document | type_id, issue | Makes a document of that type from the triggering one, referencing it: a draft unless issue. Document events only. |
| notify | users, role, subject, text | Mails your staff (chosen users, everyone in a role, or both), the text filled with the record's fields. |
POST /api/v2/automations/{id}/test with {"record_id": 1234} sends and
writes nothing. It answers whether the conditions match that record now, and what each action
would do: the rendered mail or SMS and who it goes to, the webhook's URL, a field's old and new
value. Add "dry_run": false to run the actions for real, once.
| Question | Answer |
|---|---|
| When? | From the queue, seconds after the save is committed. A save that is rolled back runs nothing. |
| Can an automation set off another? | No. What an automation writes never triggers automations, so two rules cannot loop. |
| A failed action? | Stops the actions after it; the run is failed with the reason. A webhook action is retried as webhooks are. |
| Limits? | 50 automations per company; each runs at most 1,000 times an hour (the rest are logged as skipped). |
| Where do I see what happened? | GET /api/v2/automations/{id}/runs: newest first, 90 days, each action's result. |