---
title: "Push sequence definition"
method: PUT
path: "/sequences/definitions/{key}"
tags: ["Sequences"]
---

# Push sequence definition

`PUT /sequences/definitions/{key}`

## Request

- Base URL: `https://api.sequenzy.com/api/v1`
- URL: `https://api.sequenzy.com/api/v1/sequences/definitions/{key}`
- Auth: HTTP bearer

Creates the sequence with this key, or updates it to match the document. Steps are matched by key: new keys are added, changed steps are updated in place, and missing steps are removed, with waiting contacts moved to the following step (or completed when nothing follows). A push never turns a sequence on or off or pauses it; new sequences start as drafts.

## Path parameters

- `key` string, required

## Query parameters

- `dryRun` boolean
- `confirmLiveChange` boolean

## Request body

- SequenceDefinition: A whole sequence as one document, addressed by keys you choose. In the readable format (no `connections`), `trigger` starts the sequence and `steps` run in order, with branch and split paths nesting their own steps and an implicit end. In the explicit format, every step has a `type` and `config` and `connections` wire them. On PUT, omitted settings keep their stored values while the steps replace the stored graph.
  - `key` string: Your key for the sequence. Optional on PUT (the URL key is used); must match the URL when present. Empty on GET for a sequence that has no key yet.
  - `id` string: Read-only sequence ID. On PUT, adopts that existing sequence when it has no key yet.
  - `name` string, required
  - `description` string, nullable
  - `managedBy` 'code' | 'dashboard': `code` makes steps and settings read-only in the dashboard while on/off, pause and test sends stay available. New sequences default to `code`; existing ones keep their value when omitted. Marketer personal keys cannot change it on an existing sequence. Not returned on GET, so a pulled document pushed back never changes it.
  - `status` string: Informational. Pushes accept and ignore it, and never change status.
  - `settings` SequenceDefinitionSettings
    - `enrollmentMode` 'unlimited' | 'one_time' | 'matching_field'
    - `enrollmentFieldPath` string, nullable
    - `userCancellable` boolean
    - `activeSubscribersOnly` boolean
    - `sendToNotSubscribed` boolean, nullable: Whether marketing emails also go to contacts whose status is `not_subscribed`. `null` uses the default for the trigger (`true` for `ecommerce.checkout_started`, `false` otherwise). Omit it to keep the stored value.
    - `frequencyCapEnabled` boolean
    - `sendingWindow` object, nullable
    - `stopCondition` object
      - `type` string, required
      - `value` string, nullable
      - `matchConfig` object, nullable
    - `bccEmails` string[], nullable
    - `senderProfileId` string, nullable: Must be a sender profile in this company.
    - `replyProfileId` string, nullable: Must be a Reply-To profile in this company.
  - `trigger` object: Readable format only, and required there. Use one of event (with optional where property filters), tag, list, segment, manual: true, or type and config.
    - `key` string: Defaults to trigger.
    - `label` string
    - `event` string
    - `where` object[]
    - `tag` string
    - `list` string
    - `segment` string
    - `manual` boolean
    - `type` string
    - `config` object
  - `steps` SequenceDefinitionStep[], required
    - `key` string, required: Unique within the sequence. Steps without a key get one based on their content on GET, which a push saves on the existing step.
    - `label` string: Readable format. Shown on the step in the dashboard.
    - `next` string: Readable format. The key of the step that follows, instead of the next listed step.
    - `wait` string: Readable format. A duration such as 1d, 2h 30m or 1w.
    - `branch` SequenceDefinitionPath[]: Readable format. Paths checked in order; the first match wins.
      - `id` string: Lane ID. Defaults to branch-<index>; else is reserved.
      - `label` string
      - `if` SequenceDefinitionCondition: One of tag, notTag, list, segment, event, field with equals, contains, greaterThan or lessThan, clickedLink (true or a URL fragment), hasPhone, smsSubscribed, hasPushDevice, or the stored conditionType with its fields.
      - `percent` number: Split paths only.
      - `steps` SequenceDefinitionStep[]
    - `else` SequenceDefinitionStep[]: Readable format. Required with branch; [] continues straight on.
    - `split` SequenceDefinitionPath[]: Readable format. Random paths, each with a percent.
      - `id` string: Lane ID. Defaults to branch-<index>; else is reserved.
      - `label` string
      - `if` SequenceDefinitionCondition: One of tag, notTag, list, segment, event, field with equals, contains, greaterThan or lessThan, clickedLink (true or a URL fragment), hasPhone, smsSubscribed, hasPushDevice, or the stored conditionType with its fields.
      - `percent` number: Split paths only.
      - `steps` SequenceDefinitionStep[]
    - `continueIf` SequenceDefinitionCondition: One of tag, notTag, list, segment, event, field with equals, contains, greaterThan or lessThan, clickedLink (true or a URL fragment), hasPhone, smsSubscribed, hasPushDevice, or the stored conditionType with its fields.
    - `tag` string: Readable format. Adds this tag.
    - `untag` string: Readable format. Removes this tag.
    - `end` boolean: Readable format. true ends the sequence at this step.
    - `type` string: Node type, for example trigger_event, logic_delay, action_email, logic_branch, or action_webhook with config.isEndNode true for the end. The type of an existing key cannot change, except between trigger types.
    - `config` object: The step's node config. Unknown fields are ignored with a warning; invalid values are rejected. emailId and the legacy trigger active flag are managed by Sequenzy. Webhook header values read as [REDACTED] and keep their stored value when pushed back unchanged.
    - `email` object: Email steps only. Required for a new email step, with a subject or a template; omit to keep the stored content.
      - `template` string: ID of an email in your company. Supplies the subject, preview text, content and style for any of those the step does not write. The step keeps its own copy, refreshed from the template on every push.
      - `name` string
      - `subject` string
      - `previewText` string, nullable
      - `blocks` object[]: Email blocks. GET always returns blocks.
      - `html` string: Shortcut for a single HTML block. Use either blocks or html.
  - `connections` SequenceDefinitionConnection[]: Explicit format only. Leave it out to use the readable format.
    - `from` string, required: Step key.
    - `to` string, required: Step key.
    - `condition` object: Branch lane, for example {"branchId":"else"} on a logic_branch step.

## Response `200`

Sequence updated, unchanged, or previewed with dryRun

- SequenceDefinitionPushResult
  - `success` boolean
  - `dryRun` boolean
  - `created` boolean
  - `hasChanges` boolean
  - `sequence` object
    - `id` string
    - `key` string
    - `name` string
    - `status` string
    - `managedBy` 'code' | 'dashboard'
  - `changes` object
    - `sequence` string[]: Changed sequence fields, such as name or settings.sendingWindow.
    - `steps` object
      - `added` string[]
      - `changed` object[]
        - `key` string
        - `fields` string[]
      - `removed` object[]
        - `key` string
        - `type` string
        - `contacts` integer: Contacts waiting on the step.
        - `contactsContinueTo` string, nullable: Step key those contacts continue to; null when they complete.
    - `connections` object
      - `added` object[]
        - `from` string
        - `to` string
      - `removed` object[]
        - `from` string
        - `to` string
  - `warnings` string[]
  - `error` string

## Other responses

- `201`: Sequence created as a draft
- `400`: Invalid document (unknown field, duplicate step key, broken graph, a step that changed type, a new or removed A/B test step, a changed inbound webhook trigger, an event attachment without an event trigger, a value over its length limit, a profile from another company), or an active sequence pushed without confirmLiveChange
- `401`: Unauthorized
- `404`: The key belongs to a sequence your role cannot see, or the id to adopt was not found
- `409`: The sequence changed while the push was prepared, a contact was being processed on a removed step, or another push took the key. Push again.

## Changes

- **2026-11-14** `e5af1fb27c8d`: 1 info
  - added the new optional request property `settings/sendToNotSubscribed`
- **2026-11-06** `9a2691057391`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sequenzy/apis/sequenzy-api/changes/sequences/definitions/:key/put.md)

---

[API](https://skmtc.dev/sequenzy/apis/sequenzy-api.md) - [All operations](https://skmtc.dev/sequenzy/apis/sequenzy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sequenzy/apis/sequenzy-api/revisions/e5af1fb27c8d?raw)
