Apollo.io Tasks API
Tasks against contacts, accounts and deals — create, search, update, complete, skip. 7 operation(s) from the published Apollo OpenAPI.
OpenAPI Specification
openapi: 3.1.0
info:
title: Apollo.io Tasks 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: Tasks
description: Create and search tasks for your go-to-market workflows.
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:
/tasks:
post:
summary: Create a Task
description: '## Endpoint essentials
**API key access:** `api/v1/tasks/create` or `Master API key`
**OAuth scopes:** `tasks_create`
**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/28705458602125-Tasks-Overview" target="_blank">Tasks</a>
let you track, prioritize, and help you complete actions required for your outbound sales motion.<br><br>Use
the Create a Task endpoint to create a single task in Apollo for you and your team. Tasks help
track the upcoming actions you need to take, such as emailing or calling a contact.<br><br>This
endpoint returns the created task object.<br><br>Apollo does not apply deduplication processes
when you create a new task via the API. If your entry has the same task owner, contact, and other
details as an existing task, Apollo will create a new task instead of updating the existing task.'
tags:
- Tasks
operationId: create-a-task
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_id
- contact_id
- type
- status
- due_at
properties:
user_id:
type: string
description: 'The ID for the task owner within your team''s Apollo account. This is
the user that will take action on the contacts. <br><br>Use the <a href="https://docs.apollo.io/reference/get-a-list-of-users"
target="_blank">Get a List of Users endpoint</a> to retrieve IDs for all of the users
within your Apollo account. <br><br>Example: `66302798d03b9601c7934ebf`'
contact_id:
type: string
description: 'The Apollo ID for the contact that you want to be on the receiving end
of the action. <br><br>To find contact IDs, call the <a href="https://docs.apollo.io/reference/search-for-contacts"
target="_blank">Search for Contacts endpoint</a> and identify the `id` value for the
contact. <br><br>Example: `66e34b81740c50074e3d1bd4`'
type:
type: string
description: 'Set the task to be 1 of the following task types. This enables the task
owner to know the type of action they need to take. <ul> <li> `call`: Call the contact.
</li> <li> `outreach_manual_email`: Email the contact. </li> <li> `linkedin_step_connect`:
Send a LinkedIn invitation to connect with the contact. </li> <li> `linkedin_step_message`:
Send a direct message to the contact''s LinkedIn profile. </li> <li> `linkedin_step_view_profile`:
View the contact''s LinkedIn profile. </li> <li> `linkedin_step_interact_post`: Interact
with the contact''s recent LinkedIn posts. </li> <li> `action_item`: Take generic
action for the contact. If you use this task type, Apollo recommends using the `note`
parameter too. </li> </ul>'
priority:
type: string
description: 'Assign a priority to the task you are creating: <ul> <li> `high` </li>
<li> `medium` </li> <li> `low` </li> </ul>'
default: medium
status:
type: string
description: 'The status of the task being created. For future-facing tasks, you should
use the `scheduled` status. <br><br>For tasks that are already completed, you can
use `completed` or `skipped`. <br><br>Example: `scheduled`'
due_at:
type: string
format: date-time
description: 'The full date and time when the task will be due. <br><br>Your entry should
adhere to the <a href="https://www.rfc-editor.org/rfc/rfc3339#section-5.6" target="_blank">ISO
8601 date-time format</a>. Apollo uses Greenwich Mean Time (GMT) by default. If you
do not account for time zone differences, you could add a task due date that falls
on a different day than you intended. <br><br>The value you enter can either adhere
to GMT, or you can adjust the time manually by specifying in hours and minutes how
much you want to offset GMT.<br><br>Example: `2025-02-15T08:10:30Z`; `2025-03-25T10:15:30+05:00`'
title:
type: string
description: 'A title for the task. If omitted, Apollo will display an auto-generated
title based on the task type and contact name. <br><br>Example: `Follow up on demo
request`'
note:
type: string
description: 'Add a description for the task. This should be a human-readable message.
<br><br>This parameter is not required, but it is recommended as it provides the task
owner with more context on the action they need to take. <br><br>Example: `This contact
expressed interest in the Sequences feature specifically. Be prepared to discuss.`'
examples:
Create a call task:
value:
user_id: 66302798d03b9601c7934ebf
contact_id: 66e34b81740c50074e3d1bd4
type: call
priority: high
status: scheduled
due_at: '2025-02-15T10:00:00Z'
title: Follow-up call
note: Discuss product demo results and next steps.
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
task:
type: object
properties:
emailer_campaign_id: {}
id:
type: string
example: 66e8cc45028aed019c25d724
user_id:
type: string
example: 66a3d80d4238fe02d2baaaaf
created_at:
type: string
example: '2024-09-17T00:24:37.436Z'
completed_at: {}
note: {}
skipped_at: {}
due_at:
type: string
example: '2024-09-21T00:00:00.000+00:00'
type:
type: string
example: action_item
priority:
type: string
example: medium
status:
type: string
example: scheduled
answered: {}
contact_id: {}
person_id: {}
account_id: {}
organization_id: {}
persona_ids:
type: array
subject: {}
created_from: {}
salesforce_type: {}
playbook_step_ids:
type: array
playbook_id: {}
needs_playbook_autoprospecting: {}
starred_by_user_ids:
type: array
salesforce_id: {}
hubspot_id: {}
opportunity_id:
type: string
example: 66e8c4567f32a501b2605004
title:
type: string
example: Reminder - Schedule Demo Call
rule_config_id: {}
creator_id:
type: string
example: 60affe7d6e270a00f5db6fe4
opportunity:
type: object
properties:
id:
type: string
example: 66e8c4567f32a501b2605004
team_id:
type: string
example: 6095a710bd01d100a506d4ac
owner_id:
type: string
example: 66a3d80d4238fe02d2baaaaf
salesforce_owner_id: {}
amount:
type: integer
example: 3000
default: 0
closed_date:
type: string
example: '2024-11-03T00:00:00.000+00:00'
account_id:
type: string
example: 612f9d6cd26c290001d9bda0
description: {}
is_closed:
type: boolean
example: false
default: true
is_won: {}
name:
type: string
example: 5 Seats of Acme | $2K | Google
stage_name: {}
opportunity_stage_id:
type: string
example: 66e4b9b5e5aa6b0e57f078a1
source:
type: string
example: ui_form
salesforce_id: {}
created_at:
type: string
example: '2024-09-16T23:50:46.311Z'
actual_close_date: {}
next_step:
type: string
example: Schedule Demo
next_step_date: {}
closed_lost_reason: {}
closed_won_reason: {}
forecast_category:
type: string
example: omitted
deal_probability:
type: integer
example: 50
default: 0
created_by_id:
type: string
example: 60affe7d6e270a00f5db6fe4
current_solutions: {}
deal_source: {}
manually_updated_probability: {}
manually_updated_forecast: {}
crm_id: {}
crm_record_url: {}
crm_owner_id: {}
probability: {}
opportunity_pipeline_id:
type: string
example: 66e4b85ce5aa6b03f3f08b6e
stage_updated_at:
type: string
example: '2024-09-17T16:44:07.133+00:00'
next_step_last_updated_at:
type: string
example: '2024-09-17T00:03:13.420+00:00'
exchange_rate_code:
type: string
example: USD
exchange_rate_value:
type: integer
example: 1
default: 0
amount_in_team_currency:
type: integer
example: 3000
default: 0
forecasted_revenue:
type: integer
example: 1500
default: 0
last_activity_date:
type: string
example: '2024-09-17T16:44:07.134Z'
existence_level:
type: string
example: full
typed_custom_fields:
type: object
properties:
6095a711bd01d100a506d4da:
type: array
items:
type: string
example: 6153414ac0559d00016ce5eb
6095a711bd01d100a506d4dc:
type: array
items:
type: string
example: 6153414ac0559d00016ce5f3
66e4ba346fe95a073461e00e:
type: array
items:
type: string
example: 66e4ba346fe95a073461e00c
opportunity_rule_config_statuses:
type: array
opportunity_contact_roles:
type: array
items:
type: object
properties:
id:
type: string
example: 66e8c9d7320e8a01b44f1e82
contact_id:
type: string
example: 665c3338da53130001243ac4
is_primary:
type: boolean
example: true
default: true
created_at:
type: string
example: '2024-09-17T00:14:15.655Z'
updated_at:
type: string
example: '2024-09-17T00:14:15.655Z'
role:
type: array
items:
type: object
properties:
opportunity_contact_role_type_id:
type: string
example: 64288550ffb0470001cbf2b0
crm_role_id: {}
is_primary:
type: boolean
example: true
default: true
crm_id: {}
currency:
type: object
properties:
name:
type: string
example: US Dollar
iso_code:
type: string
example: USD
symbol:
type: string
example: $
account:
type: object
properties:
id:
type: string
example: 612f9d6cd26c290001d9bda0
domain:
type: string
example: google.com
name:
type: string
example: Google
team_id:
type: string
example: 6095a710bd01d100a506d4ac
organization_id:
type: string
example: 5fc93db64c38d300d6aa24e6
account_stage_id:
type: string
example: 6095a710bd01d100a506d4b9
source:
type: string
example: csv_import
original_source:
type: string
example: csv_import
creator_id: {}
owner_id: {}
created_at:
type: string
example: '2021-09-01T15:34:04.371Z'
phone: {}
phone_status:
type: string
example: no_status
hubspot_id: {}
salesforce_id: {}
crm_owner_id: {}
parent_account_id: {}
linkedin_url: {}
account_playbook_statuses:
type: array
account_rule_config_statuses:
type: array
items:
type: object
properties:
_id:
type: string
example: 6466e8047759270001e53509
created_at: {}
rule_action_config_id:
type: string
example: 64650edd434f8f00a3b13938
rule_config_id:
type: string
example: 64650edd434f8f00a3b13939
status_cd:
type: string
example: completed
updated_at: {}
id:
type: string
example: 6466e8047759270001e53509
key:
type: string
example: 6466e8047759270001e53509
existence_level:
type: string
example: full
label_ids:
type: array
items:
type: string
example: 6466e8261e13be000133f25d
typed_custom_fields:
type: object
properties: {}
custom_field_errors: {}
modality:
type: string
example: account
source_display_name:
type: string
example: Uploaded from CSV
crm_record_url: {}
contact_emailer_campaign_ids:
type: array
contact_campaign_status_tally:
type: object
properties: {}
num_contacts:
type: integer
example: 0
default: 0
last_activity_date: {}
examples:
Result:
value:
task:
emailer_campaign_id: null
id: 67a1b2c3d4e5f60001234567
user_id: 66302798d03b9601c7934ebf
created_at: '2025-02-03T15:30:00.000Z'
completed_at: null
note: Discuss product demo results and next steps.
skipped_at: null
due_at: '2025-02-15T10:00:00.000+00:00'
type: call
priority: high
status: scheduled
answered: null
contact_id: 66e34b81740c50074e3d1bd4
person_id: 66e34b81740c50074e3d1bd5
account_id: 612f9d6cd26c290001d9bda0
organization_id: 5fc93db64c38d300d6aa24e6
persona_ids: []
subject: null
created_from: api
salesforce_type: null
playbook_step_ids: []
playbook_id: null
needs_playbook_autoprospecting: null
starred_by_user_ids: []
salesforce_id: null
hubspot_id: null
opportunity_id: null
title: Follow-up call with John Smith
rule_config_id: null
creator_id: 66302798d03b9601c7934ebf
contact:
id: 66e34b81740c50074e3d1bd4
first_name: John
last_name: Smith
name: John Smith
linkedin_url: https://www.linkedin.com/in/john-smith-6b2d9f84
title: VP of Sales
email: john.smith@example.com
organization_name: Example Corp
photo_url: null
twitter_url: null
github_url: null
facebook_url: null
account_id: 612f9d6cd26c290001d9bda0
owner_id: 66302798d03b9601c7934ebf
created_at: '2024-09-12T18:45:21.456Z'
present_raw_address: San Francisco, CA
city: San Francisco
state: California
country: United States
email_status: verified
account:
id: 612f9d6cd26c290001d9bda0
name: Example Corp
domain: example.com
team_id: 6095a710bd01d100a506d4ac
organization_id: 5fc93db64c38d300d6aa24e6
owner_id: 66302798d03b9601c7934ebf
created_at: '2021-09-01T15:34:04.371Z'
phone: +1 (555) 555-0164
phone_status: no_status
linkedin_url: https://www.linkedin.com/company/example-corp
'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/tasks. 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/tasks. Request an API key
from your administrator that includes this endpoint in its configured scope.
error_code:
type: string
example: API_INACCESSIBLE
'422':
description: '422'
content:
application/json:
examples:
Missing required fields:
value: "{\n \"error\": \"type and user can not be blank\"\n}"
schema:
type: object
properties:
error:
type: string
'429':
description: '429'
content:
application/json:
examples:
Too many requests:
value: "{\n \"message\": \"The maximum number of api calls allowed for api/v1/tasks\
\ 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
deprecated: false
/tasks/bulk_create:
post:
summary: Bulk Create Tasks
description: '## Endpoint essentials
**API key access:** `api/v1/tasks/bulk_create` or `Master API key`
**OAuth scopes:** `tasks_create`
**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).
**Authentication note:** Shares scope with `tasks/create`.
<a href="https://knowledge.apollo.io/hc/en-us/articles/28705458602125-Tasks-Overview" target="_blank">Tasks</a>
let you track, prioritize, and help you complete actions required for your outbound sales motion.<br><br>Use
the Bulk Create Tasks endpoint to create multiple tasks in a single API request. A separate task
will be created for each contact provided. <br><br>This endpoint returns a `success` boolean and
a `tasks` array containing the created tasks. <br><br>Apollo doesn''t apply deduplication processes
when you create a new task via the API. If your entry has the same task owner, contact, and other
details as an existing task, Apollo creates a new task instead of updating the existing task.
<br><br>For creating a single task, use the <a href="https://docs.apollo.io/reference/create-a-task">Create
a Task endpoint</a> instead.'
tags:
- Tasks
operationId: bulk-create-tasks
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_id
- contact_ids
- type
- status
- due_at
properties:
user_id:
type: string
description: 'The ID for the task owner within your team''s Apollo account. This is
the user that will take action on the contacts. <br><br>Use the <a href="https://docs.apollo.io/reference/get-a-list-of-users"
target="_blank">Get a List of Users endpoint</a> to retrieve IDs for all of the users
within your Apollo account. <br><br>Example: `66302798d03b9601c7934ebf`'
contact_ids:
type: array
items:
type: string
description: 'The Apollo IDs for the contacts that you want to be on the receiving end
of the action. <br><br>If you add multiple contact IDs, individual tasks will be created
for each of the contacts using the same task type, due date, and other details. <br><br>To
find contact IDs, call the <a href="https://docs.apollo.io/reference/search-for-contacts"
target="_blank">Search for Contacts endpoint</a> and identify the `id` value for the
contact. <br><br>Example: `66e34b81740c50074e3d1bd4`'
type:
type: string
description: 'Set the task to be 1 of the following task types. This enables the task
owner to know the type of action they need to take. <ul> <li> `call`: Call the contacts.
</li> <li> `outreach_manual_email`: Email the contacts. </li> <li> `linkedin_step_connect`:
Send a LinkedIn invitation to connect with the contacts. </li> <li> `linkedin_step_message`:
Send a direct message to the contacts'' LinkedIn profiles. </li> <li> `linkedin_step_view_profile`:
View the contacts'' LinkedIn profiles. </li> <li> `linkedin_step_interact_post`: Interact
with the contacts'' recent LinkedIn posts. </li> <li> `action_item`: Take generic
action for the contacts. If you use this task type, Apollo recommends using the `note`
# --- truncated at 32 KB (232 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apollo-io/refs/heads/main/openapi/apollo-io-tasks-api-openapi.yml