Skip to main content
POST
Skip one pending step for a contact
Requires sequences:write. This operation changes one contact’s enrollment. It keeps the enrollment ID, previous sends, personalization, and history, and leaves the shared sequence unchanged.

Choose the pending step

A pending step has not been sent, completed, or skipped. A failed attempt that remains retryable is still pending once dispatch has finished. A step that is being sent returns dispatch_in_progress; the request does not cancel it. Missing mode-dependent inputs, invalid channels, and negative or fractional indexes return HTTP 400. Inputs for another mode are ignored. A phone call that connected is already sent even if its sequence send record is still being reconciled. An unresolved dial cannot be skipped or continued past until its outcome is known. The optional reason is a nonempty string up to 2,000 characters. The contact’s journey history records the step, channel, reason, timestamp, and workflow, operator, or API-key attribution. Without a reason, history shows “Requested skip.” The journey shows Skipped, including future steps.

Status and waiting time

  • Active: the current due time stays in place. At that time the skipped slot is consumed and the next step’s wait begins. Future skips take effect when reached.
  • Parked: status and park reason stay unchanged. Resolve the existing park through its normal controls before the sender progresses.
  • Exited after a reply: the skip is saved, but the enrollment stays exited. Call Continue Sequence for Contact separately.
  • Completed, suppressed, removed, or candidate: no step is newly skipped and no enrollment is revived.
Sequence pauses and consent restrictions still apply when the sender reaches a recorded skip. A temporary restriction covering every available channel defers progress until it expires; permanent suppression covering every available channel exits the enrollment. Skipped steps retain their waits. A 30-minute wait before a skipped call followed by a 60-minute wait before an email keeps a 90-minute gap. Sending windows are applied at each slot in the contact’s timezone, using the sequence’s normal timezone fallback. Closed hours can lengthen the gap; later processing can also delay it. Continuation starts waiting when the contact is resumed. It adds the waits of skipped slots before the next pending step, applying the same sending windows. In the example, the email becomes due no earlier than 90 minutes after continuation. If no pending steps remain, continuation returns nothing_to_continue and the enrollment stays exited. If you later edit the pending step’s wait, it is recalculated from the latest continuation or the previous step’s effective completion time. Other history events do not restart that wait.

Results and retries

The response uses HTTP 201 for both a new skip and an expected no-op:
skipped is true only for a new skip. Index/channel fields identify the selected step where available; otherwise they are null. A missing or inaccessible sequence returns HTTP 404; insufficient scope returns HTTP 403. Specific-step requests are always idempotent. For either next-step mode, supply an idempotency_key of up to 200 characters and reuse it on retries. The key is scoped to this enrollment and identifies the original selection, even if the cursor later moves. Use a new key for a new skip intent. Workflow executions supply a key automatically for each action in a run. Recorded skips pin their step positions: removing that shared step or an earlier step is refused. Full replacement of a draft containing recorded skips is also refused. Use content/delay edits or append steps instead. The MCP equivalent is skip_sequence_step, with sequence_id, contact_id, and the same body fields.

Skip the next phone step

After skipped or already_skipped, continue the same contact using the separate continuation operation. See the workflow example.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

sequenceId
string<uuid>
required

The unique identifier of the sequence

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
contactId
string<uuid>
required

The person's contact id (from enroll results or the people list)

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Body

application/json
mode
enum<string>
required
Available options:
next_pending,
next_channel,
specific_step
channel
enum<string>

Required for next_channel. Phone uses voice.

Available options:
whatsapp,
voice,
email
step_index
integer

Required for specific_step; zero-based.

Required range: 0 <= x <= 9007199254740991
reason
string
Required string length: 1 - 2000
idempotency_key
string

Reuse for retries of a next-step request in this enrollment. Specific-step skips are always idempotent.

Required string length: 1 - 200

Response

Default Response

outcome
enum<string>
required
Available options:
skipped,
already_skipped,
contact_not_found,
not_skippable,
no_pending_step,
step_not_found,
step_not_pending,
dispatch_in_progress
skipped
boolean
required

True only when this request newly skipped a step.

contact_id
string | null
required
enrollment_id
string | null
required
step_index
integer | null
required
Required range: -9007199254740991 <= x <= 9007199254740991
channel
enum<string> | null
required
Available options:
whatsapp,
voice,
email