---
title: "Enroll a contact in a sequence"
method: POST
path: "/sequences/enroll"
tags: ["Sequences"]
---

# Enroll a contact in a sequence

`POST /sequences/enroll`

## Request

- Base URL: `https://www.sagaris.ai/api/v1`
- URL: `https://www.sagaris.ai/api/v1/sequences/enroll`
- Auth: HTTP bearer

Enroll a workspace-owned contact into a workspace-owned email sequence. The sequence must carry an applied approval whose authorized audience covers the contact (PRD §29: approval cannot be bypassed via the API); otherwise the request is rejected with 409. Requires the sequences.write scope.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `sequence_id` string, required: A sequence in the key's workspace.
  - `contact_id` string, required: A contact in the key's workspace.

## Response `201`

The created enrollment.

- object
  - `data` SequenceEnrollment, required
    - `id` string
    - `sequence_id` string
    - `contact_id` string
    - `workspace_id` string
    - `status` string
    - `current_step` integer
    - `enrolled_at` string, date-time, nullable
  - `error` unknown, required

## Other responses

- `400`: Invalid JSON body or field validation failure.
- `401`: Missing, malformed, invalid, revoked, or expired API key.
- `403`: The key does not hold the required scope for this operation.
- `404`: The sequence or contact was not found in the key's workspace.
- `409`: The sequence has no applied approval (`sequence_not_authorized`), or the contact is outside the applied approval's authorized audience (`contact_not_authorized`). Enrollment through the API cannot bypass approval (PRD §29).
- `429`: Per-key write rate limit exceeded (60 requests / 60s).
- `500`: Lookup or insert failure.
- `503`: The database / API-keys table is not provisioned.

---

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