Automations

Base URL: $BUSINESS_API

The object

namestring · required
descriptionstring · optional
triggerobject · required
Show child attributes
typestring · required

one of invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · optional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · optional

Five-field cron expression, schedule only

timezonestring · optional
thresholdinteger · optional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · optional
Show child attributes
fieldstring · required

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · required

one of eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · optional
actionsarray of AutomationAction · required
Show child attributes
typestring · required

one of send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · optional

Minutes after the previous step

paramsobject · optional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · optional
template_keystring · optional
idstring · optional
tenant_idstring · optional
statusstring · optional

one of enabled, disabled

created_bystring · optional
created_atstring (date-time) · optional
updated_atstring (date-time) · optional
The object
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

List automation rules

Logs

GET /automations

Returns the tenant's automation rules with cursor pagination (limit defaults to 20, at most 100; pass next_cursor as after). Each rule includes its trigger, conditions, actions, status and current version. Requires automations:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

statusstring · query · optional

Return only rules in this state: enabled or disabled; omit for both.

one of enabled, disabled

Returns

200 Rules

Show attributes
dataarray of AutomationRule · optional
Show child attributes
namestring · required
descriptionstring · optional
triggerobject · required
Show child attributes
typestring · required

one of invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · optional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · optional

Five-field cron expression, schedule only

timezonestring · optional
thresholdinteger · optional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · optional
Show child attributes
fieldstring · required

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · required

one of eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · optional
actionsarray of AutomationAction · required
Show child attributes
typestring · required

one of send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · optional

Minutes after the previous step

paramsobject · optional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · optional
template_keystring · optional
idstring · optional
tenant_idstring · optional
statusstring · optional

one of enabled, disabled

created_bystring · optional
created_atstring (date-time) · optional
updated_atstring (date-time) · optional
has_moreboolean · optional
next_cursorstring · optional

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "name": "Ana Matsinhe",
      "description": "Leitura confirmada no local.",
      "trigger": {
        "type": "invoice.issued",
        "days": 1,
        "cron": "cron",
        "timezone": "Africa/Maputo",
        "threshold": 1
      },
      "conditions": [
        {
          "field": "field",
          "operator": "eq"
        }
      ],
      "actions": [
        {
          "type": "send_notification",
          "delay_minutes": 1,
          "params": {}
        }
      ],
      "enabled": true,
      "template_key": "template key",
      "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "status": "enabled",
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create an automation rule. Requires automations

Logs

POST /automations

Create an automation rule. Requires automations:write and the scope of every action.

Validates the name (up to 200 characters), trigger, conditions and actions, checks that owner_role, when set, is a utility role holding every scope the actions need, and stores the rule as version 1. Rules are enabled unless enabled is false. An enabled rule ignores records that already match at creation time unless apply_to_existing is true; schedule rules have no such baseline. Returns 201; 400 for an invalid rule and 403 when the caller lacks a scope an action needs.

Body application/json

namestring · required
descriptionstring · optional
triggerobject · required
Show child attributes
typestring · required

one of invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · optional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · optional

Five-field cron expression, schedule only

timezonestring · optional
thresholdinteger · optional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · optional
Show child attributes
fieldstring · required

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · required

one of eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · optional
actionsarray of AutomationAction · required
Show child attributes
typestring · required

one of send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · optional

Minutes after the previous step

paramsobject · optional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · optional
template_keystring · optional

Returns

201 Created rule

Show attributes
namestring · required
descriptionstring · optional
triggerobject · required
Show child attributes
typestring · required

one of invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · optional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · optional

Five-field cron expression, schedule only

timezonestring · optional
thresholdinteger · optional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · optional
Show child attributes
fieldstring · required

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · required

one of eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · optional
actionsarray of AutomationAction · required
Show child attributes
typestring · required

one of send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · optional

Minutes after the previous step

paramsobject · optional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · optional
template_keystring · optional
idstring · optional
tenant_idstring · optional
statusstring · optional

one of enabled, disabled

created_bystring · optional
created_atstring (date-time) · optional
updated_atstring (date-time) · optional

Errors 400 · 403

Permissions automations:write, business:notification-intents:create · Roles: admin, owner

curl -X POST "$BUSINESS_API/automations" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key"
}'
Response 201
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Ready-made rules

Logs

GET /automations/templates

Ready-made rules (dunning sequence, overdue reminder, missing-reading follow-up, anomaly review, ticket escalation)

Returns the starter templates, each with a key, name, description and a complete rule body in the shape createAutomation accepts. The templates are fixed and editable: post a template's rule as is, or change it first. Requires automations:read.

Returns

200 Templates, each with a ready-to-submit rule body

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/templates" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Templates, each with a ready-to-submit rule body

Read a rule

Logs

GET /automations/{id}

Returns one automation rule with its trigger, conditions or condition group, actions, status, owner role, rate limit and current version number. Answers 404 when the rule is not in the caller's tenant.

Parameters

idstring · path · required

Identifier of the automation rule (prefix aut_).

Returns

200 Rule

Show attributes
namestring · required
descriptionstring · optional
triggerobject · required
Show child attributes
typestring · required

one of invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · optional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · optional

Five-field cron expression, schedule only

timezonestring · optional
thresholdinteger · optional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · optional
Show child attributes
fieldstring · required

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · required

one of eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · optional
actionsarray of AutomationAction · required
Show child attributes
typestring · required

one of send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · optional

Minutes after the previous step

paramsobject · optional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · optional
template_keystring · optional
idstring · optional
tenant_idstring · optional
statusstring · optional

one of enabled, disabled

created_bystring · optional
created_atstring (date-time) · optional
updated_atstring (date-time) · optional

Errors 404

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Update automation

Logs

PATCH /automations/{id}

Update a rule's name, description, trigger, conditions or actions

Applies only the fields present in the body, then validates the whole rule again, including the caller's and owner_role's scopes for every action. Each successful update increments the version and stores an immutable snapshot. When an enabled rule's trigger or conditions change, records that already match the new criteria are recorded as existing so they do not all fire on the next sweep. Returns 400 for an invalid rule, 403 for a missing action scope and 404 for an unknown rule.

Parameters

idstring · path · required

Identifier of the automation rule to update (prefix aut_).

Body application/json

namestring · optional
descriptionstring · optional
triggerobject · optional
Show child attributes
typestring · required

one of invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · optional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · optional

Five-field cron expression, schedule only

timezonestring · optional
thresholdinteger · optional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · optional
Show child attributes
fieldstring · required

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · required

one of eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · optional
actionsarray of AutomationAction · optional
Show child attributes
typestring · required

one of send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · optional

Minutes after the previous step

paramsobject · optional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

Returns

200 Updated rule

Show attributes
namestring · required
descriptionstring · optional
triggerobject · required
Show child attributes
typestring · required

one of invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · optional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · optional

Five-field cron expression, schedule only

timezonestring · optional
thresholdinteger · optional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · optional
Show child attributes
fieldstring · required

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · required

one of eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · optional
actionsarray of AutomationAction · required
Show child attributes
typestring · required

one of send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · optional

Minutes after the previous step

paramsobject · optional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · optional
template_keystring · optional
idstring · optional
tenant_idstring · optional
statusstring · optional

one of enabled, disabled

created_bystring · optional
created_atstring (date-time) · optional
updated_atstring (date-time) · optional

Permissions automations:write · Roles: admin, finance, operations, owner

curl -X PATCH "$BUSINESS_API/automations/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ]
}'
Response 200
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Delete a rule

Logs

DELETE /automations/{id}

Permanently removes the rule and its list of existing records it was told to skip, answering 204 with no body. Answers 404 when the rule is not in the caller's tenant. Requires automations:write.

Parameters

idstring · path · required

Identifier of the automation rule to delete (prefix aut_).

Returns

204 Deleted

Permissions automations:write · Roles: admin, finance, operations, owner

curl -X DELETE "$BUSINESS_API/automations/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Deleted

Enable a rule. Requires the scope of every action

Logs

POST /automations/{id}/enable

By default only records that match after the rule is enabled fire it. Send apply_to_existing true to also fire it for records that already match.

Parameters

idstring · path · required

Identifier of the automation rule to enable (prefix aut_).

Body application/json

apply_to_existingboolean · optional · default false

Returns

200 Enabled rule

Show attributes
namestring · required
descriptionstring · optional
triggerobject · required
Show child attributes
typestring · required

one of invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · optional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · optional

Five-field cron expression, schedule only

timezonestring · optional
thresholdinteger · optional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · optional
Show child attributes
fieldstring · required

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · required

one of eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · optional
actionsarray of AutomationAction · required
Show child attributes
typestring · required

one of send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · optional

Minutes after the previous step

paramsobject · optional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · optional
template_keystring · optional
idstring · optional
tenant_idstring · optional
statusstring · optional

one of enabled, disabled

created_bystring · optional
created_atstring (date-time) · optional
updated_atstring (date-time) · optional

Permissions automations:write · Roles: admin, finance, operations, owner

curl -X POST "$BUSINESS_API/automations/{id}/enable" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "apply_to_existing": false
}'
Response 200
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Count automation existing records

Logs

GET /automations/{id}/existing-count

Count the records that already match a rule and have never fired it

Counts the records that match the rule's trigger and conditions right now and have never been claimed by a run of the rule. Use it before enabling with apply_to_existing to see how many records would fire at once. Requires automations:read; the count fails above the per-sweep record limit.

Parameters

idstring · path · required

Identifier of the automation rule to count records for (prefix aut_).

Returns

200 How many records applying the rule to existing records would hit

Show attributes
rule_idstring · required
countinteger · required

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/{id}/existing-count" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
  "count": 1
}

Disable automation

Logs

POST /automations/{id}/disable

Disable a rule. Waiting runs are cancelled on their next attempt.

Sets the rule to disabled, increments its version and stores a snapshot. The caller needs automations:write and the scope of every action in the rule. Disabling an already disabled rule still succeeds and bumps the version.

Parameters

idstring · path · required

Identifier of the automation rule to disable (prefix aut_).

Returns

200 Disabled rule

Show attributes
namestring · required
descriptionstring · optional
triggerobject · required
Show child attributes
typestring · required

one of invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · optional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · optional

Five-field cron expression, schedule only

timezonestring · optional
thresholdinteger · optional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · optional
Show child attributes
fieldstring · required

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · required

one of eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · optional
actionsarray of AutomationAction · required
Show child attributes
typestring · required

one of send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · optional

Minutes after the previous step

paramsobject · optional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · optional
template_keystring · optional
idstring · optional
tenant_idstring · optional
statusstring · optional

one of enabled, disabled

created_bystring · optional
created_atstring (date-time) · optional
updated_atstring (date-time) · optional

Permissions automations:write · Roles: admin, finance, operations, owner

curl -X POST "$BUSINESS_API/automations/{id}/disable" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "trigger": {
    "type": "invoice.issued",
    "days": 1,
    "cron": "cron",
    "timezone": "Africa/Maputo",
    "threshold": 1
  },
  "conditions": [
    {
      "field": "field",
      "operator": "eq"
    }
  ],
  "actions": [
    {
      "type": "send_notification",
      "delay_minutes": 1,
      "params": {}
    }
  ],
  "enabled": true,
  "template_key": "template key",
  "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "enabled",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Dry run a rule against a chosen record

Logs

POST /automations/{id}/test

Dry run a rule against a chosen record, with no side effects

Loads the record named by record_type and record_id (both required, except for schedule rules), evaluates the trigger and every condition, and plans each action without running it. The result says whether the rule would fire, why not if it would not (trigger mismatch, a failed condition, or the rule being disabled), each condition's outcome, and per action the planned summary, delay-adjusted start time or the reason it would be skipped. Requires only automations:read.

Parameters

idstring · path · required

Identifier of the automation rule to test (prefix aut_).

Body application/json

record_typestring · required

one of invoice, payment, meter, reading, consumption, ticket, work_order, disconnection_notice, schedule

record_idstring · required

Returns

200 What would happen

Show attributes
rule_idstring · optional
record_typestring · optional
record_idstring · optional
subjectobject · optional
would_fireboolean · optional
reasonstring · optional
conditionsarray of object · optional
actionsarray of AutomationOutcome · optional
Show child attributes
indexinteger · optional
typestring · optional
statusstring · optional

one of pending, succeeded, failed, skipped, would_run

summarystring · optional
resource_typestring · optional
resource_idstring · optional
resultobject · optional
errorstring · optional
attemptsinteger · optional
not_beforestring (date-time) · optional
finished_atstring (date-time) · optional

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X POST "$BUSINESS_API/automations/{id}/test" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "record_type": "invoice",
  "record_id": "rec_2JvgYnLE6d1uAnLSYrZqEztccx1"
}'
Response 200
{
  "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
  "record_type": "record type",
  "record_id": "rec_2JvgYnLE6d1uAnLSYrZqEztccx1",
  "subject": {},
  "would_fire": true,
  "reason": "Leitura confirmada no local.",
  "conditions": [
    {}
  ],
  "actions": [
    {
      "index": 1,
      "type": "active",
      "status": "pending",
      "summary": "summary",
      "resource_type": "resource type",
      "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
      "result": {},
      "error": "error",
      "attempts": 1,
      "not_before": "2026-11-19T09:30:00Z",
      "finished_at": "2026-11-19T09:30:00Z"
    }
  ]
}

List the runs of a rule

Logs

GET /automations/{id}/runs

Returns the runs the rule has started, with cursor pagination (limit defaults to 20, at most 100). Each run reports its subject record, status and per-action outcomes. Answers 404 when the rule is not in the caller's tenant.

Parameters

idstring · path · required

Identifier of the automation rule whose runs to list (prefix aut_).

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

statusstring · query · optional

Return only runs in this state: pending, running, waiting, succeeded, failed or cancelled; omit for all.

one of pending, running, waiting, succeeded, failed, cancelled

Returns

200 Runs, newest first

Show attributes
dataarray of AutomationRun · optional
Show child attributes
idstring · optional
rule_idstring · optional
rule_namestring · optional
trigger_typestring · optional
record_typestring · optional
record_idstring · optional
statusstring · optional

one of pending, running, waiting, succeeded, failed, cancelled

attemptsinteger · optional
errorstring · optional
outcomesarray of AutomationOutcome · optional
Show child attributes
indexinteger · optional
typestring · optional
statusstring · optional

one of pending, succeeded, failed, skipped, would_run

summarystring · optional
resource_typestring · optional
resource_idstring · optional
resultobject · optional
errorstring · optional
attemptsinteger · optional
not_beforestring (date-time) · optional
finished_atstring (date-time) · optional
next_attempt_atstring (date-time) · optional
started_atstring (date-time) · optional
finished_atstring (date-time) · optional
created_atstring (date-time) · optional
has_moreboolean · optional
next_cursorstring · optional

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/{id}/runs" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "aut_2lVaKhFGGnDyuBTQy3NKQNviCTv",
      "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
      "rule_name": "Ana Matsinhe",
      "trigger_type": "trigger type",
      "record_type": "record type",
      "record_id": "rec_2JvgYnLE6d1uAnLSYrZqEztccx1",
      "status": "pending",
      "attempts": 1,
      "error": "error",
      "outcomes": [
        {
          "index": 1,
          "type": "active",
          "status": "pending",
          "summary": "summary",
          "resource_type": "resource type",
          "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
          "result": {},
          "error": "error",
          "attempts": 1,
          "not_before": "2026-11-19T09:30:00Z",
          "finished_at": "2026-11-19T09:30:00Z"
        }
      ],
      "next_attempt_at": "2026-11-19T09:30:00Z",
      "started_at": "2026-11-19T09:30:00Z",
      "finished_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Read a run with the outcome and error of each action

Logs

GET /automations/{id}/runs/{runId}

Returns one run, including the record it fired for and, for each action, its status, scheduled time, summary, created resource and error. Answers 404 when the run does not exist or belongs to a different rule than the one in the path.

Parameters

idstring · path · required

Identifier of the automation rule the run belongs to (prefix aut_).

runIdstring · path · required

Identifier of the run to read; it must belong to the rule given in id.

Returns

200 Run

Show attributes
idstring · optional
rule_idstring · optional
rule_namestring · optional
trigger_typestring · optional
record_typestring · optional
record_idstring · optional
statusstring · optional

one of pending, running, waiting, succeeded, failed, cancelled

attemptsinteger · optional
errorstring · optional
outcomesarray of AutomationOutcome · optional
Show child attributes
indexinteger · optional
typestring · optional
statusstring · optional

one of pending, succeeded, failed, skipped, would_run

summarystring · optional
resource_typestring · optional
resource_idstring · optional
resultobject · optional
errorstring · optional
attemptsinteger · optional
not_beforestring (date-time) · optional
finished_atstring (date-time) · optional
next_attempt_atstring (date-time) · optional
started_atstring (date-time) · optional
finished_atstring (date-time) · optional
created_atstring (date-time) · optional

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/{id}/runs/{runId}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "aut_2lVaKhFGGnDyuBTQy3NKQNviCTv",
  "rule_id": "rul_2aARlSaHxSk1Z6Yp9aKdnemXRyk",
  "rule_name": "Ana Matsinhe",
  "trigger_type": "trigger type",
  "record_type": "record type",
  "record_id": "rec_2JvgYnLE6d1uAnLSYrZqEztccx1",
  "status": "pending",
  "attempts": 1,
  "error": "error",
  "outcomes": [
    {
      "index": 1,
      "type": "active",
      "status": "pending",
      "summary": "summary",
      "resource_type": "resource type",
      "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
      "result": {},
      "error": "error",
      "attempts": 1,
      "not_before": "2026-11-19T09:30:00Z",
      "finished_at": "2026-11-19T09:30:00Z"
    }
  ],
  "next_attempt_at": "2026-11-19T09:30:00Z",
  "started_at": "2026-11-19T09:30:00Z",
  "finished_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}

List a rule's immutable versions

Logs

GET /automations/{id}/versions

Returns every stored snapshot of the rule in ascending version order, each with the name, trigger, conditions, actions, owner role, author and time it was saved. A new version is written on create, update, enable and disable. Answers 404 when the rule is not in the tenant.

Parameters

idstring · path · required

Identifier of the automation rule whose versions to list (prefix aut_).

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Versions, oldest first

Show attributes
dataarray of AutomationRule · optional
Show child attributes
namestring · required
descriptionstring · optional
triggerobject · required
Show child attributes
typestring · required

one of invoice.issued, invoice.overdue, invoice.paid, payment.received, reading.missing, reading.review_required, consumption.anomaly, ticket.created, ticket.unresolved, work_order.overdue, disconnection.notice_expired, schedule, …

daysinteger · optional

N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing

cronstring · optional

Five-field cron expression, schedule only

timezonestring · optional
thresholdinteger · optional

Percentage of the average that fires consumption.anomaly

conditionsarray of AutomationCondition · optional
Show child attributes
fieldstring · required

amount (cents), days_overdue, customer_category, service_area, or metadata.<key>

operatorstring · required

one of eq, neq, gt, gte, lt, lte, in, not_in, contains, exists

valueany · optional
actionsarray of AutomationAction · required
Show child attributes
typestring · required

one of send_notification, create_collection_case, issue_disconnection_notice, apply_late_fee, create_work_order, create_ticket, set_metadata, call_webhook

delay_minutesinteger · optional

Minutes after the previous step

paramsobject · optional

send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.

enabledboolean · optional
template_keystring · optional
idstring · optional
tenant_idstring · optional
statusstring · optional

one of enabled, disabled

created_bystring · optional
created_atstring (date-time) · optional
updated_atstring (date-time) · optional

Errors 404

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/{id}/versions" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "name": "Ana Matsinhe",
      "description": "Leitura confirmada no local.",
      "trigger": {
        "type": "invoice.issued",
        "days": 1,
        "cron": "cron",
        "timezone": "Africa/Maputo",
        "threshold": 1
      },
      "conditions": [
        {
          "field": "field",
          "operator": "eq"
        }
      ],
      "actions": [
        {
          "type": "send_notification",
          "delay_minutes": 1,
          "params": {}
        }
      ],
      "enabled": true,
      "template_key": "template key",
      "id": "aut_2w073m0Tz4ynrGAZLEIP3cmHTUK",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "status": "enabled",
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

List a rule's backtests and simulations

Logs

GET /automations/{id}/backtests

Returns every backtest stored for the rule, newest first, with the window, rule version, status, counts of matched records and records that would act, and the per-record results. The list is not paginated. Requires automations:read.

Parameters

idstring · path · required

Identifier of the automation rule whose backtests to list (prefix aut_).

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Backtests, newest first

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X GET "$BUSINESS_API/automations/{id}/backtests" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Backtests, newest first

Dry-run a rule over a past window

Logs

POST /automations/{id}/backtests

Dry-run a rule over a past window; posts nothing

Replays the rule's trigger and conditions over records from a past window and stores the result, without running any action. from and to are required, to must be after from, and the window is at most 366 days; limit caps the recorded results (default 100, at most 1000). Schedule rules cannot be backtested (400). The call answers 202 with the finished backtest; a scan error is reported in the backtest as status failed rather than as an HTTP error.

Parameters

idstring · path · required

Identifier of the automation rule to backtest (prefix aut_).

Body application/json

fromstring (date-time) · required
tostring (date-time) · required
limitinteger · optional

Returns

202 Backtest result

Errors 400

Permissions automations:read · Roles: admin, analyst, customer_service, finance, operations, owner

curl -X POST "$BUSINESS_API/automations/{id}/backtests" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "from": "2026-11-19T09:30:00Z",
  "to": "2026-11-19T09:30:00Z",
  "limit": 25
}'
Response 202

Backtest result