Sequence Enrollments
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 OKContent-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 OKContent-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 OKContent-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 OKContent-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_idsis specified -> only these sequences will be finished for given resource.sequence_idsis empty ornullor 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 OKContent-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 OKContent-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"}}