Apollo API Tasks

openapi: 3.1.0
info:
  title: Apollo API — Tasks
  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/
  version: '1.0'
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` parameter too. </li> </ul>'
                priority:
                  type: string
                  description: 'Assign a priority to the task you are creating: <ul> <li> `high` </li> <li> `medium` </li>
                    <

# --- truncated at 32 KB (231 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apollo-api-documentation/refs/heads/main/openapi/apollo-api-documentation-tasks-api-openapi.yml