## Create a sequence
`sequence.create(SequenceCreateParams**kwargs) -> SequenceCreateResponse`
**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](/using-the-api/errors/#sequence-errors).
**[Required scope](/using-the-api/scopes/):** `sequences:create`
**[Rate limit category](/using-the-api/rate-limits/):** Write
### Parameters
- `definition: Definition`
Configuration of the first draft. `description` and `steps` are required.
- `description: str`
What this version of the sequence is for.
- `steps: Iterable[DefinitionStep]`
The ordered step list.
- `class DefinitionStepUnionMember0: …`
- `delivery_mode: Literal["AUTO", "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.
- `"AUTO"`
- `"FOR_REVIEW"`
- `name: str`
Display name of the step.
- `prompt: str`
Instructions the agent follows when composing this message.
- `type: Literal["EMAIL", "LINKEDIN_MESSAGE"]`
Step type.
- `"EMAIL"`
- `"LINKEDIN_MESSAGE"`
- `mode: Optional[Literal["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.
- `"AGENT"`
- `class DefinitionStepUnionMember1: …`
- `delivery_mode: Literal["AUTO", "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.
- `"AUTO"`
- `"FOR_REVIEW"`
- `name: str`
Display name of the step.
- `prompt: str`
Instructions the agent follows when composing this message.
- `type: Literal["LINKEDIN_INVITE"]`
Step type.
- `"LINKEDIN_INVITE"`
- `include_note: Optional[bool]`
Whether the connection request carries a note. Defaults to false.
- `mode: Optional[Literal["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.
- `"AGENT"`
- `class DefinitionStepUnionMember2: …`
- `delivery_mode: Literal["AUTO", "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.
- `"AUTO"`
- `"FOR_REVIEW"`
- `name: str`
Display name of the step.
- `template: DefinitionStepUnionMember2Template`
The email every contact receives. Requires template steps for the workspace.
- `body: str`
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.
- `subject: str`
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.
- `type: Literal["EMAIL"]`
Step type.
- `"EMAIL"`
- `mode: Optional[Literal["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.
- `"TEMPLATE"`
- `class DefinitionStepUnionMember3: …`
- `delivery_mode: Literal["AUTO", "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.
- `"AUTO"`
- `"FOR_REVIEW"`
- `name: str`
Display name of the step.
- `template: DefinitionStepUnionMember3Template`
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: str`
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.
- `type: Literal["LINKEDIN_MESSAGE"]`
Step type.
- `"LINKEDIN_MESSAGE"`
- `mode: Optional[Literal["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.
- `"TEMPLATE"`
- `class DefinitionStepUnionMember4: …`
- `delivery_mode: Literal["AUTO", "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.
- `"AUTO"`
- `"FOR_REVIEW"`
- `name: str`
Display name of the step.
- `template: DefinitionStepUnionMember4Template`
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: str`
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.
- `type: Literal["LINKEDIN_INVITE"]`
Step type.
- `"LINKEDIN_INVITE"`
- `include_note: Optional[bool]`
Whether the connection request carries a note. Defaults to false.
- `mode: Optional[Literal["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.
- `"TEMPLATE"`
- `class DefinitionStepUnionMember5: …`
- `duration: int`
Length of the wait.
- `type: Literal["WAIT", "WAIT_FOR_CONNECTION"]`
`WAIT` pauses for a fixed time; `WAIT_FOR_CONNECTION` waits up to that long for a LinkedIn invite to be accepted.
- `"WAIT"`
- `"WAIT_FOR_CONNECTION"`
- `unit: Literal["DAY", "MINUTE"]`
Unit of `duration`.
- `"DAY"`
- `"MINUTE"`
- `messaging: Optional[DefinitionMessaging]`
Messaging inputs that frame every step. Omitted or null fields are left unset.
- `call_to_action: Optional[str]`
What the recipient is asked to do.
- `persona: Optional[str]`
Who the sequence targets.
- `trigger: Optional[str]`
Why the outreach is timely.
- `value_prop: Optional[str]`
The value proposition.
- `pacing: Optional[DefinitionPacing]`
How the whole sequence paces each step type it sends, keyed by sequence step type. Omitted step types have no daily cap.
- `email: Optional[DefinitionPacingEmail]`
Email steps.
- `daily_limit: Optional[int]`
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.
- `linkedin_invite: Optional[DefinitionPacingLinkedinInvite]`
LinkedIn connection requests.
- `daily_limit: Optional[int]`
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.
- `linkedin_message: Optional[DefinitionPacingLinkedinMessage]`
LinkedIn messages.
- `daily_limit: Optional[int]`
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.
- `priority: Optional[Literal["HIGH", "NORMAL"]]`
Send priority relative to other sequences. Defaults to `NORMAL`.
- `"HIGH"`
- `"NORMAL"`
- `send_window: Optional[DefinitionSendWindow]`
When the sequence may send. Omitted fields take the default: 9:00–17:00, Monday to Friday, UTC.
- `days_of_week: Optional[Iterable[int]]`
Days sends may go out, 0 = Sunday.
- `end_hour: Optional[int]`
Local hour sends stop, exclusive (1–24).
- `start_hour: Optional[int]`
First local hour sends may go out (0–23).
- `timezone: Optional[str]`
IANA timezone of the window.
- `name: str`
Name of the sequence.
- `reviewers: Optional[Sequence[str]]`
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[Sequence[str]]`
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.
### Returns
- `class SequenceCreateResponse: …`
- `channels: List[Literal["EMAIL", "LINKEDIN"]]`
Channels the draft's steps send on.
- `"EMAIL"`
- `"LINKEDIN"`
- `definition: Definition`
The draft configuration, in the same shape as a published definition.
- `description: str`
What this version of the sequence is for.
- `messaging: DefinitionMessaging`
Messaging inputs that frame every step.
- `call_to_action: Optional[str]`
What the recipient is asked to do.
- `persona: Optional[str]`
Who the sequence targets.
- `trigger: Optional[str]`
Why the outreach is timely.
- `value_prop: Optional[str]`
The value proposition.
- `pacing: DefinitionPacing`
How the whole sequence paces each step type it sends, keyed by sequence step type.
- `email: DefinitionPacingEmail`
Email steps.
- `daily_limit: Optional[int]`
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.
- `linkedin_invite: DefinitionPacingLinkedinInvite`
LinkedIn connection requests.
- `daily_limit: Optional[int]`
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.
- `linkedin_message: DefinitionPacingLinkedinMessage`
LinkedIn messages.
- `daily_limit: Optional[int]`
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.
- `priority: Literal["HIGH", "NORMAL"]`
Send priority relative to other sequences.
- `"HIGH"`
- `"NORMAL"`
- `send_window: DefinitionSendWindow`
When the sequence may send.
- `days_of_week: List[int]`
Days sends may go out, 0 = Sunday.
- `end_hour: int`
Local hour sends stop, exclusive (1–24).
- `start_hour: int`
First local hour sends may go out (0–23).
- `timezone: str`
IANA timezone of the window.
- `steps: List[DefinitionStep]`
Email, LinkedIn and wait steps in execution order.
- `class DefinitionStepUnionMember0: …`
- `id: str`
Step identifier, referenced by enrollment `currentStepId` and message `sequenceStepId`.
- `delivery_mode: Literal["AUTO", "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.
- `"AUTO"`
- `"FOR_REVIEW"`
- `mode: Literal["AGENT"]`
How each message is written: `AGENT` composes it from `prompt`; `TEMPLATE` sends `template` to every contact, with its variables filled in.
- `"AGENT"`
- `name: str`
Display name of the step.
- `prompt: str`
Instructions the agent follows when composing this message.
- `type: Literal["EMAIL", "LINKEDIN_MESSAGE"]`
Step type.
- `"EMAIL"`
- `"LINKEDIN_MESSAGE"`
- `class DefinitionStepUnionMember1: …`
- `id: str`
Step identifier, referenced by enrollment `currentStepId` and message `sequenceStepId`.
- `delivery_mode: Literal["AUTO", "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.
- `"AUTO"`
- `"FOR_REVIEW"`
- `include_note: bool`
Whether the connection request carries a note. A step authored before this setting existed reads as true.
- `mode: Literal["AGENT"]`
How each message is written: `AGENT` composes it from `prompt`; `TEMPLATE` sends `template` to every contact, with its variables filled in.
- `"AGENT"`
- `name: str`
Display name of the step.
- `prompt: str`
Instructions the agent follows when composing this message.
- `type: Literal["LINKEDIN_INVITE"]`
Step type.
- `"LINKEDIN_INVITE"`
- `class DefinitionStepUnionMember2: …`
- `id: str`
Step identifier, referenced by enrollment `currentStepId` and message `sequenceStepId`.
- `delivery_mode: Literal["AUTO", "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.
- `"AUTO"`
- `"FOR_REVIEW"`
- `mode: Literal["TEMPLATE"]`
How each message is written: `AGENT` composes it from `prompt`; `TEMPLATE` sends `template` to every contact, with its variables filled in.
- `"TEMPLATE"`
- `name: str`
Display name of the step.
- `template: DefinitionStepUnionMember2Template`
The email every contact receives.
- `body: str`
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: str`
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: Literal["EMAIL"]`
Step type.
- `"EMAIL"`
- `class DefinitionStepUnionMember3: …`
- `id: str`
Step identifier, referenced by enrollment `currentStepId` and message `sequenceStepId`.
- `delivery_mode: Literal["AUTO", "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.
- `"AUTO"`
- `"FOR_REVIEW"`
- `mode: Literal["TEMPLATE"]`
How each message is written: `AGENT` composes it from `prompt`; `TEMPLATE` sends `template` to every contact, with its variables filled in.
- `"TEMPLATE"`
- `name: str`
Display name of the step.
- `template: DefinitionStepUnionMember3Template`
The message every contact receives; for an invite, its connection note, sent only with `includeNote`.
- `body: str`
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: Literal["LINKEDIN_MESSAGE"]`
Step type.
- `"LINKEDIN_MESSAGE"`
- `class DefinitionStepUnionMember4: …`
- `id: str`
Step identifier, referenced by enrollment `currentStepId` and message `sequenceStepId`.
- `delivery_mode: Literal["AUTO", "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.
- `"AUTO"`
- `"FOR_REVIEW"`
- `include_note: bool`
Whether the connection request carries a note. A step authored before this setting existed reads as true.
- `mode: Literal["TEMPLATE"]`
How each message is written: `AGENT` composes it from `prompt`; `TEMPLATE` sends `template` to every contact, with its variables filled in.
- `"TEMPLATE"`
- `name: str`
Display name of the step.
- `template: DefinitionStepUnionMember4Template`
The message every contact receives; for an invite, its connection note, sent only with `includeNote`.
- `body: str`
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: Literal["LINKEDIN_INVITE"]`
Step type.
- `"LINKEDIN_INVITE"`
- `class DefinitionStepUnionMember5: …`
- `id: str`
Step identifier.
- `duration: int`
Length of the wait.
- `type: Literal["WAIT", "WAIT_FOR_CONNECTION"]`
`WAIT` pauses for a fixed time; `WAIT_FOR_CONNECTION` waits up to that long for a LinkedIn invite to be accepted.
- `"WAIT"`
- `"WAIT_FOR_CONNECTION"`
- `unit: Literal["DAY", "MINUTE"]`
Unit of `duration`.
- `"DAY"`
- `"MINUTE"`
- `name: str`
Name the sequence takes when the draft is published.
- `publish_warnings: List[PublishWarning]`
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: Literal["delay_shortened", "delay_lengthened", "connection_wait_shortened", 18 more]`
What publishing would change.
- `"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: str`
What would change, in plain language.
- `severity: Literal["warning", "destructive"]`
`destructive` when contacts already in the sequence may skip, repeat or receive a step they would not have; `warning` otherwise.
- `"warning"`
- `"destructive"`
- `step_ids: List[str]`
The steps involved; empty for a sequence-wide change.
- `reviewers: List[Reviewer]`
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: str`
ID of the member.
- `object_type: Literal["member"]`
Always `member`.
- `"member"`
- `senders: List[Sender]`
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: str`
ID of the sender.
- `object_type: Literal["sender"]`
Always `sender`.
- `"sender"`
- `sequence_id: str`
The sequence this draft belongs to.
- `updated_at: str`
When the draft last changed.
- `version: str`
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.
### Example
```python
from lightfield import Lightfield
client = Lightfield(
api_key="My API Key",
)
sequence_create_response = client.sequence.create(
definition={
"description": "x",
"steps": [{
"delivery_mode": "AUTO",
"name": "x",
"prompt": "x",
"type": "EMAIL",
}],
},
name="x",
)
print(sequence_create_response.channels)
```
#### Response
```json
{
"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"
}
```