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.

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`

Action

GET /v2/sequence_enrollments

Examples

Retrieve all sequence enrollments

GET /v2/sequence_enrollments HTTP/1.1

Accept: application/json
Authorization: Bearer $ACCESS_TOKEN

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

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
response = RestClient.execute method: :get, url: "https://api.getbase.com/v2/sequence_enrollments", headers: headers

puts response

import requests
import json

response = requests.get(
    url='https://api.getbase.com/v2/sequence_enrollments',
    headers={
      'Accept': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    verify=True
  )

print(response.text)

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-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"
          },
          "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 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"`

Action

POST /v2/sequence_enrollments

Examples

Simple create

POST /v2/sequence_enrollments HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer $ACCESS_TOKEN

{
  "data": {
    "sequence_id": 554,
    "resource_id": 12866615,
    "resource_type": "lead"
  },
  "meta": {
    "type": "sequence_enrollment"
  }
}

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"
  }
}'

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Content-Type" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
body = '{
"data": {
"sequence_id": 554,
"resource_id": 12866615,
"resource_type": "lead"
},
"meta": {
"type": "sequence_enrollment"
}
}
'
response = RestClient.execute method: :post, url: "https://api.getbase.com/v2/sequence_enrollments", payload: body, headers: headers

puts response

import requests
import json

payload = {
  'data': {
    'sequence_id': 554,
    'resource_id': 12866615,
    'resource_type': 'lead'
  },
  'meta': {
    'type': 'sequence_enrollment'
  }
}

response = requests.post(
    url='https://api.getbase.com/v2/sequence_enrollments',
    headers={
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    data=json.dumps(payload),
    verify=True
  )

print(response.text)

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-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"
      },
      "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

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.

Action

GET /v2/sequence_enrollments/:id

Examples

Retrieve a single sequence enrollment with id 1

GET /v2/sequence_enrollments/1 HTTP/1.1

Accept: application/json
Authorization: Bearer $ACCESS_TOKEN

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

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
response = RestClient.execute method: :get, url: "https://api.getbase.com/v2/sequence_enrollments/1", headers: headers

puts response

import requests
import json

response = requests.get(
    url='https://api.getbase.com/v2/sequence_enrollments/1',
    headers={
      'Accept': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    verify=True
  )

print(response.text)

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-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"
      },
      "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

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

Action

PUT /v2/sequence_enrollments/:id

Examples

Update a sequence enrollment with id 1

PUT /v2/sequence_enrollments/1 HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer $ACCESS_TOKEN

{
  "data": {
    "state": "finished"
  }
}

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"
  }
}'

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Content-Type" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
body = '{
  "data": {
    "state": "finished"
  }
}

'
response = RestClient.execute method: :put, url: "https://api.getbase.com/v2/sequence_enrollments/1", payload: body, headers: headers

puts response

import requests
import json

payload = {
  'data': {
    'state': 'finished'
  }
}

response = requests.put(
    url='https://api.getbase.com/v2/sequence_enrollments/1',
    headers={
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    data=json.dumps(payload),
    verify=True
  )

print(response.text)

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-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"
      },
      "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"
  }
}

Sequence Enrollments

EnrollmentStep properties

EnrollmentStepAction properties

Properties

Possible values:

Possible values:

Possible values:

Endpoints

Retrieve all sequence enrollments

Parameters

Possible values:

Create an sequence enrollment

Parameters

Possible values:

Retrieve a single sequence enrollment

Parameters

Update a sequence enrollment

Parameters

Possible values: