Skip to content
Lightfield Lightfield
API Reference
Sequence

Create a sequence

POST/v1/sequences

Creates a new sequence and its first draft, and returns the draft. The sequence sends nothing until the draft is published and the sequence is activated.

Supports idempotency via the Idempotency-Key header.

Returns 400 invalid_configuration listing the draft’s problems under issues, and 400 referenced_resource_missing for a reviewer or sender that does not exist. See Sequence errors.

Required scope: sequences:create

Rate limit category: Write

Body ParametersJSONExpand Collapse
definition: object { description, steps, messaging, 3 more }

Configuration of the first draft. description and steps are required.

description: string

What this version of the sequence is for.

minLength1
steps: array of object { deliveryMode, name, prompt, 2 more } or object { deliveryMode, name, prompt, 3 more } or object { deliveryMode, name, template, 2 more } or 3 more

The ordered step list.

One of the following:
object { deliveryMode, name, prompt, 2 more }
deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

One of the following:
"AUTO"
"FOR_REVIEW"
name: string

Display name of the step.

minLength1
prompt: string

Instructions the agent follows when composing this message.

minLength1
type: "EMAIL" or "LINKEDIN_MESSAGE"

Step type.

One of the following:
"EMAIL"
"LINKEDIN_MESSAGE"
mode: optional "AGENT"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in. Optional: the content decides, a prompt for AGENT and a template for TEMPLATE. A kept template step sent with a prompt is refused unless mode is AGENT, so its template is never dropped by accident.

object { deliveryMode, name, prompt, 3 more }
deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

One of the following:
"AUTO"
"FOR_REVIEW"
name: string

Display name of the step.

minLength1
prompt: string

Instructions the agent follows when composing this message.

minLength1
type: "LINKEDIN_INVITE"

Step type.

includeNote: optional boolean

Whether the connection request carries a note. Defaults to false.

mode: optional "AGENT"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in. Optional: the content decides, a prompt for AGENT and a template for TEMPLATE. A kept template step sent with a prompt is refused unless mode is AGENT, so its template is never dropped by accident.

object { deliveryMode, name, template, 2 more }
deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

One of the following:
"AUTO"
"FOR_REVIEW"
name: string

Display name of the step.

minLength1
template: object { body, subject }

The email every contact receives. Requires template steps for the workspace.

body: string

Email body as Markdown; paragraphs, bold, italics, links and lists keep their formatting. Leave out the sign-off and signature, which are added when the message is written. A variable cannot be part of a link address. Write each variable as {{ coalesce(, “fallback”) }}, with a fallback for contacts missing the value. A variable reads a contact field as {attr:}, the contact’s first or last name as {col:firstName} or {col:lastName}, the contact’s first account’s field as {rel:account.}, that account’s name as {rel:account.col:name}, and the sender’s name or email as {rel:sender.col:name} or {rel:sender.col:email}; a SINGLE_SELECT field reads its option’s label, as {attr:.label} or {rel:account..label}. is the literal id of a CrmContact or CrmAccount field in the CRM schema whose type is one of TEXT, NUMBER, CURRENCY, DATETIME, SINGLE_SELECT, FULL_NAME, EMAIL, URL; never a slug, a name, or an id starting with _synthetic. Nothing else is a variable: leave such a value out rather than reading a different field. A {{ }} that is not a variable would send as written, so it is refused. A field’s may be the ad_ ID the field-definitions endpoints list.

minLength1
maxLength10000
subject: string

Plain-text subject line. Write each variable as {{ coalesce(, “fallback”) }}, with a fallback for contacts missing the value. A variable reads a contact field as {attr:}, the contact’s first or last name as {col:firstName} or {col:lastName}, the contact’s first account’s field as {rel:account.}, that account’s name as {rel:account.col:name}, and the sender’s name or email as {rel:sender.col:name} or {rel:sender.col:email}; a SINGLE_SELECT field reads its option’s label, as {attr:.label} or {rel:account..label}. is the literal id of a CrmContact or CrmAccount field in the CRM schema whose type is one of TEXT, NUMBER, CURRENCY, DATETIME, SINGLE_SELECT, FULL_NAME, EMAIL, URL; never a slug, a name, or an id starting with _synthetic. Nothing else is a variable: leave such a value out rather than reading a different field. A {{ }} that is not a variable would send as written, so it is refused. A field’s may be the ad_ ID the field-definitions endpoints list.

minLength1
maxLength10000
type: "EMAIL"

Step type.

mode: optional "TEMPLATE"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in. Optional: the content decides, a prompt for AGENT and a template for TEMPLATE. A kept template step sent with a prompt is refused unless mode is AGENT, so its template is never dropped by accident.

object { deliveryMode, name, template, 2 more }
deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

One of the following:
"AUTO"
"FOR_REVIEW"
name: string

Display name of the step.

minLength1
template: object { body }

The message every contact receives; for an invite, its connection note, sent only with includeNote and otherwise left empty. Requires template steps for the workspace.

body: string

Plain-text message. Write each variable as {{ coalesce(, “fallback”) }}, with a fallback for contacts missing the value. A variable reads a contact field as {attr:}, the contact’s first or last name as {col:firstName} or {col:lastName}, the contact’s first account’s field as {rel:account.}, that account’s name as {rel:account.col:name}, and the sender’s name or email as {rel:sender.col:name} or {rel:sender.col:email}; a SINGLE_SELECT field reads its option’s label, as {attr:.label} or {rel:account..label}. is the literal id of a CrmContact or CrmAccount field in the CRM schema whose type is one of TEXT, NUMBER, CURRENCY, DATETIME, SINGLE_SELECT, FULL_NAME, EMAIL, URL; never a slug, a name, or an id starting with _synthetic. Nothing else is a variable: leave such a value out rather than reading a different field. A {{ }} that is not a variable would send as written, so it is refused. A field’s may be the ad_ ID the field-definitions endpoints list.

maxLength10000
type: "LINKEDIN_MESSAGE"

Step type.

mode: optional "TEMPLATE"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in. Optional: the content decides, a prompt for AGENT and a template for TEMPLATE. A kept template step sent with a prompt is refused unless mode is AGENT, so its template is never dropped by accident.

object { deliveryMode, name, template, 3 more }
deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

One of the following:
"AUTO"
"FOR_REVIEW"
name: string

Display name of the step.

minLength1
template: object { body }

The message every contact receives; for an invite, its connection note, sent only with includeNote and otherwise left empty. Requires template steps for the workspace.

body: string

Plain-text message. Write each variable as {{ coalesce(, “fallback”) }}, with a fallback for contacts missing the value. A variable reads a contact field as {attr:}, the contact’s first or last name as {col:firstName} or {col:lastName}, the contact’s first account’s field as {rel:account.}, that account’s name as {rel:account.col:name}, and the sender’s name or email as {rel:sender.col:name} or {rel:sender.col:email}; a SINGLE_SELECT field reads its option’s label, as {attr:.label} or {rel:account..label}. is the literal id of a CrmContact or CrmAccount field in the CRM schema whose type is one of TEXT, NUMBER, CURRENCY, DATETIME, SINGLE_SELECT, FULL_NAME, EMAIL, URL; never a slug, a name, or an id starting with _synthetic. Nothing else is a variable: leave such a value out rather than reading a different field. A {{ }} that is not a variable would send as written, so it is refused. A field’s may be the ad_ ID the field-definitions endpoints list.

maxLength10000
type: "LINKEDIN_INVITE"

Step type.

includeNote: optional boolean

Whether the connection request carries a note. Defaults to false.

mode: optional "TEMPLATE"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in. Optional: the content decides, a prompt for AGENT and a template for TEMPLATE. A kept template step sent with a prompt is refused unless mode is AGENT, so its template is never dropped by accident.

object { duration, type, unit }
duration: number

Length of the wait.

minimum1
maximum9007199254740991
type: "WAIT" or "WAIT_FOR_CONNECTION"

WAIT pauses for a fixed time; WAIT_FOR_CONNECTION waits up to that long for a LinkedIn invite to be accepted.

One of the following:
"WAIT"
"WAIT_FOR_CONNECTION"
unit: "DAY" or "MINUTE"

Unit of duration.

One of the following:
"DAY"
"MINUTE"
messaging: optional object { callToAction, persona, trigger, valueProp }

Messaging inputs that frame every step. Omitted or null fields are left unset.

callToAction: optional string

What the recipient is asked to do.

minLength1
persona: optional string

Who the sequence targets.

minLength1
trigger: optional string

Why the outreach is timely.

minLength1
valueProp: optional string

The value proposition.

minLength1
pacing: optional object { EMAIL, LINKEDIN_INVITE, LINKEDIN_MESSAGE }

How the whole sequence paces each step type it sends, keyed by sequence step type. Omitted step types have no daily cap.

EMAIL: optional object { dailyLimit }

Email steps.

dailyLimit: number

Most sends of this step type across the whole sequence in any rolling 24 hours, or null when the sequence sets no daily cap. Workspace and sender limits still apply.

minimum1
maximum9007199254740991
LINKEDIN_INVITE: optional object { dailyLimit }

LinkedIn connection requests.

dailyLimit: number

Most sends of this step type across the whole sequence in any rolling 24 hours, or null when the sequence sets no daily cap. Workspace and sender limits still apply.

minimum1
maximum9007199254740991
LINKEDIN_MESSAGE: optional object { dailyLimit }

LinkedIn messages.

dailyLimit: number

Most sends of this step type across the whole sequence in any rolling 24 hours, or null when the sequence sets no daily cap. Workspace and sender limits still apply.

minimum1
maximum9007199254740991
priority: optional "HIGH" or "NORMAL"

Send priority relative to other sequences. Defaults to NORMAL.

One of the following:
"HIGH"
"NORMAL"
sendWindow: optional object { daysOfWeek, endHour, startHour, timezone }

When the sequence may send. Omitted fields take the default: 9:00–17:00, Monday to Friday, UTC.

daysOfWeek: optional array of number

Days sends may go out, 0 = Sunday.

endHour: optional number

Local hour sends stop, exclusive (1–24).

minimum1
maximum24
startHour: optional number

First local hour sends may go out (0–23).

minimum0
maximum23
timezone: optional string

IANA timezone of the window.

name: string

Name of the sequence.

minLength1
reviewers: optional array of string

Extra members who may approve this sequence’s FOR_REVIEW messages before they send. The sending member and the sequence’s creator always review, whether or not they are listed. Member IDs of active members. Omit for none.

senders: optional array of string

The senders this sequence sends from; new contacts rotate across them. Sender IDs of unarchived senders. Omit for none; activating needs a sender for each channel the steps use.

ReturnsExpand Collapse
SequenceCreateResponse object { channels, definition, name, 6 more }
channels: array of "EMAIL" or "LINKEDIN"

Channels the draft’s steps send on.

One of the following:
"EMAIL"
"LINKEDIN"
definition: object { description, messaging, pacing, 3 more }

The draft configuration, in the same shape as a published definition.

description: string

What this version of the sequence is for.

messaging: object { callToAction, persona, trigger, valueProp }

Messaging inputs that frame every step.

callToAction: string

What the recipient is asked to do.

persona: string

Who the sequence targets.

trigger: string

Why the outreach is timely.

valueProp: string

The value proposition.

pacing: object { EMAIL, LINKEDIN_INVITE, LINKEDIN_MESSAGE }

How the whole sequence paces each step type it sends, keyed by sequence step type.

EMAIL: object { dailyLimit }

Email steps.

dailyLimit: number

Most sends of this step type across the whole sequence in any rolling 24 hours, or null when the sequence sets no daily cap. Workspace and sender limits still apply.

minimum-9007199254740991
maximum9007199254740991
LINKEDIN_INVITE: object { dailyLimit }

LinkedIn connection requests.

dailyLimit: number

Most sends of this step type across the whole sequence in any rolling 24 hours, or null when the sequence sets no daily cap. Workspace and sender limits still apply.

minimum-9007199254740991
maximum9007199254740991
LINKEDIN_MESSAGE: object { dailyLimit }

LinkedIn messages.

dailyLimit: number

Most sends of this step type across the whole sequence in any rolling 24 hours, or null when the sequence sets no daily cap. Workspace and sender limits still apply.

minimum-9007199254740991
maximum9007199254740991
priority: "HIGH" or "NORMAL"

Send priority relative to other sequences.

One of the following:
"HIGH"
"NORMAL"
sendWindow: object { daysOfWeek, endHour, startHour, timezone }

When the sequence may send.

daysOfWeek: array of number

Days sends may go out, 0 = Sunday.

endHour: number

Local hour sends stop, exclusive (1–24).

minimum-9007199254740991
maximum9007199254740991
startHour: number

First local hour sends may go out (0–23).

minimum-9007199254740991
maximum9007199254740991
timezone: string

IANA timezone of the window.

steps: array of object { id, deliveryMode, mode, 3 more } or object { id, deliveryMode, includeNote, 4 more } or object { id, deliveryMode, mode, 3 more } or 3 more

Email, LinkedIn and wait steps in execution order.

One of the following:
object { id, deliveryMode, mode, 3 more }
id: string

Step identifier, referenced by enrollment currentStepId and message sequenceStepId.

deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

One of the following:
"AUTO"
"FOR_REVIEW"
mode: "AGENT"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in.

name: string

Display name of the step.

prompt: string

Instructions the agent follows when composing this message.

type: "EMAIL" or "LINKEDIN_MESSAGE"

Step type.

One of the following:
"EMAIL"
"LINKEDIN_MESSAGE"
object { id, deliveryMode, includeNote, 4 more }
id: string

Step identifier, referenced by enrollment currentStepId and message sequenceStepId.

deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

One of the following:
"AUTO"
"FOR_REVIEW"
includeNote: boolean

Whether the connection request carries a note. A step authored before this setting existed reads as true.

mode: "AGENT"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in.

name: string

Display name of the step.

prompt: string

Instructions the agent follows when composing this message.

type: "LINKEDIN_INVITE"

Step type.

object { id, deliveryMode, mode, 3 more }
id: string

Step identifier, referenced by enrollment currentStepId and message sequenceStepId.

deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

One of the following:
"AUTO"
"FOR_REVIEW"
mode: "TEMPLATE"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in.

name: string

Display name of the step.

template: object { body, subject }

The email every contact receives.

body: string

Email body as Markdown, without the sign-off or signature, which are added when the message is written. Each {{ }} is a variable filled in per contact, with a fallback for a contact missing the value; a field variable names the field by the ad_ ID the field-definitions endpoints list.

subject: string

Plain-text subject line. Each {{ }} is a variable filled in per contact, with a fallback for a contact missing the value; a field variable names the field by the ad_ ID the field-definitions endpoints list.

type: "EMAIL"

Step type.

object { id, deliveryMode, mode, 3 more }
id: string

Step identifier, referenced by enrollment currentStepId and message sequenceStepId.

deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

One of the following:
"AUTO"
"FOR_REVIEW"
mode: "TEMPLATE"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in.

name: string

Display name of the step.

template: object { body }

The message every contact receives; for an invite, its connection note, sent only with includeNote.

body: string

Plain-text message. Each {{ }} is a variable filled in per contact, with a fallback for a contact missing the value; a field variable names the field by the ad_ ID the field-definitions endpoints list.

type: "LINKEDIN_MESSAGE"

Step type.

object { id, deliveryMode, includeNote, 4 more }
id: string

Step identifier, referenced by enrollment currentStepId and message sequenceStepId.

deliveryMode: "AUTO" or "FOR_REVIEW"

AUTO sends without manual approval, subject to the send window and limits; FOR_REVIEW requires a person to approve the draft before sending.

One of the following:
"AUTO"
"FOR_REVIEW"
includeNote: boolean

Whether the connection request carries a note. A step authored before this setting existed reads as true.

mode: "TEMPLATE"

How each message is written: AGENT composes it from prompt; TEMPLATE sends template to every contact, with its variables filled in.

name: string

Display name of the step.

template: object { body }

The message every contact receives; for an invite, its connection note, sent only with includeNote.

body: string

Plain-text message. Each {{ }} is a variable filled in per contact, with a fallback for a contact missing the value; a field variable names the field by the ad_ ID the field-definitions endpoints list.

type: "LINKEDIN_INVITE"

Step type.

object { id, duration, type, unit }
id: string

Step identifier.

duration: number

Length of the wait.

minimum-9007199254740991
maximum9007199254740991
type: "WAIT" or "WAIT_FOR_CONNECTION"

WAIT pauses for a fixed time; WAIT_FOR_CONNECTION waits up to that long for a LinkedIn invite to be accepted.

One of the following:
"WAIT"
"WAIT_FOR_CONNECTION"
unit: "DAY" or "MINUTE"

Unit of duration.

One of the following:
"DAY"
"MINUTE"
name: string

Name the sequence takes when the draft is published.

publishWarnings: array of object { code, message, severity, stepIds }

What publishing this draft would change for contacts already in the sequence; empty when nothing is affected. Before the first publish, the only possible warning is a proposed sender that was archived and would be left off.

code: "delay_shortened" or "delay_lengthened" or "connection_wait_shortened" or 18 more

What publishing would change.

One of the following:
"delay_shortened"
"delay_lengthened"
"connection_wait_shortened"
"connection_wait_lengthened"
"send_schedule_changed"
"send_configuration_changed"
"send_priority_changed"
"senders_changed"
"email_sender_pool_emptied"
"linkedin_account_pool_emptied"
"assigned_sender_removed"
"delivery_became_automatic"
"invite_note_enabled"
"invite_note_disabled"
"step_inserted"
"automatic_send_step_inserted"
"step_removed"
"step_type_changed"
"step_order_changed"
"full_identity_rewrite"
"low_identity_overlap"
message: string

What would change, in plain language.

severity: "warning" or "destructive"

destructive when contacts already in the sequence may skip, repeat or receive a step they would not have; warning otherwise.

One of the following:
"warning"
"destructive"
stepIds: array of string

The steps involved; empty for a sequence-wide change.

reviewers: array of object { id, objectType }

Extra members who may approve this sequence’s FOR_REVIEW messages before they send. The sending member and the sequence’s creator always review, whether or not they are listed.

id: string

ID of the member.

minLength1
objectType: "member"

Always member.

senders: array of object { id, objectType }

The senders this draft will publish; new contacts rotate across them. Until a save changes it, this is the sequence’s live list. An archived sender stays listed but never sends; any change to the list drops it.

id: string

ID of the sender.

minLength1
objectType: "sender"

Always sender.

sequenceId: string

The sequence this draft belongs to.

updatedAt: string

When the draft last changed.

version: string

Opaque token for the current state of the draft. Send it as expectedVersion on the next save, publish or discard; it changes whenever anyone edits the draft.

Create a sequence

curl https://api.lightfield.app/v1/sequences \
    -H 'Content-Type: application/json' \
    -H 'Lightfield-Version: 2026-03-01' \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
          "definition": {
            "description": "x",
            "steps": [
              {
                "deliveryMode": "AUTO",
                "name": "x",
                "prompt": "x",
                "type": "EMAIL"
              }
            ]
          },
          "name": "x"
        }'
{
  "channels": [
    "EMAIL"
  ],
  "definition": {
    "description": "description",
    "messaging": {
      "callToAction": "callToAction",
      "persona": "persona",
      "trigger": "trigger",
      "valueProp": "valueProp"
    },
    "pacing": {
      "EMAIL": {
        "dailyLimit": -9007199254740991
      },
      "LINKEDIN_INVITE": {
        "dailyLimit": -9007199254740991
      },
      "LINKEDIN_MESSAGE": {
        "dailyLimit": -9007199254740991
      }
    },
    "priority": "HIGH",
    "sendWindow": {
      "daysOfWeek": [
        -9007199254740991
      ],
      "endHour": -9007199254740991,
      "startHour": -9007199254740991,
      "timezone": "timezone"
    },
    "steps": [
      {
        "id": "id",
        "deliveryMode": "AUTO",
        "mode": "AGENT",
        "name": "name",
        "prompt": "prompt",
        "type": "EMAIL"
      }
    ]
  },
  "name": "name",
  "publishWarnings": [
    {
      "code": "delay_shortened",
      "message": "message",
      "severity": "warning",
      "stepIds": [
        "string"
      ]
    }
  ],
  "reviewers": [
    {
      "id": "x",
      "objectType": "member"
    }
  ],
  "senders": [
    {
      "id": "x",
      "objectType": "sender"
    }
  ],
  "sequenceId": "sequenceId",
  "updatedAt": "updatedAt",
  "version": "version"
}
Returns Examples
{
  "channels": [
    "EMAIL"
  ],
  "definition": {
    "description": "description",
    "messaging": {
      "callToAction": "callToAction",
      "persona": "persona",
      "trigger": "trigger",
      "valueProp": "valueProp"
    },
    "pacing": {
      "EMAIL": {
        "dailyLimit": -9007199254740991
      },
      "LINKEDIN_INVITE": {
        "dailyLimit": -9007199254740991
      },
      "LINKEDIN_MESSAGE": {
        "dailyLimit": -9007199254740991
      }
    },
    "priority": "HIGH",
    "sendWindow": {
      "daysOfWeek": [
        -9007199254740991
      ],
      "endHour": -9007199254740991,
      "startHour": -9007199254740991,
      "timezone": "timezone"
    },
    "steps": [
      {
        "id": "id",
        "deliveryMode": "AUTO",
        "mode": "AGENT",
        "name": "name",
        "prompt": "prompt",
        "type": "EMAIL"
      }
    ]
  },
  "name": "name",
  "publishWarnings": [
    {
      "code": "delay_shortened",
      "message": "message",
      "severity": "warning",
      "stepIds": [
        "string"
      ]
    }
  ],
  "reviewers": [
    {
      "id": "x",
      "objectType": "member"
    }
  ],
  "senders": [
    {
      "id": "x",
      "objectType": "sender"
    }
  ],
  "sequenceId": "sequenceId",
  "updatedAt": "updatedAt",
  "version": "version"
}