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

AttributeDescription
positionZero-based step's position in sequence for this enrollment
delay_from_previous_stepTime that should pass in between execution of this and previous step
delay_from_previous_step_unitUnit of the time that should pass in between execution of this and previous step. Possible values: hours, weekdays - days between Monday and Friday
overdueIndicates 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_typeType of the step's action. Possible values:automated_email,task
action_propertiesObject 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
actionEnrollmentStepAction object defined in the table below

EnrollmentStepAction properties

AttributeDescription
statusStep'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_atDate and time when the action was executed
estimated_execute_atDate and time when the action was scheduled to be executed
failure_reasonPossible values:unknown,sendout_limited,recipient_invalid,auth,missing_merge_tags,attachment_limit_exceeded,sendout_disabled,quota_exceeded
task_contentTask content, present only for action of type: task
task_idTask identifier, present only for action of type: task after the task was already created (statuses: in_progress,completed).

JSON format

NameRead OnlyTypeDescription
idtruenumberUnique identifier of the enrollment.
actor_idtruenumberUnique identifier of the user on whose behalf emails are being sent and for whom the tasks are being created
resource_idtruenumberUnique identifier of the resource, a sequence has been started for
resource_typetruestringType of the resource, a sequence has been started for. Possible values: lead, contact
created_attruestringDate and time that the enrollment was created in UTC (ISO8601 format).
updated_attruestringDate and time of the last update on the enrollment in UTC (ISO8601 format).
sequencetrueobjectThe sequence object that this enrollment is started for
statefalsestringState of the sequence. Used to resume blocked sequence and finish active sequence in PUT request. Possible values: active, blocked, finished
current_step_positiontruenumberZero-based index of current step position in the sequence
enrollment_stepstruearrayArray of enrollments steps that are explained in the previous point.
finished_attruestringDate at time when enrollment was finished. Only if sequence is already finished.
finished_reasontruestringReason for the enrollment to be finished. Possible values: manual, all_steps_completed, replied_to_email, resource_deleted, subscription_cancelled, task_deleted
finished_actor_idtruenumberUnique 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

NameRequiredTypeInDescription
pagefalsenumberQueryPage number to start from. Page numbering starts at 1, and omitting the page parameter will return the first page.
per_pagefalsenumberQueryNumber of records to return per page. Default limit is 25 and the maximum number that can be returned is 100.
idsfalsestringQueryComma-separated list of enrollment identifiers to be returned in a request.
resource_idsfalsestringQueryComma-separated list of resource ids
resource_typefalsestringQueryType 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

NameRequiredTypeInDescription
sequence_idtruenumberBodyUnique identifier of Sequence that resource should be enrolled to
resource_typetruestringBodyType of the resource, a sequence should be started for. Possible values, lead, contact
resource_idtruenumberBodyUnique identifier of resource that sequence should be started for
actor_idfalsenumberBodyUnique 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

NameRequiredTypeInDescription
idtruenumberQueryUnique 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

NameRequiredTypeInDescription
idtruenumberQueryUnique identifier of enrollment
statefalsestringBodyState 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

NameRequiredTypeInDescription
resource_idfalsenumberBodyUnique identifier of the resource, to finish the sequences for.
resource_typefalsestringBodyType of the resource, to finish the sequences for. Possible values: lead, contact
sequence_idsfalsearrayBodyOptional 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"  }}