# Create and manage automations

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Every page is available as Markdown by adding .md to its URL.

> Create and manage automations and automation action executions in Rippling using the API.

Source: https://developer.rippling.com/documentation/rest-api/guides/workflows

## Overview

An automation is a named automation with a trigger and one or more actions (or steps). Triggers include schedule kinds (daily, weekly, etc.), business events, Slack notifications, and inbound emails. The create endpoint currently supports `registered_callback` actions.

*Key terms:*

- **Trigger**: What starts the automation. Each automation has one trigger, and the [`kind`](#trigger-kinds) field selects the trigger type.
- **Action**: Work the automation runs. This API writes `registered_callback` actions only. An automation can have 1 to 160 actions.
- **Version**: `version_id` identifies the current definition. Send it on every update.
- **Authoring**: The `authoring` object on a retrieved automation. It reports whether you can change the definition, the metadata, or neither, and lists the fields an update can change.
- **Status**: `draft` or `published` when you write an automation. A read can also return `unknown`.
- **Enabled**: Whether a published automation is active. `enabled: true` requires `status: published`.

### Available endpoints

| Endpoint | Description |
|-----------|-----------|
| [GET List workflows](https://developer.rippling.com/documentation/rest-api/reference/list-workflows.md) | Returns a paginated list of automation summaries. |
| [POST Create a workflow](https://developer.rippling.com/documentation/rest-api/reference/create-workflows.md) | Creates an automation with a trigger and at least one action. Defaults to `draft` and `enabled: false`. |
| [GET Retrieve a workflow](https://developer.rippling.com/documentation/rest-api/reference/get-workflows.md) | Returns the full definition, `version_id`, and `authoring` capabilities. |
| [PATCH Update a workflow](https://developer.rippling.com/documentation/rest-api/reference/update-workflows.md) | Applies changes to the current version. Requires `version_id` to avoid a 409 conflict. |
| [DELETE Delete a workflow](https://developer.rippling.com/documentation/rest-api/reference/delete-workflows.md) | Removes the automation when `deletable` is `true`. |
| [POST Execute a workflow action from Rippling Functions](https://developer.rippling.com/documentation/rest-api/reference/workflow-action-executions) | Executes a supported action such as `run_query` against an automation definition. |

### Suggested workflow

1. [Create an automation](https://developer.rippling.com/documentation/rest-api/reference/create-workflows.md) with a trigger and at least one `registered_callback` action. It starts as `draft` with `enabled: false`. Keep the returned `id`.
2. [Retrieve the automation](https://developer.rippling.com/documentation/rest-api/reference/get-workflows.md) by `id`. Keep `version_id`, and check `authoring` for which fields you can change.
3. [Update the automation](https://developer.rippling.com/documentation/rest-api/reference/update-workflows.md) to change the trigger, actions, name, or publish state. Send the current `version_id` on every update.
4. Publish the automation, then set `enabled: true` so it can run. `enabled: true` requires `status: published`.
5. [List automations](https://developer.rippling.com/documentation/rest-api/reference/list-workflows.md) to find automations across the company.
6. [Delete an automation](https://developer.rippling.com/documentation/rest-api/reference/delete-workflows.md) by `id` when `deletable` is `true`.
7. [Execute an automation action](https://developer.rippling.com/documentation/rest-api/reference/workflow-action-executions) from a Rippling Function when you need to run a supported action, such as `run_query`, against the automation definition.

### Trigger `kinds`

Every trigger requires `kind`, and any schedule triggers also require a `timezone`.

| `kind` | Required besides `kind` | Other fields |
| ----- | ----- | ----- |
| `daily_schedule` | `timezone`, `hour` | `minute` (0–59, default 0). `hour` is 0–23. |
| `weekday_schedule` | `timezone`, `hour` | `minute` (0–59, default 0). `hour` is 0–23. |
| `weekly_schedule` | `timezone`, `hour`, `days_of_week` | `minute` (0–59, default 0). `days_of_week` is an array of integers. The spec does not document the day numbering. |
| `biweekly_schedule` | `timezone`, `hour`, `days_of_week` | `minute` (0–59, default 0). |
| `monthly_schedule` | `timezone`, `hour`, `day_of_month` | `minute` (0–59, default 0). `day_of_month` is 1–31. |
| `monthly_on_day_of_week_schedule` | `timezone`, `hour`, `day_of_week`, `week_of_month` | `minute` (0–59, default 0). `day_of_week` is 0–6. `week_of_month` is 1–4. |
| `quarterly_schedule` | `timezone`, `hour`, `month_of_year`, `day_of_month` | `minute` (0–59, default 0). `month_of_year` is 1–12. `day_of_month` is 1–31. |
| `annual_schedule` | `timezone`, `hour`, `month_of_year`, `day_of_month` | `minute` (0–59, default 0). `month_of_year` is 1–12. `day_of_month` is 1–31. |
| `one_time_schedule` | `timezone`, `hour`, `year`, `month_of_year`, `day_of_month` | `minute` (0–59, default 0). `year` is 1–9999. `month_of_year` is 1–12. `day_of_month` is 1–31. |
| `custom_schedule` | `timezone`, `unit`, `interval` | `unit` is `minutes`, `hours`, `days`, `weeks`, `months`, or `years`. `interval` is at least 1. Optional: `hour` (default 0), `minute` (default 0), `days_of_week`, `day_of_month`, `month_of_year`, `start_month`. |
| `cron_schedule` | `timezone`, `expression` | |
| `business_event` | `event_name` | |
| `slack` | `event_type`, `channel_ids` | `event_type` is `message_posted` or `reaction_added`. `channel_ids` needs at least one entry. Optional: `allowed_sender_group_id`, `message_text_regex` (max 512 characters), `reaction_names`, `include_thread_replies` (default `false`). |
| `inbound_email` | `recipient_email` | Optional: `subject_contains`, `body_contains`, `has_attachment` (default `false`). |

---

## Requirements

- Access to Rippling automations.
- An API token with the following scopes:
  - `workflows.read` **or** `workflows.read-write` to list/retrieve automations
  - `workflows.read-write` to create/update/delete automations
  - `workflows-action-executions.read-write` to execute an action from Functions

---

## Fetch

Use [GET List workflows](https://developer.rippling.com/documentation/rest-api/reference/list-workflows.md) to return a paginated list of automations.

*Request:*

```json
curl -L -X GET 'https://rest.ripplingapis.com/workflows/?limit=50'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
```

*Response:*

```json
{
  "results": [
    {
      "id": "68c1f2a09b1c4e0012ab34cd",
      "version_id": "v_01JEXAMPLE",
      "name": "Daily headcount digest",
      "description": "Posts a daily summary to a registered callback.",
      "status": "published",
      "enabled": true,
      "owner_id": "58d3a1f0e4b0a12c3d456789",
      "created_at": "2026-03-17T21:37:32.953000+00:00",
      "updated_at": "2026-03-18T09:00:00.000000+00:00"
    }
  ],
  "next_link": null
}
```

Use [GET Retrieve a workflow](https://developer.rippling.com/documentation/rest-api/reference/get-workflows.md) when you need the full definition, `version_id`, and whether the automation is editable.

*Request:*

```json
curl -L -X GET 'https://rest.ripplingapis.com/workflows/68c1f2a09b1c4e0012ab34cd/'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
```

---

## Create

### Automations

Use [POST Create a workflow](https://developer.rippling.com/documentation/rest-api/reference/create-workflows.md) to create a new automation.

*Request:*

```json
curl -L -X POST 'https://rest.ripplingapis.com/workflows/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

*Request body:*

```json
{
  "name": "Daily headcount digest",
  "description": "Posts a daily summary to a registered callback.",
  "status": "draft",
  "enabled": false,
  "trigger": {
    "kind": "daily_schedule",
    "timezone": "America/Los_Angeles",
    "hour": 9,
    "minute": 0
  },
  "actions": [
    {
      "kind": "registered_callback",
      "id": "headcount_digest_callback",
      "owner_type": "APP",
      "owner_id": "custom_app_id",
      "implementation_config": "{\"url\":\"https://example.com/webhooks/headcount\"}"
    }
  ]
}
```

| Request body field | Required | Rule |
| ----- | -------- | ---- |
| `name` | Yes | 1 to 150 characters. |
| `trigger` | Yes | One trigger object. |
| `actions` | Yes | 1 to 160 actions. |
| `description` | No | Up to 3,000 characters. |
| `status` and `enabled` | No | A draft cannot be enabled. Set `status` to `published` if you also send `enabled: true`. |

*Response:*

```json
{
  "id": "68c1f2a09b1c4e0012ab34cd",
  "version_id": "v_01JEXAMPLE",
  "name": "Daily headcount digest",
  "description": "Posts a daily summary to a registered callback.",
  "status": "draft",
  "enabled": false,
  "owner_id": "58d3a1f0e4b0a12c3d456789",
  "has_draft": true,
  "deletable": true,
  "created_at": "2026-03-17T21:37:32.953000+00:00",
  "updated_at": "2026-03-17T21:37:32.953000+00:00"
}
```

### Automation action executions

Use [POST Execute a workflow action from Rippling Functions](https://developer.rippling.com/documentation/rest-api/reference/workflow-action-executions) to run a supported action from a function. The request requires `action_type`, `payload`, and `workflow_definition_id`.

*Request:*

```json
curl -L -X POST 'https://rest.ripplingapis.com/workflow-action-executions/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

*Request body:*

```json
{
  "action_type": "run_query",
  "workflow_definition_id": "68c1f2a09b1c4e0012ab34cd",
  "payload": {
    "query": "SELECT id, name FROM Employee LIMIT 10",
    "product_name": null
  }
}
```

---

## Update

Use [PATCH Update a workflow](https://developer.rippling.com/documentation/rest-api/reference/update-workflows.md) to modify an existing automation. Send the current `version_id` on every uodate, and if the automation changed elsewhere first, the API will return a `409` with `WORKFLOW_VERSION_CONFLICT`.

Draft automations cannot be enabled, so set `status` to `published` if you also send `enabled: true`. Before patching a trigger or actions, check the `authoring` capabilities on the retrieved automation.

*Request:*

```json
curl -L -X PATCH 'https://rest.ripplingapis.com/workflows/68c1f2a09b1c4e0012ab34cd/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

*Request body:*

```json
{
  "version_id": "v_01JEXAMPLE",
  "status": "published",
  "enabled": true
}
```

---

## Delete

Use [DELETE Delete a workflow](https://developer.rippling.com/documentation/rest-api/reference/delete-workflows.md) to remove an automation that is marked `deletable`.

*Request:*

```json
curl -L -X DELETE 'https://rest.ripplingapis.com/workflows/68c1f2a09b1c4e0012ab34cd/'
-H 'Accept: application/json'
-H 'Authorization: Bearer REDACTED'
```

A successful delete returns `200` and no response body.

---

## See also

- [Get started with the Developer API](https://developer.rippling.com/documentation/rest-api/guides/dev-getting-started.md)
- [Get started with automations](https://developer.rippling.com/documentation/rippling-platform/developer/workflows/get-started.md)
- [API tokens and permissions](https://developer.rippling.com/documentation/rest-api/essentials/api-tokens.md)