Sequences

Sequences can be used to engage with leads. They must be created by users via web app, while leads can also be programmatically added into existing sequences. Example flow:

Sequences are created by users in the web app
The API client lists the sequences via API applying the necessary filters
Collect the sequences from response.sequences
Iterate the endpoint through response._links.next.href while respecting the Retry-After HTTP Header
Add leads to the desired sequences

Sequences Endpoints

List Sequences

Sequence Object

Field	Type	Description
`id`	string	The ID of the Sequence
`name`	string	The name of the Sequence
`status`	string	The status of the Sequence:
		`active`: The sequence is live and can accept new leads
		`draft`: The sequence is not launched yet and cannot accept leads programmatically
		`archived`: The sequence is archived and cannot accept leads programmatically
		`archiving`: The sequence is being archived and cannot accept leads programmatically
		`paused`: The sequence is paused and can accept new leads
		`pausing`: The sequence is being paused and cannot accept leads programmatically
		`resuming`: The sequence is being resumed and cannot accept leads programmatically
`created_at`	string	The creation date in ISO 8601
`updated_at`	string	The last update date in ISO 8601
`created_by_user_id`	string	The user id of the creator of the Sequence (refer to the `Users` API)
`created_by_user_email`	string	The email of the creator of the Sequence
`dynamic_fields_used`	array of strings	Lead data fields (see the Add leads `data` property) referenced by the Sequence’s active stages
`_links`	array of links	Contains useful links related to this resource

dynamic_fields_used can include more fields than are strictly required to add a lead. It lists every field the sequence’s active stages reference, including ones that have a fallback and therefore don’t need to be present on every lead:

Fields referenced only inside a conditional block (e.g. {% if custom_field_1 %}...{% elsif custom_field_2 %}...{% endif %}) — the sequence renders fine even if none of them are present on a given lead, since the block is simply skipped.
Fields with a Liquid default filter (e.g. {{ company_name | default: "there" }}) — the sequence falls back to the default value when the field is missing.

Treat this list as “fields the sequence may use,” not “fields every lead must have” — if a field that is actually required is missing for a lead, adding it will fail with the missing_lead_field error described below.

Request format

Retrieve a list of Sequences:

GET /sequences HTTP/1.1
Authorization: Bearer {{API Key}}

curl -X GET https://api.amplemarket.com/sequences \
	-H "Authorization: Bearer {{API Key}}"

Sequences can be filtered using

name (case insensitive search)
status
created_by_user_id
created_by_user_email

Response

This will return a 200 OK with a list of Sequences:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "sequences": [
    {
      "id": "311d73f042157b352c724975970e4369dba30777",
      "name": "Sample sequence",
      "status": "active",
      "created_by_user_id": "edbec9eb3b3d8d7c1c24ab4dcac572802b14e5f1",
      "created_by_user_email": "foo-49@email.com",
      "created_at": "2025-01-07T10:16:01Z",
      "updated_at": "2025-01-07T10:16:01Z",
      "dynamic_fields_used": ["first_name", "company_name"]
    },
    {
      "id": "e6890fa2c0453fd2691c06170293131678deb47b",
      "name": "A sequence",
      "status": "active",
      "created_by_user_id": "edbec9eb3b3d8d7c1c24ab4dcac572802b14e5f1",
      "created_by_user_email": "foo-49@email.com",
      "created_at": "2025-01-07T10:16:01Z",
      "updated_at": "2025-01-07T10:16:01Z",
      "dynamic_fields_used": []
    }
  ],
  "_links": {
    "self": {
      "href": "/sequences?page[size]=20"
    },
    "next": {
      "href": "/sequences?page[after]=e6890fa2c0453fd2691c06170293131678deb47b&page[size]=20"
    }
  }
}

If the result set contains more entries than the page size, then pagination is required traverse them all and can be done using the links such as: response._links.next.href (e.g. GET /sequences?page[after]=e6890fa2c0453fd2691c06170293131678deb47b&page[size]=20).

Add leads to a Sequence

This endpoint allows users to add one or more leads to an existing active sequence in Amplemarket. It supports flexible lead management with customizable distribution settings, real-time validations, and asynchronous processing for improved scalability. For specific API details, please refer to the API specification.

This endpoint does not enrich the lead information, it only uses the information sent in the payload. Refer to the People Search guide if you need to gather more information, or the Email Validation guide to ensure the email is valid.

This endpoint does not update leads already in sequence, it can only add new ones

Choosing the sequence

A sequence is identified by its id, which is used in the POST request:

POST https://api.amplemarket.com/sequences/cb4925debf37ccb6ae1244317697e0f/leads

To retrieve it, you have two options:

Use the “List Sequences” endpoint
Go to the Amplemarket Dashboard, navigate to Sequences, and choose your Sequence.

In the URL bar of your browser, you will find a URL that looks like this: https://app.amplemarket.com/dashboard/sequences/cb4925debf37ccb6ae1244317697e0f
In this case, the sequence id is cb4925debf37ccb6ae1244317697e0f

Request format

The request has two main properties:

leads: An array of objects, each of them representing a lead to be added to the sequence. Each lead object must include at least an email or linkedin_url field at the root level of the object. These properties are used to check multiple conditions, including exclusion lists and whether they are already present in other sequences. If you do not have either one, you may omit the field or set it to null. Other supported properties:
- data: holds other lead data fields, such as first_name and company_domain
- overrides: used to bypass certain safety checks. It can be omitted completely or partially, and the default value is false for each of the following overrides:
  - ignore_recently_contacted: whether to override the recently contacted check. Note that the time range used for considering a given lead as “recently contacted” is an account-wide setting managed by your Amplemarket account administrator
  - ignore_exclusion_list: whether to override the exclusion list
  - ignore_duplicate_leads_in_other_draft_sequences: whether to bypass the check for leads with the same email or linkedin_url present in other draft sequences
  - ignore_duplicate_leads_in_other_active_sequences: whether to bypass the check for leads with the same email or linkedin_url present in other active or paused sequences
settings: an optional object storing lead distribution configurations affecting all leads:
- leads_distribution: a string that can have 2 values:
  - sequence_senders: (default) the leads will be distributed across the mailboxes configured in the sequence settings
  - custom_mailboxes: the leads will be distributed across the mailboxes referred to by the /settings/mailboxes property, regardless of the sequence setting.
- mailboxes: an array of email addresses, that must correspond to mailboxes connected to the Amplemarket account. If /settings/leads_distribution is custom_mailboxes, this property will be used to assign the leads to the respective users and mailboxes. Otherwise, this property is ignored.

If you are trying to add leads to a sequence which has email stages, with no conditional logic, the lead must have the email field set

Request limits

Each request can have up to 250 leads, if you try to send more, the request will fail with an HTTP 400. Besides the email and linkedin_url, each lead can have up to 50 data fields on the data object. Both the data field names and values must be of the type String, field names can be up to 255 characters while values can be up to 1024 characters. The names of the data fields can only have lowercase letters, numbers or underscores (_), and must start with a letter. Some examples of rejected data field names:

Rejected	Accepted	Explanation
`FirstName`	`first_name`	Only lowercase letters are accepted
`first name`	`first_name`	Spaces are not accepted
`3_letter_name`	`three_letter_name`	Must start with a letter
`_special_field`	`special_field`	Must start with a letter

Request example

{
  "leads": [
    {
      "email": "lead1@example.com",
      "data": {
        "first_name": "John",
        "company_name": "Apple"
      }
    },
    {
      "email": "lead2@example.org",
      "data": {
        "first_name": "Jane",
        "company_name": "Salesforce"
      },
      "overrides": {
        "ignore_exclusion_list": true
      }
    }
  ],
  "settings": {
    "leads_distribution": "custom_mailboxes",
    "mailboxes": ["my_sales_mailbox@example.com"]
  }
}

Response format

There are 3 potential outcomes:

The request is successful, and it returns the number of leads that were added and skipped due to safety checks. Example:

{
  "total": 2,
  "total_added_to_sequence": 1,
  "duplicate_emails": [],
  "duplicate_linkedin_urls": [],
  "in_exclusion_list_and_skipped": [{"email": "lead1@example.com"}],
  "recently_contacted_and_skipped": [],
  "already_in_sequence_and_skipped": [],
  "in_other_draft_sequences_and_skipped": [],
  "in_other_active_sequences_and_skipped": []
}

Property name	Explanation
`total`	Total number of lead objects in the request
`total_added_to_sequence`	Total number of leads added to the sequence
`duplicate_emails`	List of email addresses that appeared duplicated in the request. Leads with duplicate emails will be skipped and not added to the sequence
`duplicate_linkedin_urls`	List of LinkedIn URLs that appeared duplicated in the request. Leads with duplicate LinkedIn URLs will be skipped and not added to the sequence
`in_exclusion_list_and_skipped`	List of lead objects (with just the `email` and `linkedin_url` fields) that were in the account exclusion list, and therefore not added to the sequence
`recently_contacted_and_skipped`	List of lead objects (with just the `email` and `linkedin_url` fields) that were recently contacted by the account, and therefore not added to the sequence
`already_in_sequence_and_skipped`	List of lead objects (with just the `email` and `linkedin_url` fields) that are already present in the sequence with the same contact fields, and therefore not added to the sequence
`in_other_draft_sequences_and_skipped`	List of lead objects (with just the `email` and `linkedin_url` fields) that are present in other draft sequences of the account, and therefore skipped
`in_other_active_sequences_and_skipped`	List of lead objects (with just the `email` and `linkedin_url` fields) that are present in other active sequences of the account, and therefore skipped

Checks corresponding to in_exclusion_list_and_skipped, recently_contacted_and_skipped, in_other_draft_sequences_and_skipped, and in_other_active_sequences_and_skipped can be bypased by using the overrides property on the lead object

The request was malformed in itself. In that case, the response will have the HTTP Status code 400, and the body will contain an indication of the error, following the standard format.

The request was correctly formatted, but due to other reasons the request cannot be completed. The response will have the HTTP Status code 422, and a single property validation_errors, which can indicate one or more problems. Example

{
  "validation_errors": [
    {
      "error_code": "missing_lead_field",
      "message": "Missing lead dynamic field 'it' on leads with indexes [1]"
    },
    {
      "error_code": "total_leads_exceed_limit",
      "message": "Number of leads 1020 would exceed the per-sequence limit of 1000"
    }
  ]
}

Error codes and their explanations

All error_code values have an associated message giving more details about the specific cause of failure. Some of the errors include:

`error_code`	Description
`"invalid_sequence_status"`	The sequence is in a status that does not allow adding new leads with this method. That typically is because the sequence is in the “Draft” or “Archived” states
`"missing_ai_credits"`	Some of the sequence users do not have enough credits to support additional leads
`"missing_feature_copywriter"`	Some of the sequence users do not have access to Duo features, and the sequence is using Duo Copywriter email stages or Duo Voice stages
`"missing_feature_dialer"`	The sequence has a phone call stage, and some of the users do not have a Dialer configured
`"missing_linkedin_account"`	The sequence has a stage that requires a LinkedIn account (such as Duo Copywriter or automatic LinkedIn stages), and not all sequence users have connected their LinkedIn account to Amplemarket
`"missing_voice_clone"`	The sequence has a Duo Voice stage, but a sequence user does not have an usable voice clone configured
`"missing_lead_field"`	The sequence requires a lead data field that was not provided in the request (such as an email address when there are email stages, or a data field used in the text)
`"missing_sender_field"`	The sequence requires a sender data field that a sequence user has not filled in yet
`"mailbox_unusable"`	A mailbox was selected to be used, but it cannot be used (e.g. due to disconnection or other errors)
`"max_leads_threshold_reached"`	Adding all the leads would make the sequence go over the account-wide per-sequence lead limit
`"other_validation_error"`	An unexpected validaton error has occurred

Common errors and pitfalls

Invalid email field: do not use placeholder values like "unknown" or "N/A". It is best to ommit the field or set it to null.
Linkedin URL field: to be used as an identifier of the lead, it should be put at the top level of the lead, not inside the data part of the lead.

Home

Guides

Sequences Endpoints

List Sequences

Sequence Object

Request format

Response

Links

Add leads to a Sequence

Choosing the sequence

Request format

Request limits

Request example

Response format

Error codes and their explanations

Common errors and pitfalls

​Sequences Endpoints

​List Sequences

​Sequence Object

​Request format

​Response

​Links

​Add leads to a Sequence

​Choosing the sequence

​Request format

​Request limits

​Request example

​Response format

​Error codes and their explanations

​Common errors and pitfalls

Sequences Endpoints

List Sequences

Sequence Object

Request format

Response

Links

Add leads to a Sequence

Choosing the sequence

Request format

Request limits

Request example

Response format

Error codes and their explanations

Common errors and pitfalls