Skip to main content
PATCH
Update a task
Changes an open task. Send only the fields you want to change. Use it to draft the email a rep will send: set subject and body on a manual_email task, from a cadence or one-off, and the rep starts from your draft. On a task from a sequence, the subject you set is what the rep sees, but when you complete the task through the API, send the subject again: left out, the step template’s subject is sent. 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.
body is plain text, up to 20,000 characters. A blank line starts a new paragraph and a single line break stays a line break. HTML is not rendered: <p>Hi</p> reaches the recipient as those characters. 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. Write names out. Changing due_at or priority on a task from a sequence is refused with 422: snooze it instead. A body on a task that is not manual_email is refused with 422 too.

Good to know

  • The action cannot change. Cancel the task and create a new one.
  • A one-off task can be edited by its assignee, whoever created it, or a team admin. A task from a sequence can be edited by its assignee, the sequence’s owner, or a team admin.
  • Moving due_at moves the auto-skip deadline with it. Edits are not recorded on the task’s timeline.

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.

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"

due_at
string<date-time>

New due time. Moves the auto-skip deadline by the same amount. At most 365 days ahead; up to 5 minutes in the past is accepted.

priority
enum<string>

New priority band.

Available options:
high,
medium,
low
subject
string

New short title, and subject line for a manual_email task. On a task from a sequence, completing it sends the step template's subject unless you pass subject again on complete, and an email that replies in its thread always goes out as Re: and the thread's first subject.

Maximum string length: 998
note
string

New instructions.

Maximum string length: 2000
body
string

Up to 20,000 characters. Replaces the draft email on an open manual_email task, cadence tasks included: this is how you predraft the email the rep will review and send. Plain text: a blank line starts a new paragraph and a single line break stays a line break. HTML is not rendered; tags reach the recipient exactly as typed. 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. A task with any other action refuses it with 422.

Maximum string length: 20000

Response

The updated task, with contact and sequence expanded.

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>