Skip to main content
POST
Create a sequence
Creates a sequence with no steps. It starts disabled, with user_id as its author. Only the author, the team owner or a team admin can change it later.

Build a sequence end to end

  1. Create the sequence with this call.
  2. Create an email template for each email you want to send.
  3. Add steps, in the order they should run.
  4. Add contacts. While the sequence is disabled they wait as pending.
  5. Enable the sequence. Everyone waiting starts.

Example

The response is the new sequence, with enabled: false and sequence_step_count: 0.

Things to know

  • schedule is all or nothing. Send all five fields, or leave schedule out. A partial schedule is refused with 400. Without one, the sequence uses the team’s default schedule, or, when the team has none, Monday to Friday from 8 to 17 in each prospect’s timezone (UTC when it is unknown).
  • sequence_type is fixed once there are steps. interval times each step from the previous one; date gives each step a fixed date. Changing it later is refused with 409.
  • primary_reply_pause_duration is in seconds. One week is 604800.
  • transactional: true skips the suppression list when people are added. Sends still never go to an address suppressed as bounced, complained or do-not-contact. Use it only for mail a recipient asked for.
  • Mailboxes. Leave email_account_ids out to send from the author’s assigned mailboxes, or from the team’s shared ones when the author has none. A member who is not a team admin can only pick shared mailboxes or mailboxes assigned to them; anything else is a 422. List them with List sending mailboxes.
  • Retries. Without an Idempotency-Key, retrying a request whose response you lost creates a second sequence.

When it fails

Authorizations

x-api-key
string
header
required

Team-scoped API key generated in the Salesfinity dashboard under Settings → Connections → API & Webhooks. A missing or invalid key returns HTTP 403.

Headers

Idempotency-Key
string

Makes this write safe to retry. Send a unique value, such as a UUID, and send the same value again when you retry the same request. A retry with the same key and the same request (method, path including the query string, and JSON body) returns the original successful response without acting twice. The same key with a different body or path returns 409, and so does a retry while the first request is still running; that one is safe to repeat after a moment. A request that fails frees its key, so a retry runs the write again: after a 5xx on a create, confirm with a GET before retrying. Keys are kept for 24 hours and are scoped to your team.

Body

application/json
name
string
required

Sequence name, 1 to 200 characters.

Maximum string length: 200
Example:

"Q4 outbound - VP Operations"

user_id
string
required

The team member creating the sequence; it becomes the author. Must be an active team member with an active plan or seat. A 24-character hexadecimal ID.

Example:

"507f1f77bcf86cd799439011"

description
string

Up to 2,000 characters.

Maximum string length: 2000
tags
string[]

Up to 20 labels for filtering, each up to 50 characters.

Maximum array length: 20
Maximum string length: 50
sequence_type
enum<string>
default:interval

interval: each step waits interval_seconds after the previous one. date: each step comes due on a fixed date. Cannot be changed later once the sequence has steps.

Available options:
interval,
date
policy
string | null

Rules-of-engagement policy id; it must be on your team (404 otherwise). Omit, or send null, to use the team default policy. A 24-character hexadecimal ID.

throttle_max_adds_per_day
number

Most new enrollments this sequence accepts per owner per day, counted from midnight in the schedule's timezone. Further adds that day are refused with throttle_daily. Whole number. Omit for no cap.

Required range: x >= 0
throttle_capacity
number

Most live (pending, active or paused) enrollments this sequence holds per owner. Further adds are refused with throttle_capacity. Whole number. Omit for no cap.

Required range: x >= 0
throttle_paused
boolean

When true, adding people to the sequence is refused with 422 while it keeps running for those already in it.

transactional
boolean

Marks the sequence transactional. Enrollment then skips the suppression list entirely, and sends ignore unsubscribed and manual suppression entries; an address suppressed as bounced, complained or dnc is still never emailed. Only for mail a recipient asked for.

track_opens
boolean
default:true

Adds an open-tracking pixel to this sequence's emails.

Rewrites links in this sequence's emails to track clicks.

primary_reply_action
enum<string>
default:finish

What a reply that reads as interested, a meeting request, or unclear does to the enrollment: finish ends it, continue carries on, pause pauses it. Other replies are handled the same way in every sequence: an out-of-office reply pauses the enrollment until the return date, an auto-reply is ignored, an unsubscribe request opts the person out, and a not-interested or wrong-person reply finishes the enrollment.

Available options:
finish,
continue,
pause
primary_reply_pause_duration
number

Seconds to pause for when primary_reply_action is pause; the enrollment then resumes on its own. Omit, or send 0, to pause until someone resumes it. Whole number.

Required range: x >= 0
schedule
object

When the sequence may act. Send all five fields together: a partial schedule is rejected with 400. Omit schedule to use the team's default schedule, or, when the team has none, Monday to Friday, 8 to 17, in each prospect's timezone (UTC when unknown). A step that comes due outside the window waits for the next open hour.

Example:
email_account_ids
number[]

Mailbox ids this sequence sends from (see GET /v2/sequencer/email-accounts). Omit, or send an empty array, to send from the mailboxes assigned to the sequence's author, or from the team's shared mailboxes when the author has none. A member who is not a team admin may only pick shared mailboxes or mailboxes assigned to them (422 otherwise).

Maximum array length: 100

Response

The new sequence. can_manage is not included.

A Sequencer sequence (a cadence). can_manage is returned by list and get only; step_type_counts and enrollment_counts by list only.

_id
string

24-character hexadecimal id.

Example:

"507f1f77bcf86cd799439011"

team
string

The team that owns the sequence (24-character id).

name
string

Sequence name.

description
string | null
tags
string[]

Free-text labels for filtering.

enabled
boolean

Whether the sequence is running. New and duplicated sequences start false.

sequence_type
enum<string>

interval: each step waits interval_seconds after the previous one. date: each step comes due on its own date.

Available options:
interval,
date
user
string

Author's team member id. Only the author, the team owner or an admin can change the sequence. On GET /v2/sequencer/sequences this field arrives expanded, as an object with _id, first_name, last_name and email, not as a string.

policy
string | null

Rules-of-engagement policy id, or null (or absent) when the sequence uses the team default policy.

transactional
boolean

Whether the sequence is transactional: enrollment skips the suppression list, and sends skip only unsubscribed and manual suppression entries.

throttle_capacity
integer | null

Most live (pending, active or paused) enrollments per owner. Absent when there is no cap.

throttle_max_adds_per_day
integer | null

Most new enrollments per owner per day. Absent when there is no cap.

throttle_paused
boolean

When true, adding people is refused while the sequence keeps running for those already in it.

track_opens
boolean

Whether emails carry an open-tracking pixel.

Whether links in emails are rewritten to track clicks.

sequence_step_count
integer

Number of steps. Updated whenever a step is added, changed or deleted.

duration_in_days
integer

Sum of the steps' interval_seconds, rounded up to whole days. Always 0 on a date sequence.

num_contacted_prospects
integer

Distinct people reached: sent or delivered an email, or a completed call or task. Rebuilt every 15 minutes.

num_replied_prospects
integer

Distinct people who replied. Rebuilt every 15 minutes.

open_count
integer

Number of opens, counted as events, not people. Rebuilt every 15 minutes.

click_count
integer

Number of link clicks, counted as events, not people. Rebuilt every 15 minutes.

reply_count
integer

Number of replies, counted as events, not people. Rebuilt every 15 minutes.

bounce_count
integer

Number of bounces, counted as events, not people. Rebuilt every 15 minutes.

opt_out_count
integer

Number of opt-outs, counted as events, not people. Rebuilt every 15 minutes.

deliver_count
integer

Number of deliveries, counted as events, not people. Rebuilt every 15 minutes.

enabled_at
string<date-time>

When the sequence was last enabled. Absent if it never has been.

archived_at
string<date-time> | null

When the sequence was archived in the dashboard, or null. Archived sequences are left out of the list and cannot be enabled or enrolled into; the API has no archive endpoint.

primary_reply_action
enum<string>

What a reply that reads as interested, a meeting request, or unclear does to the enrollment.

Available options:
finish,
continue,
pause
primary_reply_pause_duration
integer

Seconds an enrollment pauses for when primary_reply_action is pause. Absent means the pause lasts until someone resumes it.

schedule
object

The sequence's own sending window. Absent when the sequence uses the team default schedule.

email_account_ids
integer[]

Mailbox ids the sequence sends from. Empty means the author's assigned mailboxes, or the team's shared ones when the author has none.

failure_count
integer

Number of failed sends, counted as events. Rebuilt every 15 minutes.

schedule_count
integer

Number of times a step ran and produced work: emails sent plus tasks created. Rebuilt every 15 minutes.

reply_rate
integer

num_replied_prospects as a percentage of num_contacted_prospects, 0 to 100, rounded. 0 while nobody has been contacted.

automation_percentage
integer

Share of steps that are auto_email, 0 to 100, rounded.

last_activity_at
string<date-time> | null

When anything last happened in the sequence (an email, a task, a reply). Null for a sequence that has done nothing.

step_type_counts
object

List only. How many steps of each type the sequence has. Every type is always present.

enrollment_counts
object

List only. Live count of the sequence's enrollments in each state, plus total. Every state is always present.

can_manage
boolean

Whether the member the request acted as may change this sequence. API reads act as the team owner, so this is true on every API read; it does not tell you whether a given user_id may edit. Returned by list and get only.

created_at
string<date-time>

When the sequence was created.

updated_at
string<date-time>

When it last changed.