Sequences

Multi-step automated outreach — email + SMS + tasks — that enrolls a contact and walks them through a sequence of touches.

A sequence is a parent record that holds a list of steps. Enrollments tie a contact into a sequence; the runner advances enrollments based on each step's schedule and the contact's engagement. Manage step definitions through the app UI today — programmatic step CRUD ships in v1.1.

POST/api/sequencesBearer token

Create a sequence

Create a sequence shell. Add steps from the app UI.

Required scopes:sequences.manage

Request body

Name	Type	Description
`name`required	`string`	Sequence display name.
`description`	`string`	Optional description. ≤ 2000 chars.
`active`	`boolean`	Whether the sequence accepts enrollments.

Request body

JSON

{ "name": "Welcome — new patient", "active": true }

Responses

201 CreatedCreated.

example

{
  "id": "seq_2k9d4f…",
  "name": "Welcome — new patient",
  "description": "3-touch onboarding over 10 days.",
  "active": true,
  "stepCount": 3,
  "createdAt": "2026-05-18T14:00:00Z"
}

Code samples

Shell

curl -X POST https://app.contactfollowup.com/api/sequences \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Welcome — new patient", "active": true }'

GET/api/sequencesBearer token

List sequences

List every sequence visible to the caller.

Required scopes:sequences.managecontacts.read

Responses

200 OKSequences.

example

{ "sequences": [{
  "id": "seq_2k9d4f…",
  "name": "Welcome — new patient",
  "description": "3-touch onboarding over 10 days.",
  "active": true,
  "stepCount": 3,
  "createdAt": "2026-05-18T14:00:00Z"
}] }

Code samples

Shell

curl -X GET https://app.contactfollowup.com/api/sequences \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json"

POST/api/sequences/enrollmentsBearer token

Enroll a contact

Place a contact into a sequence. Idempotent on (contactId, sequenceId): re-enrolling a contact does nothing.

Required scopes:sequences.manage

Request body

Name	Type	Description
`sequenceId`required	`string`	Sequence id.
`contactId`required	`string`	Contact id.

Request body

JSON

{ "sequenceId": "seq_2k9d4f…", "contactId": "cln…" }

Responses

201 CreatedEnrolled.

example

{ "id": "enr_x…", "sequenceId": "seq_…", "contactId": "cln…", "status": "ACTIVE", "currentStepIndex": 0 }

409 ConflictAlready enrolled.

Code samples

Shell

curl -X POST https://app.contactfollowup.com/api/sequences/enrollments \
  -H "Authorization: Bearer $HEARTHNOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "sequenceId": "seq_2k9d4f…", "contactId": "cln…" }'