---
title: "sequence.add"
method: POST
path: "/sequence.add"
tags: ["Sequence"]
---

# sequence.add

`POST /sequence.add`

> Beta
>
> This endpoint is in beta and may not be available for all organizations.

Enrolls a candidate in a reusable sourcing sequence. Set start to false to create an editable draft, or true to validate and start the sequence immediately.

The optional applicationId fixes the application used for token resolution. The optional from.email must be a Primary, PersonalAlias, or OrganizationAlias address returned by emailSender.list for the same acting user. `NoReply` is never accepted, even when returned by emailSender.list. This excludes both Ashby's no-reply address and custom-domain no-reply addresses sent through Ashby's email infrastructure. Passing any no-reply or otherwise unavailable address returns sequence_sender_not_allowed. Requests made with x-on-behalf-of create a draft owned by that user.

If validation errors or required actions block an immediate start, the sequence is returned as NotStarted with a structured Blocked startResult. If a draft already exists for the same candidate, template, and acting user, sequence_draft_already_exists includes its id in errorInfo.meta.existingSequenceId.

**Requires the [`sourcingWrite`](authentication#permissions-sequenceadd) permission.**

## Request body

- SequenceAddRequest
  - `sequenceTemplateId` string, uuid, required — The reusable sourcing sequence template to use
  - `candidateId` string, uuid, required — The candidate to enroll in the sequence
  - `applicationId` string, uuid — The candidate's application to use for token resolution
  - `from` object — The sending address to use for every email stage
    - `email` string, email, required — A Primary, PersonalAlias, or OrganizationAlias address returned by emailSender.list for the same acting user. NoReply addresses are always rejected, including Ashby and custom-domain no-reply addresses.
  - `start` boolean, required — Whether to validate and start the sequence immediately after creating it

## Response `200`

Responses from the sequence.add endpoint

- union
  - SequenceAddSuccessResponse
    - `success` true, required
    - `results` SequenceAddResult, required
      - `sequence` Sequence, required
        - `id` string, uuid, required — The unique identifier for this candidate's sequence enrollment
        - `candidateId` string, uuid, required — The candidate enrolled in the sequence
        - `applicationId` string, uuid, nullable, required — The application selected for token resolution, when one is available
        - `sequenceTemplateId` string, uuid, required — The reusable sequence template used for enrollment
        - `status` 'NotStarted' | 'Running' | 'Paused' | 'Completed' | 'Cancelled' | 'Unsubscribed', required
        - `createdAt` string, date-time, required — When the sequence enrollment was created
        - `stages` SequenceStage[], required — The stages in sequence order
          - `id` string, uuid, required — The unique identifier for this sequence stage
          - `type` 'Email' | 'InMail' | 'LinkedInConnection', required
          - `from` SequenceSender
            - `email` string, email, required — The address used to send this stage
            - `displayName` string, nullable, required — The sender display name configured by Ashby, when one is available
          - `subject` string — The resolved subject for an editable, not-started email stage
          - `bodyHtml` string — The editable HTML body for a not-started email stage. Ashby token markers must be preserved when editing.
          - `sendAfter` union, required — The delay before this stage is sent
            - object
              - …
            - object
              - …
            - object
              - …
      - `startResult` SequenceStartResult, required
        - `status` 'Started' | 'Blocked', required
        - `lintResult` SequenceLintResult, required
          - `info` string[], required — Informational validation messages
          - `warnings` SequenceLintIssue[], required — Non-blocking validation issues
            - `type` string, required — The stable machine-readable issue type. Clients should tolerate types added in the future.
          - `errors` SequenceLintIssue[], required — Validation issues that block starting
            - `type` string, required — The stable machine-readable issue type. Clients should tolerate types added in the future.
          - `requiredActions` SequenceLintIssue[], required — Actions that must be completed before starting
            - `type` string, required — The stable machine-readable issue type. Clients should tolerate types added in the future.
  - ErrorResponse
    - `success` false, required
    - `errors` ErrorDetail[], required
      - `message` string, required
      - `parameter` string

---

[API](https://skmtc.net/ashbyhq/apis/ashby-api.md) · [All operations](https://skmtc.net/ashbyhq/apis/ashby-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ashbyhq/ashby-api/revisions/778b919dc743/schema)