Outreach sequences — create, update, approve, abort, archive, enrollment and activity. 12 operation(s) from the published Apollo OpenAPI.
openapi: 3.1.0
info:
title: Apollo.io Sequences API
version: '1.0'
summary: Programmatic access to Apollo's sales intelligence and engagement platform — data enrichment,
prospect and company search, and go-to-market workflow management.
description: 'The Apollo API provides programmatic access to [Apollo](https://www.apollo.io/), the all-in-one
sales intelligence and engagement platform. Use it to enrich people and company data (individually
or in bulk), search Apollo''s database of over 240 million contacts and 30 million companies, and
manage accounts, contacts, deals, sequences, tasks, calls, and conversations in your go-to-market
workflows.
## Base URL
All API requests are made to `https://api.apollo.io/api/v1`.
## Authentication
- **Apollo users** authenticate with an API key passed in the `x-api-key` request header. See [Create
API Keys](https://docs.apollo.io/docs/create-api-key).
- **Apollo partners** building integrations on behalf of mutual users authenticate with the [OAuth
2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).
## Rate limits & credits
Rate limits and credit consumption depend on your [Apollo pricing plan](https://docs.apollo.io/docs/api-pricing).
Check your current limits and usage with the [View API Usage Stats and Rate Limits](https://docs.apollo.io/reference/view-api-usage-stats)
endpoint. For more details, see [Rate Limits](https://docs.apollo.io/reference/rate-limits) and the
[API FAQs](https://docs.apollo.io/docs/apollo-api-faqs).
New to the API? Start with the [Apollo API overview](https://docs.apollo.io/reference/apollo-api).'
termsOfService: https://www.apollo.io/terms/api
contact:
name: Apollo API Support
url: https://docs.apollo.io/
servers:
- url: https://api.apollo.io/api/v1
tags:
- name: Sequences
description: Manage outreach sequences and the contacts enrolled in them.
security:
- apiKey: []
- bearerAuth: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: '[Recommended] API key, passed in the `x-api-key` request header.
See [Create API Keys](https://docs.apollo.io/docs/create-api-key).'
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'OAuth 2.0 access token, used by Apollo partners building integrations.
See the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).'
paths:
/emailer_schedules:
get:
summary: List Email Schedules
description: '## Endpoint essentials
**API key access:** `api/v1/emailer_schedules/index` or `Master API key`
**OAuth scopes:** `emailer_schedules_list`
**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).
<a href="https://knowledge.apollo.io/hc/en-us/articles/4409477927309-Configure-a-Sequence-Sending-Schedule"
target="_blank">Sending schedules</a> control the days and times that Apollo sends emails for
your sequences. You can configure multiple sending schedules for different sequences, for example
to match your audience''s time zone or when your contacts are most likely to engage.<br><br>Use
the List Email Schedules endpoint to retrieve every sending schedule that has been created for
your team''s Apollo account. For each schedule, the response returns its ID, name, time zone,
weekly sending windows, and whether it is your team''s default schedule.<br><br>Use a schedule''s
`id` as the `emailer_schedule_id` when you <a href="https://docs.apollo.io/reference/create-sequence"
target="_blank">create a sequence</a> or <a href="https://docs.apollo.io/reference/update-sequence"
target="_blank">update a sequence</a> to control when that sequence''s emails are sent.'
tags:
- Sequences
operationId: list-email-schedules
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"emailer_schedules\": [\n {\n \"id\": \"6605a1f2e4b0c80012a3d456\"\
,\n \"name\": \"Normal Business Hours\",\n \"default\": true,\n \"\
time_zone\": \"America/Los_Angeles\",\n \"schedule_hash\": {\n \"monday\"\
: [[8, 17]],\n \"tuesday\": [[8, 17]],\n \"wednesday\": [[8, 17]],\n\
\ \"thursday\": [[8, 17]],\n \"friday\": [[8, 17]]\n },\n \
\ \"created_at\": \"2024-03-28T18:56:24.067Z\",\n \"use_contacts_time_zone\"\
: true,\n \"skip_holidays\": true\n },\n {\n \"id\": \"6605a2b7e4b0c80012a3d789\"\
,\n \"name\": \"West Coast Afternoons\",\n \"default\": false,\n \"\
time_zone\": \"America/New_York\",\n \"schedule_hash\": {\n \"monday\"\
: [[12, 17]],\n \"wednesday\": [[12, 17]],\n \"friday\": [[12, 17]]\n\
\ },\n \"created_at\": \"2024-04-02T14:10:05.512Z\",\n \"use_contacts_time_zone\"\
: false,\n \"skip_holidays\": true\n }\n ]\n}"
schema:
type: object
properties:
emailer_schedules:
type: array
description: The list of sending schedules that belong to your team.
items:
type: object
properties:
id:
type: string
description: The unique Apollo ID for the sending schedule. Use this value as
the `emailer_schedule_id` when you create or update a sequence.
example: 6605a1f2e4b0c80012a3d456
name:
type: string
description: The name of the sending schedule.
example: Normal Business Hours
default:
type: boolean
description: Whether this is the default sending schedule for your team. Only
one schedule can be the default at a time.
example: true
time_zone:
type: string
description: The IANA time zone that the schedule's sending windows are defined
in, for example `America/Los_Angeles`.
example: America/Los_Angeles
schedule_hash:
type: object
description: The weekly sending windows, keyed by day of the week. Each day
maps to an array of `[start_hour, end_hour]` pairs using 24-hour times, so
`[[8, 17]]` means 8:00 AM to 5:00 PM. Days with no sending windows are omitted.
created_at:
type: string
description: The timestamp for when the schedule was created, in ISO 8601 format.
example: '2024-03-28T18:56:24.067Z'
use_contacts_time_zone:
type: boolean
description: Whether Apollo sends emails according to each contact's own time
zone instead of the schedule's `time_zone`.
example: true
skip_holidays:
type: boolean
description: Whether Apollo skips sending emails on holidays.
example: true
'401':
description: '401'
content:
text/plain:
examples:
Check API key:
value: Invalid API key. See https://docs.apollo.io/reference/authentication for how
to authenticate.
'403':
description: '403'
content:
application/json:
examples:
Need master API key:
value: "{\n \"error\": \"This API key is not authorized to access api/v1/emailer_schedules/index.\
\ Request an API key from your administrator that includes this endpoint in its configured\
\ scope.\",\n \"error_code\": \"API_INACCESSIBLE\"\n}"
schema:
type: object
properties:
error:
type: string
example: This API key is not authorized to access api/v1/emailer_schedules/index.
Request an API key from your administrator that includes this endpoint in its configured
scope.
error_code:
type: string
example: API_INACCESSIBLE
'429':
description: '429'
content:
application/json:
examples:
Too many requests:
value: "{\n \"message\": \"The maximum number of api calls allowed for api/v1/emailer_schedules\
\ is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.\"\
\n}"
schema:
type: object
properties:
message:
type: string
example: The maximum number of api calls allowed for api/v1/emailer_schedules is 600
times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.
deprecated: false
/emailer_campaigns/search:
post:
summary: Search for Sequences
description: '## Endpoint essentials
**API key access:** `api/v1/emailer_campaigns/search` or `Master API key`
**OAuth scopes:** `emailer_campaigns_search`
**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).
<a href="https://knowledge.apollo.io/hc/en-us/articles/4409237165837-Sequences-Overview" target="_blank">Sequences</a>
are outreach campaigns that sales teams use to reach out to contacts over a planned period of
time.<br><br>Use the Search for Sequences endpoint to search for the sequences that have been
created for your team''s Apollo account.'
tags:
- Sequences
operationId: search-for-sequences
parameters:
- name: q_name
in: query
description: 'Add keywords to narrow the search of the sequences in your team''s Apollo account.
<br><br>Keywords should directly match at least part of a sequence''s name. For example, searching
the keyword `marketing` might return the result `NY Marketing Sequence`, but not `NY Marketer
Conference 2025 attendees`. <br><br>This parameter only searches sequence names, not other sequence
fields. <br><br>Example: `marketing conference attendees`'
schema:
type: string
- name: page
in: query
description: 'The page number of the Apollo data that you want to retrieve. <br><br>Use this parameter
in combination with the `per_page` parameter to make search results for navigable and improve
the performance of the endpoint. <br><br>Example: `4`'
schema:
type: string
- name: per_page
in: query
description: 'The number of search results that should be returned for each page. Limiting the
number of results per page improves the endpoint''s performance. <br><br>Use the `page` parameter
to search the different pages of data. <br><br>Example: `10`'
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
pagination:
page: 1
per_page: 5
total_entries: 1
total_pages: 1
breadcrumbs:
- label: Name
signal_field_name: q_name
value: Copywriting Dublin
display_name: Copywriting Dublin
emailer_campaigns:
- id: 66e9e215ece19801b219997f
name: Target Copywriting Clients in Dublin
archived: false
created_at: '2024-09-17T20:09:57.837Z'
emailer_schedule_id: 6095a711bd01d100a506d52a
max_emails_per_day: null
user_id: 66302798d03b9601c7934ebf
same_account_reply_policy_cd: null
excluded_account_stage_ids:
- 6095a710bd01d100a506d4b8
- 6095a710bd01d100a506d4b9
- 6095a710bd01d100a506d4ba
- 6095a710bd01d100a506d4bb
excluded_contact_stage_ids:
- 6095a710bd01d100a506d4b5
- 6095a710bd01d100a506d4b4
- 6095a710bd01d100a506d4b0
- 6095a710bd01d100a506d4b1
contact_email_event_to_stage_mapping: {}
label_ids:
- 66e9e215ece19801b2199980
- 66e9e215ece19801b2199981
- 66e9e215ece19801b2199982
create_task_if_email_open: false
email_open_trigger_task_threshold: 3
mark_finished_if_click: false
active: false
days_to_wait_before_mark_as_response: 5
starred_by_user_ids:
- 66302798d03b9601c7934ebf
mark_finished_if_reply: true
mark_finished_if_interested: true
mark_paused_if_ooo: true
sequence_by_exact_daytime: null
last_used_at: null
sequence_ruleset_id: 6095a711bd01d100a506d4e0
folder_id: null
same_account_reply_delay_days: 30
is_performing_poorly: false
num_contacts_email_status_extrapolated: 0
remind_ab_test_results: false
ab_test_step_ids: []
prioritized_by_user: null
creation_type: new
num_steps: 3
unique_scheduled: 0
unique_delivered: 0
unique_bounced: 0
unique_opened: 0
unique_hard_bounced: 0
unique_spam_blocked: 0
unique_replied: 0
unique_demoed: 0
unique_clicked: 0
unique_unsubscribed: 0
bounce_rate: 0
hard_bounce_rate: 0
open_rate: 0
click_rate: 0
reply_rate: 0
spam_block_rate: 0
opt_out_rate: 0
demo_rate: 0
loaded_stats: true
cc_emails: ''
bcc_emails: ''
underperforming_touches_count: 0
sharing_permission:
visibility: everyone
access_type: can_view
object_type: EmailerCampaign
object_id: 66e9e215ece19801b219997f
is_owner: true
owner_id: 66302798d03b9601c7934ebf
sharing_accesses: []
num_fetch_result: null
schema:
type: object
properties:
pagination:
type: object
properties:
page:
type: integer
example: 1
default: 0
per_page:
type: integer
example: 5
default: 0
total_entries:
type: integer
example: 1
default: 0
total_pages:
type: integer
example: 1
default: 0
breadcrumbs:
type: array
items:
type: object
properties:
label:
type: string
example: Name
signal_field_name:
type: string
example: q_name
value:
type: string
example: Copywriting Dublin
display_name:
type: string
example: Copywriting Dublin
emailer_campaigns:
type: array
items:
type: object
properties:
id:
type: string
example: 66e9e215ece19801b219997f
name:
type: string
example: Target Copywriting Clients in Dublin
archived:
type: boolean
example: false
default: true
created_at:
type: string
example: '2024-09-17T20:09:57.837Z'
emailer_schedule_id:
type: string
example: 6095a711bd01d100a506d52a
max_emails_per_day: {}
user_id:
type: string
example: 66302798d03b9601c7934ebf
same_account_reply_policy_cd: {}
excluded_account_stage_ids:
type: array
items:
type: string
example: 6095a710bd01d100a506d4b8
excluded_contact_stage_ids:
type: array
items:
type: string
example: 6095a710bd01d100a506d4b5
contact_email_event_to_stage_mapping:
type: object
properties: {}
label_ids:
type: array
items:
type: string
example: 66e9e215ece19801b2199980
create_task_if_email_open:
type: boolean
example: false
default: true
email_open_trigger_task_threshold:
type: integer
example: 3
default: 0
mark_finished_if_click:
type: boolean
example: false
default: true
active:
type: boolean
example: false
default: true
days_to_wait_before_mark_as_response:
type: integer
example: 5
default: 0
starred_by_user_ids:
type: array
items:
type: string
example: 66302798d03b9601c7934ebf
mark_finished_if_reply:
type: boolean
example: true
default: true
mark_finished_if_interested:
type: boolean
example: true
default: true
mark_paused_if_ooo:
type: boolean
example: true
default: true
sequence_by_exact_daytime: {}
last_used_at: {}
sequence_ruleset_id:
type: string
example: 6095a711bd01d100a506d4e0
folder_id: {}
same_account_reply_delay_days:
type: integer
example: 30
default: 0
is_performing_poorly:
type: boolean
example: false
default: true
num_contacts_email_status_extrapolated:
type: integer
example: 0
default: 0
remind_ab_test_results:
type: boolean
example: false
default: true
ab_test_step_ids:
type: array
prioritized_by_user: {}
creation_type:
type: string
example: new
num_steps:
type: integer
example: 3
default: 0
unique_scheduled:
type: integer
example: 0
default: 0
unique_delivered:
type: integer
example: 0
default: 0
unique_bounced:
type: integer
example: 0
default: 0
unique_opened:
type: integer
example: 0
default: 0
unique_hard_bounced:
type: integer
example: 0
default: 0
unique_spam_blocked:
type: integer
example: 0
default: 0
unique_replied:
type: integer
example: 0
default: 0
unique_demoed:
type: integer
example: 0
default: 0
unique_clicked:
type: integer
example: 0
default: 0
unique_unsubscribed:
type: integer
example: 0
default: 0
bounce_rate:
type: integer
example: 0
default: 0
hard_bounce_rate:
type: integer
example: 0
default: 0
open_rate:
type: integer
example: 0
default: 0
click_rate:
type: integer
example: 0
default: 0
reply_rate:
type: integer
example: 0
default: 0
spam_block_rate:
type: integer
example: 0
default: 0
opt_out_rate:
type: integer
example: 0
default: 0
demo_rate:
type: integer
example: 0
default: 0
loaded_stats:
type: boolean
example: true
default: true
cc_emails:
type: string
example: ''
bcc_emails:
type: string
example: ''
underperforming_touches_count:
type: integer
example: 0
default: 0
sharing_permission:
type: object
description: Who can see and act on the sequence. This replaced the legacy `permissions`
field, which is no longer returned.
properties:
visibility:
type: string
description: '`everyone` if the sequence is shared with the whole team,
or `restricted` if it is limited to the owner and the users or teams listed
in `sharing_accesses`.'
enum:
- restricted
- everyone
example: everyone
access_type:
type: string
description: The level of access granted to the team when `visibility` is
`everyone`. `null` when `visibility` is `restricted`.
enum:
- can_view
- can_edit
- full_access
nullable: true
example: can_view
object_type:
type: string
example: EmailerCampaign
object_id:
type: string
description: The Apollo ID for the sequence.
example: 66e9e215ece19801b219997f
is_owner:
type: boolean
description: Whether the authenticated user owns the sequence.
example: true
owner_id:
type: string
description: The Apollo user ID for the sequence owner. Matches `user_id`.
example: 66302798d03b9601c7934ebf
sharing_accesses:
type: array
description: Sequences shared with specific users or teams, in addition
to whatever `visibility` grants.
items:
type: object
properties:
id:
type: string
shared_by:
type: string
description: The Apollo user ID for the user who granted the access.
user_or_team_id:
type: string
description: The Apollo ID for the user or team the sequence is shared
with.
user_or_team_type:
type: string
access_type:
type: string
enum:
- can_view
- can_edit
- full_access
object_id:
type: string
object_type:
type: string
is_default:
type: boolean
num_fetch_result: {}
'401':
description: '401'
content:
text/plain:
examples:
Check API key:
value: Invalid API key. See https://docs.apollo.io/reference/authentication for how
to authenticate.
'403':
description: '403'
content:
application/json:
examples:
Need master API key:
value: "{\n \"error\": \"This API key is not authorized to access api/v1/emailer_campaigns/search.\
\ Request an API key from your administrator that includes this endpoint in its configured\
\ scope.\",\n \"error_code\": \"API_INACCESSIBLE\"\n}"
Check Apollo pricing plan:
value: "{\n \"message\": \"This endpoint is only available to Apollo users on paid\
\ plans.\"\n}"
schema:
oneOf:
- title: Need master API key
type: object
properties:
error:
type: string
example: This API key is not authorized to access api/v1/emailer_campaigns/search.
Request an API key from your administrator that includes this endpoint in its
configured scope.
error_code:
type: string
example: API_INACCESSIBLE
- title: Check Apollo pricing plan
type: object
properties:
message:
type: string
example: This endpoint is only available to Apollo users on paid plans.
'429':
description: '429'
content:
application/json:
examples:
Too many requests:
value: "{\n \"message\": \"The maximum number of api calls allowed for api/v1/emailer_campaigns/search\
\ is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.\"\
\n}"
schema:
type: object
properties:
message:
type: string
example: The maximum number of api calls allowed for api/v1/emailer_campaigns/search
is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade.
deprecated: false
/emailer_campaigns/{sequence_id}/add_contact_ids:
post:
summary: Add Contacts to a Sequence
description: '## Endpoint essentials
**API key access:** `api/v1/emailer_campaigns/add_contact_ids` or `Master API key`
**OAuth scopes:** `emailer_cam
# --- truncated at 32 KB (205 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apollo-io/refs/heads/main/openapi/apollo-io-sequences-api-openapi.yml