> ## Documentation Index > Fetch the complete documentation index at: https://docs.getaptly.com/llms.txt > Use this file to discover all available pages before exploring further. # 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). ## OpenAPI ````yaml /openapi.yaml post /api/board/{boardId}/configuration/automations openapi: 3.0.3 info: title: Aptly API version: '1.1' description: | The Aptly API lets external systems work with boards, contacts, inboxes, tasks, files, and other Aptly resources. Most endpoints accept an API key in the `x-token` header. Some endpoints also accept a delegate token or partner bearer token, as shown in each operation's security requirements, and explicitly public endpoints require no credential. API keys are scoped to a company and may be restricted to specific boards and read, insert, or update permissions; requests outside those restrictions receive a 403 `FORBIDDEN` response. servers: - url: https://core-api.getaptly.com description: Production security: - ApiKeyHeader: [] paths: /api/board/{boardId}/configuration/automations: post: tags: - Board summary: Create an automation description: > 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). operationId: createAutomation parameters: - name: boardId in: path required: true schema: type: string description: The board's UUID. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAutomationRequest' examples: emailAfterStage: summary: Email the contact two days after a stage change value: 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 staleLeads: summary: Nudge stale leads on Mondays and Wednesdays value: title: Nudge stale leads trigger: type: segment conditions: - fieldUuid: stage operator: anyIn value: - New Lead - Contacted timing: mode: daysOfWeek days: - 1 - 3 timeOfDay: 8 actions: - type: update_fields fields: - fieldUuid: status value: Needs Follow Up - type: notify teamIds: - 7Hq3dZ message: Stale lead responses: '201': description: The created automation (paused). content: application/json: schema: type: object properties: data: type: object description: 'The stored automation. `archived: true` means paused.' properties: uuid: type: string title: type: string archived: type: boolean example: true triggerOn: type: string timingMode: type: string description: type: string actions: type: array items: type: object '400': description: >- `VALIDATION_ERROR` (shape) or `INVALID_DATA` (a reference or rule that doesn't hold). content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Invalid or missing API key. '403': description: >- The key lacks `update` permission or the "Automations" access, or the board isn't API-enabled. '404': description: Board not found. security: - ApiKeyHeader: [] - PartnerBearer: [] components: schemas: CreateAutomationRequest: type: object additionalProperties: false required: - title - trigger - actions properties: title: type: string maxLength: 200 trigger: $ref: '#/components/schemas/AutomationTrigger' timing: $ref: '#/components/schemas/AutomationTiming' actions: type: array minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/AutomationAction' ValidationError: type: object description: > Returned with HTTP 400 when the request body fails shape validation (wrong type, missing required field, malformed email/phone number, value out of bounds). `meta.issues` lists every offending field. properties: error: type: object properties: code: type: string enum: - VALIDATION_ERROR message: type: string example: One or more fields are invalid meta: type: object properties: issues: type: array items: type: object properties: field: type: string description: >- Dotted path to the offending property (for example `to.0.value`); empty for a problem with the body as a whole. example: to.0.value code: type: string description: >- Machine-readable issue code (for example `invalid_type`, `invalid_format`, `too_small`). example: invalid_format message: type: string example: must be a valid email address requestId: type: string AutomationTrigger: description: What starts the automation. Exactly one `type`. oneOf: - $ref: '#/components/schemas/AutomationStageTrigger' - $ref: '#/components/schemas/AutomationSegmentTrigger' - $ref: '#/components/schemas/AutomationReplyTrigger' discriminator: propertyName: type mapping: stage: '#/components/schemas/AutomationStageTrigger' segment: '#/components/schemas/AutomationSegmentTrigger' reply: '#/components/schemas/AutomationReplyTrigger' AutomationTiming: description: > 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. oneOf: - type: object additionalProperties: false required: - mode properties: mode: type: string enum: - now useBusinessHours: type: boolean default: false description: >- Only fire while the board or organization is open. Rejected when no business hours are configured, because it would never run. - type: object additionalProperties: false required: - mode - amount - unit properties: mode: type: string enum: - after amount: type: integer minimum: 1 maximum: 100000 unit: type: string enum: - minutes - hours - days - months anchor: type: string default: stageUpdatedAt description: >- What the delay counts from - `stageUpdatedAt`, `conditionMet`, `createdAt`, or the uuid of a date field on the board. timeOfDay: type: integer minimum: 0 maximum: 23 description: Only for `days` or `months`. useBusinessHours: type: boolean default: false description: Only for `minutes` or `hours`. - type: object additionalProperties: false required: - mode - day - timeOfDay properties: mode: type: string enum: - dayOfWeek day: type: string enum: - sunday - monday - tuesday - wednesday - thursday - friday - saturday timeOfDay: type: integer minimum: 0 maximum: 23 - type: object additionalProperties: false required: - mode - days - timeOfDay properties: mode: type: string enum: - daysOfWeek days: type: array minItems: 1 maxItems: 7 description: 0 = Sunday ... 6 = Saturday. No repeats. items: type: integer minimum: 0 maximum: 6 timeOfDay: type: integer minimum: 0 maximum: 23 - type: object additionalProperties: false required: - mode - day - timeOfDay properties: mode: type: string enum: - dayOfMonth day: type: integer minimum: 1 maximum: 31 description: 31 means the last day of the month. timeOfDay: type: integer minimum: 0 maximum: 23 - type: object additionalProperties: false required: - mode - startDay - endDay - timeOfDay properties: mode: type: string enum: - dateRange startDay: type: integer minimum: 1 maximum: 31 endDay: type: integer minimum: 1 maximum: 31 description: Must be after startDay. timeOfDay: type: integer minimum: 0 maximum: 23 - type: object additionalProperties: false required: - mode - interval properties: mode: type: string enum: - everyXDays interval: type: integer minimum: 1 maximum: 365 startImmediately: type: boolean default: true timeOfDay: type: integer minimum: 0 maximum: 23 discriminator: propertyName: mode AutomationAction: description: > 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. oneOf: - type: object additionalProperties: false required: - type - inbox - templateId - to description: Send an email. properties: type: type: string enum: - email inbox: type: string description: >- The sending inbox id, or "assignee" for the card assignee's inbox. Must be an active email inbox with users. templateId: type: string description: An active email template of the organization. to: $ref: '#/components/schemas/AutomationRecipient' cc: type: array maxItems: 10 default: [] items: type: string format: email deliveryMode: type: string enum: - multiple - single default: multiple description: >- `single` sends one email to all recipients; `multiple` sends each their own. fallback: type: object additionalProperties: false required: - inbox - templateId description: >- Send an SMS instead to recipients with no email address. Needs an active phone inbox and an SMS template. properties: inbox: type: string templateId: type: string - type: object additionalProperties: false required: - type - inbox - templateId - to description: Send a text message. properties: type: type: string enum: - sms inbox: type: string description: The sending phone inbox id, or "assignee". templateId: type: string description: An active SMS template of the organization. to: $ref: '#/components/schemas/AutomationRecipient' fallback: type: object additionalProperties: false required: - inbox - templateId description: Send an email instead to recipients with no phone number. properties: inbox: type: string templateId: type: string - type: object additionalProperties: false required: - type - source description: Create tasks on the card, from a task template or defined inline. properties: type: type: string enum: - task source: type: string enum: - template - manual templateId: type: string description: Required for `template`. A task template of this board. tasks: type: array minItems: 1 maxItems: 20 description: Required for `manual`. items: type: object additionalProperties: false required: - title properties: title: type: string maxLength: 200 description: type: string maxLength: 2000 userId: type: string description: >- An active user of the organization. Defaults to the card assignee. dueInDays: type: integer minimum: 0 maximum: 365 dueFrom: type: string description: '"now" (default) or a date field uuid. Needs dueInDays.' fieldUuid: type: string description: >- A task list (checkboxlist) field to put the tasks on. Defaults to the card's checklist. useBusinessDays: type: boolean default: false description: >- Count the tasks' due dates in business days. Rejected when no business hours are configured, because the due dates would fall on calendar days instead. - type: object additionalProperties: false required: - type - mode description: Assign the card. properties: type: type: string enum: - assign mode: type: string enum: - user - team - roundRobin - contactField userId: type: string description: Required for `user`. teamId: type: string description: Required for `team`. An active team. contactFieldUuid: type: string description: >- Required for `contactField`. A contact or user field of the board. onlyIfUnassigned: type: boolean default: false - type: object additionalProperties: false required: - type - fields description: > Set field values. Supported field types and the value each takes: `string`/`text` (text), `email`, `url` (http/https), `tel` (E.164), `number`, `percent` (a fraction, 0.25 = 25%), `money` (`{ amount: whole cents, currency?: "USD" }`), `boolean`, `singleselect` (an option), `multiselect` (array of options), `tags` (added to the existing tags), `user` (a user id), and `date`/`datetime-local` (`{ from: "now" | , days: integer }` or `{ clear: true }`). Read-only and computed fields, and every other field type, are rejected. properties: type: type: string enum: - update_fields fields: type: array minItems: 1 maxItems: 20 description: Each field at most once. items: type: object additionalProperties: false required: - fieldUuid - value properties: fieldUuid: type: string value: {} - type: object additionalProperties: false required: - type - stage description: >- Move the card to a stage of the board. Can't be the stage that triggered a stage automation. properties: type: type: string enum: - stage stage: type: string - type: object additionalProperties: false required: - type description: Set or clear the card's due date. properties: type: type: string enum: - due_date from: type: string default: now description: '"now", "clear", or a date field uuid.' days: type: integer minimum: -366 maximum: 1999 description: Required unless `from` is "clear". useBusinessDays: type: boolean description: >- Count `days` in business days. Not valid when `from` is "clear". Rejected when no business hours are configured, because the due date would fall on calendar days instead. - type: object additionalProperties: false required: - type description: >- Post a notification comment on the card. At least one of userIds, teamIds, fieldUuids or notifyCardCreator is required. properties: type: type: string enum: - notify userIds: type: array maxItems: 25 default: [] items: type: string teamIds: type: array maxItems: 25 default: [] items: type: string fieldUuids: type: array maxItems: 10 default: [] description: User fields of the board. items: type: string notifyCardCreator: type: boolean default: false message: type: string maxLength: 1000 description: Plain text (no < or >). - type: object additionalProperties: false required: - type description: Archive the card. properties: type: type: string enum: - archive - type: object additionalProperties: false required: - type description: Archive the card and its conversations. properties: type: type: string enum: - archive_convos - type: object additionalProperties: false required: - type - url description: >- POST the card to a URL. The URL must be a public https address - localhost, private/internal addresses, credentials and non-default ports are rejected. properties: type: type: string enum: - webhook url: type: string maxLength: 2000 discriminator: propertyName: type AutomationStageTrigger: type: object additionalProperties: false required: - type - stage properties: type: type: string enum: - stage stage: type: string description: >- A stage of the board, spelled exactly as it is on the board (case and spacing included). A stage trigger fires at most once per card. AutomationSegmentTrigger: type: object additionalProperties: false required: - type - conditions properties: type: type: string enum: - segment conditions: type: array minItems: 1 maxItems: 25 description: > Rules a card must meet, ANDed together - the same rule format as board segments (`fieldUuid`, `operator`, `value`, ...; see `GET /api/board/{boardId}/segments`). At least one rule is required, because an automation with no conditions would run on every card. A rule on an unknown field, an operator the field doesn't support, a missing or malformed value, a stage or option that isn't on the board, or a user who isn't in the company is rejected, as are rules on `archived`/`deleted` and `valueSource: currentUser` (an automation runs without a signed-in user). The rules are saved as a segment named `Automation - `. items: type: object frequency: type: string enum: - everyTime - once default: everyTime description: >- `once` fires the first time a card matches; `everyTime` fires again each time it stops and starts matching. AutomationReplyTrigger: type: object additionalProperties: false required: - type properties: type: type: string enum: - reply stages: type: array maxItems: 50 default: [] description: Only fire for cards in these stages. Empty means any stage. items: type: string frequency: type: string enum: - everyTime - once default: everyTime audience: type: string enum: - anyone - relatedContacts default: anyone description: >- `relatedContacts` requires the sender to be a contact related to the card. reopenArchived: type: boolean default: false description: Reopen an archived card when a reply arrives. AutomationRecipient: description: Who an email or SMS goes to. oneOf: - type: object additionalProperties: false required: - type properties: type: type: string enum: - assignee - type: object additionalProperties: false required: - type properties: type: type: string enum: - relatedContacts - type: object additionalProperties: false required: - type - contactTypeIds properties: type: type: string enum: - contactTypes contactTypeIds: type: array minItems: 1 maxItems: 25 description: >- Contact type ids of the organization. Related contacts of these types receive the message. items: type: string - type: object additionalProperties: false required: - type - addresses properties: type: type: string enum: - specific addresses: type: array minItems: 1 maxItems: 25 description: >- Email addresses for an email, E.164 phone numbers (+15551234567) for an SMS. No repeats. items: type: string - type: object additionalProperties: false required: - type - fieldUuid properties: type: type: string enum: - field fieldUuid: type: string description: >- An email, user or contact field of the board (an SMS needs a user or contact field). discriminator: propertyName: type securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-token PartnerBearer: type: http scheme: bearer description: 'Partner token. Format: `Authorization: Bearer <token>`' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.