Skip to main content
POST
Complete a task
Marks a task done and, for a task from a sequence, moves its enrollment to the next step. Completing a manual_email task also sends a real email.

Completing a manual email

The response comes back with the task still pending and sending_claimed_at set. The task completes once the send is confirmed. If the send fails, sending_claimed_at is cleared and error_reason says why, and the task can be completed again. Leave body out, or send the draft unchanged, to send the task’s draft as it is stored: plain text for any draft written now, possibly HTML for an older one. A body that differs from the draft is sent as plain text: a blank line starts a new paragraph, a single line break stays a line break, and HTML is not rendered. The task’s attachments go with the email.
The subject on a task from a sequence. Leaving subject out sends the step template’s subject, filled in again, not the task’s subject. If you set a subject with Update a task, send it again here. On a step with several templates, that subject may come from a different template than the draft. An email that replies in its thread always goes out as Re: and the thread’s first subject, whatever subject you pass. A one-off task sends its own subject.
Variables are not filled in. An email whose subject or body still has a {{...}} is not sent: the task stays pending with an error_reason such as Not sent: fill in {{first_name}} first. This call has answered by then, so read the task again to check.
An agent should show the email to a person before calling this. The API has no way to cancel a queued send.

Good to know

  • A call dialed from the rep’s Sequencer dial list completes its task when the call is dispositioned, and applies the call’s outcome. Call this endpoint only for calls made elsewhere; it advances the cadence but applies no call outcome.
  • A one-off task without a draft needs a body here, and a subject if the task has none.
  • held tasks and tasks whose enrollment is no longer active are refused with 409. If the enrollment is paused, resume it first.

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.

Path Parameters

id
string
required

24-character task id.

Body

application/json
user_id
string
required

The team member this call acts as. Must be an active member of the team the API key belongs to.

Example:

"507f1f77bcf86cd799439011"

call_log
string

For a call task: the 24-character id of the call log that resolved it. Must be a call log on your team (Call log not found otherwise). Stored on the task as call_log.

note
string

Replaces the task's note and is recorded on the timeline.

Maximum string length: 2000
subject
string

For a manual_email task: the subject line to send. Defaults to the step template's subject, filled in again (never the task's own subject), or the one-off task's subject. On a step with several templates, that subject may come from a different template than the draft. An email that replies in its thread always goes out as Re: and the thread's first subject, whatever subject you pass.

Maximum string length: 998
body
string

Up to 20,000 characters. For a manual_email task: the email to send. Leave it out, or send the draft unchanged, to send the draft as it is stored: plain text for a draft written through this API, possibly HTML for an older draft the sequencer wrote. A body that differs from the draft is sent as plain text: a blank line starts a new paragraph, a single line break stays a line break, and HTML is not rendered. A task without a draft needs one. Completing such a task sends a real email, with the task's attachments, and the task stays pending until the send is confirmed. Variables are not filled in: an email whose subject or body still has a {{...}} is not sent, and the task stays pending with an error_reason such as Not sent: fill in {{first_name}} first. The complete call has answered by then, so read the task again to see it.

Maximum string length: 20000

Response

The task. A manual_email task is still pending, with sending_claimed_at set, until its send is confirmed.

A task in a rep's queue. contact, sequence, sequence_step and user are documented as ids, but responses expand some of them into objects, as each property says.

_id
string

24-character hexadecimal id.

Example:

"507f1f77bcf86cd799439011"

team
string

Team id.

user
string

Assignee, as a team member id. GET /v2/sequencer/tasks with the default sort=due expands it to an object with _id, first_name, last_name, email and image.

contact
string

The contact the task is about. Every task response expands it to an object: _id plus whichever of these are set: first_name, last_name, email, linkedin_username, account (company), account_key, title, phone_numbers, timezone, website, email_domain, last_touched_at, last_touch, channel_stats, crm_facts.

sequence
string | null

The sequence that created the task. Absent on a one-off task. Every task response expands it to _id and name.

sequence_state
string | null

The enrollment the task belongs to. Absent on a one-off task.

sequence_step
string | null

The step that created the task. Absent on a one-off task. GET /v2/sequencer/tasks expands it to _id, order, step_type and display_name, and GET /v2/sequencer/tasks/{id} adds task_note; other responses return the id.

origin
enum<string>

sequence: created by a sequence step or a reaction. one_off: created by a rep.

Available options:
sequence,
one_off
created_by
string

Who created a one-off task. Absent on sequence tasks.

standalone
boolean

True for tasks outside the cadence: every one-off task, and to-dos a reaction created. Completing or skipping one never moves an enrollment.

action
enum<string>

What the task asks for. Sequence steps create call, manual_email and generic; the LinkedIn actions, meeting and sms occur only on one-off tasks.

Available options:
call,
manual_email,
generic,
linkedin_connect,
linkedin_message,
linkedin_view,
linkedin_interact,
meeting,
sms
state
enum<string>

pending: open. held: waiting while the enrollment is paused; it cannot be completed or skipped until it returns to pending. completed and skipped: resolved by a person. expired: skipped automatically at autoskip_at. cancelled: withdrawn, because the enrollment ended underneath it or a one-off task was cancelled.

Available options:
pending,
held,
completed,
skipped,
expired,
cancelled
priority
enum<string>

Priority band, copied from the step or set on a one-off task.

Available options:
high,
medium,
low
subject
string | null

Short title: the step's display name on a sequence task, or what the creator entered on a one-off task.

note
string | null

Instructions for the rep: the step's task note, or the one-off task's note. A note sent on completion replaces it.

body
string

The draft email of a manual_email task, in plain text: the step's template filled in when the step came due, a draft personalization wrote, or one sent through this API. A task drafted before body_format existed may hold HTML. After a send, the body that was sent.

body_format
enum<string>

text on every draft written now. Absent on older tasks, whose body may be HTML.

Available options:
text,
html
personalization
object | null

Present when AI personalization ran for this task's email: when, any flags worth checking before sending, and the evidence the draft relies on.

attachments
object[]

Files sent with the email. On a manual_email task from a sequence, the files its template had when the task was made; [] on other tasks. Read-only here: completing the task sends them.

due_at
string<date-time>

When the task is due.

autoskip_at
string<date-time> | null

When an untouched task is skipped automatically, moving to expired. Set from the step's auto-skip delay; absent when the step has none.

completed_at
string<date-time> | null

When the task was completed or skipped.

held_at
string<date-time> | null

When the task went held with its paused enrollment; null otherwise.

call_log
string | null

The call that resolved a call task: from a disposition in the dialer, or from call_log on complete.

outcome_applied_at
string<date-time> | null

When the outcome of the call that resolved this task was applied to the enrollment.

contact_list
string | null

The Sequencer dial list a pending call task is placed on; null or absent when it is not on one.

contact_list_item
string | null

The task's row in that dial list.

sending_claimed_at
string<date-time> | null

Set while the email of a manual_email task is being sent. The task stays pending until the send is confirmed; a failed send clears this.

error_reason
string

Why the sequencer handed this email to the rep instead of sending it, such as Waiting for you: no first name, or why its last send failed. Cleared when a new send starts.

created_at
string<date-time>
updated_at
string<date-time>