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:

1. Sequences are created by users in the web app

2. The API client lists the sequences via API applying the necessary filters

3. Collect the sequences from response.sequences

4. Iterate the endpoint through response._links.next.href while respecting the Retry-After HTTP Header

5. Add leads to the desired sequences

​

Sequences Endpoints

​

List Sequences

​

Sequence Object

​

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"
    },
    {
      "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"
    }
  ],
  "_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 transverse them all and can be done using the links such as: response._links.next.href (e.g. GET /sequences/81f63c2e-edbd-4c1a-9168-542ede3ce98f?page[size]=100&page[after]=81f63c2e-edbd-4c1a-9168-542ede3ce98a).

​

Links

• self - GET points back to the same object

• next - GET points to the next page of entries, when available

• prev - GET points to the previous page of entries, when available

​

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.

​

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:

1. Use the “List Sequences” endpoint
2. 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. These properties are used to check multiple conditions, including exclusion lists and whether they are already present in other sequences. 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.

​

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 512 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:

​

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:

  Copy

  {
    "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

  Copy

  {
    "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: