---
title: "Update an automation rule"
method: PATCH
path: "/companies/{company}/automations/rules/{rule}"
tags: ["Automations"]
---

# Update an automation rule

`PATCH /companies/{company}/automations/rules/{rule}`

## Request

- Base URL: `https://api.factuarea.com/v1`
- URL: `https://api.factuarea.com/v1/companies/{company}/automations/rules/{rule}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Partially update an automation rule: omitted fields keep their value, and `""` in `description` clears it.
- Every edit seals a NEW version and bumps `current_version`; past runs keep their original definition.
- The status is unchanged: an active rule stays active.

## Path parameters

- `company` string, uuid, required
- `rule` string, uuid, required

## Headers

- `Idempotency-Key` string
- `Factuarea-Version` string, date

## Request body

- UpdateAutomationRuleV1Request
  - `name` string: New human-readable name. Omit it to keep the current one; it cannot be sent empty.
  - `description` string, nullable: New description. Send it empty to clear the current one; omit it to keep it.
  - `scope` 'empresa' | 'cartera' | 'null', nullable: Scope of the automation. It is immutable: send it to state the one the rule already has, or omit it. Sending a different one is rejected and the rule is left untouched.
  - `trigger_type` string: New trigger, in `resource.action` form. Omit it to keep the current one. Must belong to the catalog visible to the company.
  - `conditions` object: New condition tree. An empty object means "no condition" (the rule runs on every event); omit the key to keep the current conditions.
  - `actions` AutomationActionInput[]: New ordered list of actions, replacing the current ones. Omit it to keep them.
    - `type` 'notify_in_app' | 'notify_channel' | 'emit_webhook' | 'create_calendar_event' | 'send_document_email' | 'send_payment_reminder' | 'change_status' | 'tag_entity' | 'create_task' | 'change_task_status' | 'assign_task' | 'add_task_comment', required: Kind of action to run. Must be one of the action types `GET /v1/companies/{company}/automations/catalog` reports as registered.
    - `order` integer: Position of the action within the sequence, starting at 0. Omit it (or send `null`) and the action takes position 0.
    - `parameters` object: Parameters of the action, whose accepted keys depend on `type`. The schema of each action type is published by `GET /v1/companies/{company}/automations/catalog`.

## Response `200`

- object
  - `data` AutomationRule, required: An automation rule: the event it listens to, the condition tree that decides whether to act, and the ordered actions to run when an event matches. Delivered as the `data.object` of the `automation_rule.*` webhook events, captured at emission time and frozen there.
    - `id` string, uuid, required: Opaque identifier of the automation rule, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).
    - `object` 'automation_rule', required: Always `automation_rule`.
    - `name` string, required: Name the account owner gave the automation.
    - `description` string, nullable, required: Free-form description of what the automation is for, or `null`.
    - `trigger_type` string, required: Event the automation listens to, in `resource.action` form (e.g. `invoice.paid`). It is one of the event types returned by `GET /v1/event-catalog`.
    - `scope` 'empresa' | 'cartera', required: Which tax IDs the automation watches: `empresa` (the default, and the scope of every rule created before portfolio automations existed) watches only the events of the company that owns it, while `cartera` is reserved for the titular company of an account with the gestoría module and watches the events of the other tax IDs the account operates (its own and those another account lets it operate), delivering the notices to the titular itself. It is fixed when the rule is created and cannot be changed afterwards, so a run stays attributable to the scope it executed under.
    - `conditions` object, required: Condition tree of the current version that decides whether an incoming event triggers the actions. An empty object `{}` means the automation has no condition and always acts. Its shape is defined by the account owner (nested combinators over the fields of the trigger payload), so it is returned verbatim.
    - `actions` object[], required: Actions of the current version, in the order the account owner declared them. Each element carries its action type and its frozen parameters. An empty array means the version declares no action.
    - `status` 'draft' | 'active' | 'paused', required: State of the automation: `draft` (not listening yet), `active` (listening) or `paused` (not listening; either paused by a person or auto-paused by the platform after a streak of failures).
    - `current_version` integer, required: Number of the current version of the definition. Editing an automation creates a new version instead of mutating the previous one, so every run keeps a pointer to the exact definition it executed.
    - `created_at` string, date-time, nullable, required: When the automation was created (ISO 8601).
    - `updated_at` string, date-time, nullable, required: When the automation was last modified (ISO 8601).

## Other responses

- `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). `company_inactive`: the company in the path is deactivated; reactivate it to operate.
- `404`: The requested resource does not exist or belongs to another company. `profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test).
- `422`: Validation failed. The `error.param` field identifies which input is invalid. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)