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

  • start a sequence for a resource (lead or contact): create sequence enrollment for a given resource
  • stop the sequence for a resource: update the enrollment with status finished
  • resume blocked sequence for a resource: 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 a given resource (e.g. lead) and are not changed when sequence is changed. Those steps explain 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 Zero-based step's position in sequence for this enrollment
delay_from_previous_step Time that should pass in between execution of this and previous step
delay_from_previous_step_unit 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 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 Type of the step's action. Possible values:automated_email,task
action_properties 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 EnrollmentStepAction object defined in the table below

EnrollmentStepAction properties

Attribute Description
status 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 Date and time when the action was executed
estimated_execute_at Date and time when the action was scheduled to be executed
failure_reason Possible values:unknown,sendout_limited,recipient_invalid,auth,missing_merge_tags,attachment_limit_exceeded,sendout_disabled,quota_exceeded
task_content Task content, present only for action of type: task
task_id Task identifier, present only for action of type: task after the task was already created (statuses: in_progress,completed).

JSON format

Name Read Only Type Description
id true number Unique identifier of the enrollment.
actor_id true number Unique identifier of the user on whose behalf emails are being sent and for whom the tasks are being created
resource_id true number Unique identifier of the resource, a sequence has been started for
resource_type true string Type of the resource, a sequence has been started for. Possible values: lead, contact
created_at true string Date and time that the enrollment was created in UTC (ISO8601 format).
updated_at true string Date and time of the last update on the enrollment in UTC (ISO8601 format).
sequence true object The sequence object that this enrollment is started for
state false 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 true number Zero-based index of current step position in the sequence
enrollment_steps true array Array of enrollments steps that are explained in the previous point.
finished_at true string Date at time when enrollment was finished. Only if sequence is already finished.
finished_reason true string 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 true number Unique identified of user that finished the enrollment, only for manually finished enrollment.

Retrieve all sequence enrollments

GET /v2/sequence_enrollments

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

Parameters

Name Required Type In Description
page false number Query Page number to start from. Page numbering starts at 1, and omitting the page parameter will return the first page.
per_page false number Query Number of records to return per page. Default limit is 25 and the maximum number that can be returned is 100.
ids false string Query Comma-separated list of enrollment identifiers to be returned in a request.
resource_ids false string Query Comma-separated list of resource ids
resource_type false string Query Type of resources in "resource_ids" parameter. Possible values: lead, contact

Allowed for

  • Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/sequence_enrollments \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "items": [    {      "data": {        "id": 461,        "actor_id": 2168016,        "resource_type": "lead",        "resource_id": 12866615,        "created_at": "2020-04-08T07:25:20Z",        "updated_at": "2020-04-08T07:25:40Z",        "sequence": {          "data": {            "id": 11051,            "name": "Favourite food sequence",            "steps_total": 2,            "creator_id": 2168016,            "updated_at": "2020-06-22T12:38:55Z",            "created_at": "2020-04-08T06:40:16Z",            "unsubscribe_settings": {              "enabled": true,              "locale": "en-US"            }          },          "meta": {            "type": "sequence"          }        },        "state": "active",        "current_step_position": 1,        "enrollment_steps": {          "items": [            {              "data": {                "position": 0,                "delay_from_previous_step": 0,                "delay_from_previous_step_unit": "weekdays",                "overdue": false,                "action_type": "automated_email",                "action_properties": {                  "email_template_id": 13628,                  "is_reply": false                },                "action": {                  "data": {                    "status": "completed",                    "executed_at": "2020-06-22T12:59:57Z",                    "estimated_execute_at": null,                    "failure_reason": null                  },                  "meta": {                    "type": "action"                  }                }              },              "meta": {                "type": "enrollment_step"              }            },            {              "data": {                "position": 1,                "delay_from_previous_step": 1,                "delay_from_previous_step_unit": "weekdays",                "overdue": false,                "action_type": "automated_email",                "action_properties": {                  "email_template_id": 13629,                  "is_reply": true                },                "action": {                  "data": {                    "status": "scheduled",                    "executed_at": null,                    "estimated_execute_at": "2020-06-23T12:59:57Z",                    "failure_reason": null                  },                  "meta": {                    "type": "action"                  }                }              },              "meta": {                "type": "enrollment_step"              }            }          ],          "meta": {            "type": "collection",            "count": 1          }        },        "finished_at": null,        "finished_reason": null,        "finished_actor_id": null      },      "meta": {        "type": "sequence_enrollment"      }    }  ],  "meta": {    "count": 1,    "links": {      "self": "http://api.getbase.com/v2/sequence_enrollments"    },    "type": "collection"  }}

Create a sequence enrollment

POST /v2/sequence_enrollments

Create a new enrollment

Parameters

Name Required Type In Description
sequence_id true number Body Unique identifier of Sequence that resource should be enrolled to
resource_type true string Body Type of the resource, a sequence should be started for. Possible values, lead, contact
resource_id true number Body Unique identifier of resource that sequence should be started for
actor_id false number Body 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.

Allowed for

  • Agents

Using cURL

curl -v -X POST https://api.getbase.com/v2/sequence_enrollments \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "sequence_id": 554,    "resource_id": 12866615,    "resource_type": "lead"  },  "meta": {    "type": "sequence_enrollment"  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 11752426,    "actor_id": 2168016,    "resource_type": "lead",    "resource_id": 12866615,    "created_at": "2020-12-15T19:58:53Z",    "updated_at": "2020-12-15T19:58:53Z",    "sequence": {      "data": {        "id": 554,        "name": "Warm approach after webinar",        "steps_total": 2,        "creator_id": 2168016,        "updated_at": "2020-04-09T07:35:23Z",        "created_at": "2020-03-31T06:17:01Z",        "unsubscribe_settings": {          "enabled": true,          "locale": "en-US"        }      },      "meta": {        "type": "sequence"      }    },    "state": "active",    "current_step_position": 0,    "enrollment_steps": {      "items": [        {          "data": {            "position": 0,            "delay_from_previous_step": 0,            "delay_from_previous_step_unit": "weekdays",            "overdue": false,            "action_type": "automated_email",            "action_properties": {              "email_template_id": 9606,              "is_reply": false            },            "action": {              "data": {                "status": "scheduled",                "executed_at": null,                "estimated_execute_at": "2020-12-15T19:58:53.526Z",                "failure_reason": null              },              "meta": {                "type": "action"              }            }          },          "meta": {            "type": "enrollment_step"          }        },        {          "data": {            "position": 1,            "delay_from_previous_step": 1,            "delay_from_previous_step_unit": "weekdays",            "overdue": false,            "action_type": "automated_email",            "action_properties": {              "email_template_id": 9607,              "is_reply": false            },            "action": {              "data": {                "status": "scheduled",                "executed_at": null,                "estimated_execute_at": "2020-12-16T19:58:53.526Z",                "failure_reason": null              },              "meta": {                "type": "action"              }            }          },          "meta": {            "type": "enrollment_step"          }        }      ],      "meta": {        "type": "collection",        "count": 2      }    },    "finished_at": null,    "finished_reason": null,    "finished_actor_id": null  },  "meta": {    "type": "sequence_enrollment"  }}

Retrieve a single sequence enrollment

GET /v2/sequence_enrollments/:id

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

Name Required Type In Description
id true number Query Unique identifier of the enrollment.

Allowed for

  • Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/sequence_enrollments/1 \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 11752426,    "actor_id": 2168016,    "resource_type": "lead",    "resource_id": 12866615,    "created_at": "2020-12-15T19:58:53Z",    "updated_at": "2020-12-15T19:58:53Z",    "sequence": {      "data": {        "id": 554,        "name": "Warm approach after webinar",        "steps_total": 2,        "creator_id": 2168016,        "updated_at": "2020-04-09T07:35:23Z",        "created_at": "2020-03-31T06:17:01Z",        "unsubscribe_settings": {          "enabled": true,          "locale": "en-US"        }      },      "meta": {        "type": "sequence"      }    },    "state": "active",    "current_step_position": 0,    "enrollment_steps": {      "items": [        {          "data": {            "position": 0,            "delay_from_previous_step": 0,            "delay_from_previous_step_unit": "weekdays",            "overdue": false,            "action_type": "automated_email",            "action_properties": {              "email_template_id": 9606,              "is_reply": false            },            "action": {              "data": {                "status": "scheduled",                "executed_at": null,                "estimated_execute_at": "2020-12-15T19:58:53.526Z",                "failure_reason": null              },              "meta": {                "type": "action"              }            }          },          "meta": {            "type": "enrollment_step"          }        },        {          "data": {            "position": 1,            "delay_from_previous_step": 1,            "delay_from_previous_step_unit": "weekdays",            "overdue": false,            "action_type": "automated_email",            "action_properties": {              "email_template_id": 9607,              "is_reply": false            },            "action": {              "data": {                "status": "scheduled",                "executed_at": null,                "estimated_execute_at": "2020-12-16T19:58:53.526Z",                "failure_reason": null              },              "meta": {                "type": "action"              }            }          },          "meta": {            "type": "enrollment_step"          }        }      ],      "meta": {        "type": "collection",        "count": 2      }    },    "finished_at": null,    "finished_reason": null,    "finished_actor_id": null  },  "meta": {    "type": "sequence_enrollment"  }}

Update a sequence enrollment

PUT /v2/sequence_enrollments/:id

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

Name Required Type In Description
id true number Query Unique identifier of enrollment
state false string Body State of the sequence. Used to resume blocked sequence and finish active sequence in PUT request. Possible values:active, finished

Allowed for

  • Agents

Using cURL

curl -v -X PUT https://api.getbase.com/v2/sequence_enrollments/1 \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "state": "finished"  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 11752426,    "actor_id": 2168016,    "resource_type": "lead",    "resource_id": 12866615,    "created_at": "2020-12-15T19:58:54Z",    "updated_at": "2020-12-17T09:20:11Z",    "sequence": {      "data": {        "id": 554,        "name": "Warm approach after webinar",        "steps_total": 2,        "creator_id": 2168016,        "updated_at": "2020-04-09T07:35:23Z",        "created_at": "2020-03-31T06:17:01Z",        "unsubscribe_settings": {          "enabled": true,          "locale": "en-US"        }      },      "meta": {        "type": "sequence"      }    },    "state": "finished",    "current_step_position": 0,    "enrollment_steps": {      "items": [        {          "data": {            "position": 0,            "delay_from_previous_step": 0,            "delay_from_previous_step_unit": "weekdays",            "overdue": false,            "action_type": "automated_email",            "action_properties": {              "email_template_id": 9606,              "is_reply": false            },            "action": {              "data": {                "status": "cancelled",                "executed_at": null,                "estimated_execute_at": null,                "failure_reason": null              },              "meta": {                "type": "action"              }            }          },          "meta": {            "type": "enrollment_step"          }        },        {          "data": {            "position": 1,            "delay_from_previous_step": 1,            "delay_from_previous_step_unit": "weekdays",            "overdue": false,            "action_type": "automated_email",            "action_properties": {              "email_template_id": 9607,              "is_reply": false            },            "action": {              "data": {                "status": "cancelled",                "executed_at": null,                "estimated_execute_at": null,                "failure_reason": null              },              "meta": {                "type": "action"              }            }          },          "meta": {            "type": "enrollment_step"          }        }      ],      "meta": {        "type": "collection",        "count": 2      }    },    "finished_at": "2020-12-15T20:46:33Z",    "finished_reason": "manual",    "finished_actor_id": 2168016  },  "meta": {    "type": "sequence_enrollment"  }}

Finish sequence enrollments for given resource

POST /v2/sequence_enrollments/finish_ongoing_for_resource

Finishes ongoing sequence enrollments for a given resource (e.g. lead).

Behaviour based on sequence_ids param:

  • sequence_ids is specified -> only these sequences will be finished for given resource.
  • sequence_ids is empty or null or not specified -> all sequences will be finished for given resource.

Parameters

Name Required Type In Description
resource_id false number Body Unique identifier of the resource, to finish the sequences for.
resource_type false string Body Type of the resource, to finish the sequences for. Possible values: lead, contact
sequence_ids false array Body Optional array with IDs of sequences to finish. If is empty or skipped then all ongoing sequences will be finished.

Allowed for

  • Agents

Using cURL

Finish all sequences for given lead

curl -v -X POST https://api.getbase.com/v2/sequence_enrollments/finish_ongoing_for_resource \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "resource_type": "lead",    "resource_id": 5  }}'

Finish one given sequence for given lead

curl -v -X POST https://api.getbase.com/v2/sequence_enrollments/finish_ongoing_for_resource \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "resource_type": "lead",    "resource_id": 5,    "sequence_ids": [      2222    ]  }}'

Example responses

Finish all sequences for given lead

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "enrollment_action": "finish_ongoing",    "updated_enrollments": {      "items": [        {          "data": {            "id": 1,            "actor_id": 2168016,            "resource_type": "lead",            "resource_id": 5,            "created_at": "2020-12-15T19:58:54Z",            "updated_at": "2020-12-17T09:20:11Z",            "sequence": {              "data": {                "id": 554,                "name": "Warm approach after webinar",                "steps_total": 2,                "creator_id": 2168016,                "updated_at": "2020-04-09T07:35:23Z",                "created_at": "2020-03-31T06:17:01Z",                "unsubscribe_settings": {                  "enabled": true,                  "locale": "en-US"                }              },              "meta": {                "type": "sequence"              }            },            "state": "finished",            "current_step_position": 0,            "enrollment_steps": {              "items": [                {                  "data": {                    "position": 0,                    "delay_from_previous_step": 0,                    "delay_from_previous_step_unit": "weekdays",                    "overdue": false,                    "action_type": "automated_email",                    "action_properties": {                      "email_template_id": 1,                      "is_reply": false                    },                    "action": {                      "data": {                        "status": "cancelled",                        "executed_at": null,                        "estimated_execute_at": null,                        "failure_reason": null                      },                      "meta": {                        "type": "action"                      }                    }                  },                  "meta": {                    "type": "enrollment_step"                  }                },                {                  "data": {                    "position": 1,                    "delay_from_previous_step": 1,                    "delay_from_previous_step_unit": "weekdays",                    "overdue": false,                    "action_type": "automated_email",                    "action_properties": {                      "email_template_id": 2,                      "is_reply": false                    },                    "action": {                      "data": {                        "status": "cancelled",                        "executed_at": null,                        "estimated_execute_at": null,                        "failure_reason": null                      },                      "meta": {                        "type": "action"                      }                    }                  },                  "meta": {                    "type": "enrollment_step"                  }                }              ],              "meta": {                "type": "collection",                "count": 2              }            },            "finished_at": "2020-12-15T20:46:33Z",            "finished_reason": "manual",            "finished_actor_id": 2168016          },          "meta": {            "type": "sequence_enrollment"          }        },        {          "data": {            "id": 2,            "actor_id": 2168016,            "resource_type": "lead",            "resource_id": 5,            "created_at": "2020-12-15T19:58:54Z",            "updated_at": "2020-12-17T09:20:11Z",            "sequence": {              "data": {                "id": 2222,                "name": "Laid back approach with emoji",                "steps_total": 2,                "creator_id": 2168016,                "updated_at": "2020-04-09T07:35:23Z",                "created_at": "2020-03-31T06:17:01Z",                "unsubscribe_settings": {                  "enabled": true,                  "locale": "en-US"                }              },              "meta": {                "type": "sequence"              }            },            "state": "finished",            "current_step_position": 0,            "enrollment_steps": {              "items": [                {                  "data": {                    "position": 0,                    "delay_from_previous_step": 0,                    "delay_from_previous_step_unit": "weekdays",                    "overdue": false,                    "action_type": "automated_email",                    "action_properties": {                      "email_template_id": 3,                      "is_reply": false                    },                    "action": {                      "data": {                        "status": "cancelled",                        "executed_at": null,                        "estimated_execute_at": null,                        "failure_reason": null                      },                      "meta": {                        "type": "action"                      }                    }                  },                  "meta": {                    "type": "enrollment_step"                  }                },                {                  "data": {                    "position": 1,                    "delay_from_previous_step": 5,                    "delay_from_previous_step_unit": "weekdays",                    "overdue": false,                    "action_type": "automated_email",                    "action_properties": {                      "email_template_id": 4,                      "is_reply": false                    },                    "action": {                      "data": {                        "status": "cancelled",                        "executed_at": null,                        "estimated_execute_at": null,                        "failure_reason": null                      },                      "meta": {                        "type": "action"                      }                    }                  },                  "meta": {                    "type": "enrollment_step"                  }                }              ],              "meta": {                "type": "collection",                "count": 2              }            },            "finished_at": "2020-12-15T20:46:33Z",            "finished_reason": "manual",            "finished_actor_id": 2168016          },          "meta": {            "type": "sequence_enrollment"          }        }      ],      "meta": {        "type": "collection",        "count": 2      }    }  },  "meta": {    "type": "sequence_enrollment_action"  }}

Finish one given sequence for given lead

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "enrollment_action": "finish_ongoing",    "updated_enrollments": {      "items": [        {          "data": {            "id": 2,            "actor_id": 2168016,            "resource_type": "lead",            "resource_id": 5,            "created_at": "2020-12-15T19:58:54Z",            "updated_at": "2020-12-17T09:20:11Z",            "sequence": {              "data": {                "id": 2222,                "name": "Laid back approach with emoji",                "steps_total": 2,                "creator_id": 2168016,                "updated_at": "2020-04-09T07:35:23Z",                "created_at": "2020-03-31T06:17:01Z",                "unsubscribe_settings": {                  "enabled": true,                  "locale": "en-US"                }              },              "meta": {                "type": "sequence"              }            },            "state": "finished",            "current_step_position": 0,            "enrollment_steps": {              "items": [                {                  "data": {                    "position": 0,                    "delay_from_previous_step": 0,                    "delay_from_previous_step_unit": "weekdays",                    "overdue": false,                    "action_type": "automated_email",                    "action_properties": {                      "email_template_id": 3,                      "is_reply": false                    },                    "action": {                      "data": {                        "status": "cancelled",                        "executed_at": null,                        "estimated_execute_at": null,                        "failure_reason": null                      },                      "meta": {                        "type": "action"                      }                    }                  },                  "meta": {                    "type": "enrollment_step"                  }                },                {                  "data": {                    "position": 1,                    "delay_from_previous_step": 5,                    "delay_from_previous_step_unit": "weekdays",                    "overdue": false,                    "action_type": "automated_email",                    "action_properties": {                      "email_template_id": 4,                      "is_reply": false                    },                    "action": {                      "data": {                        "status": "cancelled",                        "executed_at": null,                        "estimated_execute_at": null,                        "failure_reason": null                      },                      "meta": {                        "type": "action"                      }                    }                  },                  "meta": {                    "type": "enrollment_step"                  }                }              ],              "meta": {                "type": "collection",                "count": 2              }            },            "finished_at": "2020-12-15T20:46:33Z",            "finished_reason": "manual",            "finished_actor_id": 2168016          },          "meta": {            "type": "sequence_enrollment"          }        }      ],      "meta": {        "type": "collection",        "count": 1      }    }  },  "meta": {    "type": "sequence_enrollment_action"  }}