Sequence Enrollments

The Sequence Enrollments API provides a simple interface to start and manage leads sequences. This automation is available only if you have bought our Reach product. The API allows you to

  • start a sequence for lead: create sequence enrollment for a given lead

  • stop the sequence for a lead: update the enrollment with status finished

  • resume blocked sequence for a lead: update the enrollment with status active

  • retrieve sequence enrollment by id

Sequence Enrollment consists of steps that are saved from the sequence when it is started for given resource (e.g. lead) and are not changed when sequence is changed. Those steps explains what is the current progress of sequence, which steps have been completed, which are still pending as well as what is the planned execution timeline for the particular resource. Each Step can be either an automated_email or a task and contains some specific attributes per type.

EnrollmentStep properties

Attribute Description
position
number
readonly
Zero-based step’s position in sequence for this enrollment
delay_from_previous_step
number
readonly
Time that should pass in between execution of this and previous step
delay_from_previous_step_unit
string
readonly
Unit of the time that should pass in between execution of this and previous step

Possible values
  • hours
  • weekdays - days between Monday and Friday
overdue
boolean
readonly
Indicates whether the step is delayed in execution. It might be because email was not sent on time or task was not completed by user on time
action_type
string
readonly
Type of the step’s action

Possible values
  • automated_email
  • task
action_properties
object
readonly
Object containing attributes from sequence that configure this step

Properites for automated email:
  • email_template_id - id of a email template that will be send in this step
  • is_reply - boolean (true, false) - whether email should be sent as a reply or as a new thread

Properties for task:
  • task_content - content of task that will be created for this step
action
object
readonly
EnrollmentStepAction object defined in the table below

EnrollmentStepAction properties

Attribute Description
status
string
readonly
Step’s action status

Statuses for automated email:
  • scheduled - email is scheduled to be sent
  • in_progress - email is being sent
  • completed - email was sent successfully
  • blocked - email cannot be sent, see action’s failure reason to learn more
  • cancelled - email sendout was cancelled (e.g. due to prospect response to sequence)


Statuses for task:
  • scheduled - task is scheduled to be created for a given due date
  • in_progress - task is created and awaits user action
  • completed - task was completed
  • cancelled - task was cancelleted (e.g. due to prospect response to sequence)
executed_at
string
readonly
Date and time when the action was executed
estimated_execute_at
string
readonly
Date and time when the action was scheduled to be executed
failure_reason
string
readonly
optional
Possible values
  • unknown
  • sendout_limited
  • recipient_invalid
  • auth
  • missing_merge_tags
  • attachment_limit_exceeded
  • sendout_disabled
  • quota_exceeded
task_content
string
readonly
optional
Task content, present only for action of type: task
task_id
number
readonly
optional
Task identifier, present only for action of type: task after the task was already created (statuses: in_progress, completed).

Properties

Attribute Description
id number readonly

Unique identifier of the enrollment.

actor_id number readonly

Unique identifier of the user on whose behalf emails are being sent and for whom the tasks are being created

resource_id number readonly

Unique identifier of the resource, a sequence has been started for

resource_type string readonly

Type of the resource, a sequence has been started for

Possible values:

  • lead
created_at string readonly

Date and time that the enrollment was created in UTC (ISO8601 format).

updated_at string readonly

Date and time of the last update on the enrollment in UTC (ISO8601 format).

sequence object readonly

The sequence object that this enrollment is started for

state string

State of the sequence. Used to resume blocked sequence and finish active sequence in PUT request.

Possible values:

  • active
  • blocked
  • finished
current_step_position number readonly

Zero-based index of current step position in the sequence

enrollment_steps array readonly

Array of enrollments steps that are explained in the previous point.

finished_at string readonly

Date at time when enrollment was finished. Only if sequence is already finished.

finished_reason string readonly

Reason for the enrollment to be finished.

Possible values:

  • manual
  • all_steps_completed
  • replied_to_email
  • resource_deleted
  • subscription_cancelled
  • task_deleted
finished_actor_id number readonly

Unique identified of user that finished the enrollment, only for manually finished enrollment.


Endpoints


Retrieve all sequence enrollments

Returns all sequence enrollments available to the user according to the parameters provided.

Parameters

Attribute Description
page number optional

Page number to start from. Page numbering starts at 1, and omitting the page parameter will return the first page.

e.g. ?page=2
per_page number optional

Number of records to return per page. Default limit is 25 and the maximum number that can be returned is 100.

e.g. ?per_page=20
ids string optional

Comma-separated list of enrollment identifiers to be returned in a request.

e.g. ?ids=1,2,3
resource_ids string optional

Comma-separated list of resource ids

e.g. ?resource_ids=1,2,3
resource_type string optional

Type of resources in resource_ids parameter

Possible values:

  • lead
e.g. ?resource_type=lead

Create an sequence enrollment

Create a new enrollment

Parameters

Attribute Description
sequence_id number required

Unique identifier of Sequence that resource should be enrolled to

e.g. "sequence_id": "1"
resource_type string required

Type of the resource, a sequence should be started for

Possible values:

  • lead
e.g. "resource_type": "lead"
resource_id number required

Unique identifier of resource that sequence should be started for

e.g. "resource_id": "4"
actor_id number optional

Unique identifier of the user on whose behalf sequence should be executed. This user will be emails sender and for that person tasks will be created.

e.g. "actor_id": "4"

Retrieve a single sequence enrollment

Returns a single enrollment available to the user, according to the unique enrollment identifier provided. If the specified enrollment does not exist, the request will return an error.

Parameters

Attribute Description
id number required

Unique identifier of the enrollment.


Update a sequence enrollment

Updates enrollment information. You can only change the state of enrollment. When enrollment is active you can choose to finish the enrollment by setting state to finished When enrollment is blocked you can choose to resume the enrollment by setting state to active

Parameters

Attribute Description
id number required

Unique identifier of enrollment

state required

State of the sequence. Used to resume blocked sequence and finish active sequence in PUT request.

Possible values:

  • active
  • finished