curl --request POST \
  --url https://core-api.getaptly.com/api/board/{boardId}/configuration/automations \
  --header 'Content-Type: application/json' \
  --header 'x-token: <api-key>' \
  --data '
{
  "title": "Tour follow-up",
  "trigger": {
    "type": "stage",
    "stage": "Tour Scheduled"
  },
  "timing": {
    "mode": "after",
    "amount": 2,
    "unit": "days",
    "timeOfDay": 9
  },
  "actions": [
    {
      "type": "email",
      "inbox": "assignee",
      "templateId": "5kQx2mP9",
      "to": {
        "type": "relatedContacts"
      }
    }
  ]
}
'

{
  "data": {
    "uuid": "<string>",
    "title": "<string>",
    "archived": true,
    "triggerOn": "<string>",
    "timingMode": "<string>",
    "description": "<string>",
    "actions": [
      {}
    ]
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields are invalid",
    "meta": {
      "issues": [
        {
          "field": "to.0.value",
          "code": "invalid_format",
          "message": "must be a valid email address"
        }
      ]
    }
  },
  "requestId": "<string>"
}

Board

Create an automation

Creates an Automation on the board (the board’s workflows). Requires update permission and the key’s “Automations” access (a separate toggle on the key, off by default, independent of “Edit Boards”); a key’s board allowlist applies.

Always created paused. Nothing runs until the automation is switched on in the Aptly app, so the API can’t set one live. Existing cards are not enrolled: once it is switched on a stage automation applies to cards that enter the stage afterwards.

Validated strictly - the request is refused outright on the first problem. Unknown properties, a stage / field / template / inbox / contact type / user / team that doesn’t exist (or is archived) on this board or organization, an email template used for an SMS (or the reverse), an inbox of the wrong type or with no users, conditions that are empty, on a missing field, with an unsupported operator or a bad value, a delay with business hours, or a task or due-date action with business days, when none are configured, a webhook to anything but a public https address, and a pair of stage-moving automations that would send cards round in a circle are all rejected with 400. Shape problems come back as VALIDATION_ERROR with the offending path in meta.issues; problems found by checking against your data come back as INVALID_DATA with a message that names the path (for example actions[1].templateId: template "abc" was not found).

Supported triggers: stage, segment (conditions), reply. Supported actions: email, sms, task, assign, update_fields, stage, due_date, notify, archive, archive_convos, webhook. Task-completion and field-group triggers and the Yardi, e-sign, PDF, team-access and related-card actions aren’t available through the API.

The response is the stored automation (the same shape GET .../automations returns).

POST

api

board

{boardId}

configuration

automations

curl --request POST \
  --url https://core-api.getaptly.com/api/board/{boardId}/configuration/automations \
  --header 'Content-Type: application/json' \
  --header 'x-token: <api-key>' \
  --data '
{
  "title": "Tour follow-up",
  "trigger": {
    "type": "stage",
    "stage": "Tour Scheduled"
  },
  "timing": {
    "mode": "after",
    "amount": 2,
    "unit": "days",
    "timeOfDay": 9
  },
  "actions": [
    {
      "type": "email",
      "inbox": "assignee",
      "templateId": "5kQx2mP9",
      "to": {
        "type": "relatedContacts"
      }
    }
  ]
}
'

{
  "data": {
    "uuid": "<string>",
    "title": "<string>",
    "archived": true,
    "triggerOn": "<string>",
    "timingMode": "<string>",
    "description": "<string>",
    "actions": [
      {}
    ]
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields are invalid",
    "meta": {
      "issues": [
        {
          "field": "to.0.value",
          "code": "invalid_format",
          "message": "must be a valid email address"
        }
      ]
    }
  },
  "requestId": "<string>"
}

Authorizations

x-token

string

header

required

Path Parameters

boardId

string

required

The board's UUID.

Body

application/json

title

string

required

Maximum string length: 200

trigger

object

required

What starts the automation. Exactly one type.

Option 1
Option 2
Option 3

Show child attributes

actions

object[]

required

Required array length: 1 - 10 elements

One thing the automation does. Actions run in order. At most one stage, one due_date and one archive action per automation. Every id, stage and field named here must exist on the board / organization or the whole request is rejected.

Show child attributes

timing

object

When the actions run after the trigger. Defaults to { "mode": "now" }. A trigger with frequency: once can only use now or after. Times of day are hours (0-23) in the organization's time zone, and the automation fires within four hours after that time.

Show child attributes

Response

The created automation (paused).

data

object

The stored automation. archived: true means paused.

Show child attributes