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

# Create an automation rule

`POST /companies/{company}/automations/rules`

## Request

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

Create an automation rule from a trigger, an optional condition tree and an ordered list of actions; the server assigns the `id`.
- It is created in `draft` and does not fire until activated via `POST /v1/companies/{company}/automations/rules/{rule}/activate`.
- A trigger outside your catalog or an action without adapter returns 422.

## Path parameters

- `company` string, uuid, required

## Headers

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

## Request body

- CreateAutomationRuleV1Request
  - `name` string, required: Human-readable name of the automation rule.
  - `description` string, nullable: Free-form description for whoever maintains the rule. It has no effect on execution.
  - `scope` 'empresa' | 'cartera' | 'null', nullable: Scope of the automation: `empresa` (the default) watches only your own company, `cartera` (only for the titular company of an account with the gestoría module) watches the other tax IDs your account operates and delivers its notices to you. Omit it to keep the current behaviour. It cannot be changed afterwards.
  - `trigger_type` string, required: Trigger that puts the rule in motion, in `resource.action` form (for example `invoice.paid`). Must belong to the catalog visible to the company.
  - `conditions` object: Condition tree evaluated against the triggering event. Either a single condition (`field`, `operator`, `value`) or a group (`combinator`, `children`). Omit it to run the rule on every event of its trigger.
  - `actions` AutomationActionInput[], required: Ordered list of actions the rule executes. At least one, each with a registered adapter.
    - `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 `201`

- 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).
- `409`: The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.
- `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)