v1

latestOpenAPI 3.1.02026-07-247601.0 MB

Tasks

Create a Task

This endpoint doesn't consume Apollo credits. Learn more about API pricing and credits.

<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. 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. This endpoint returns the created task object. 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. This endpoint requires a master API key. If you call the endpoint without a master key, you receive a 403 response. Check out <a href="https://docs.apollo.io/docs/create-api-key">Create an API Key</a> to learn how to create a master key.

post/tasks

Request body

user_idstring required

The ID for the task owner within your team's Apollo account. This is the user that will take action on the contacts. 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. Example: 66302798d03b9601c7934ebf

contact_idstring required

The Apollo ID for the contact that you want to be on the receiving end of the action. 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. Example: 66e34b81740c50074e3d1bd4

typestring required

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>

prioritystring

Assign a priority to the task you are creating: <ul> <li> high </li> <li> medium </li> <li> low </li> </ul>

statusstring required

The status of the task being created. For future-facing tasks, you should use the scheduled status. For tasks that are already completed, you can use completed or skipped. Example: scheduled

due_atstring date-time required

The full date and time when the task will be due. 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. 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. Example: 2025-02-15T08:10:30Z; 2025-03-25T10:15:30+05:00

titlestring

A title for the task. If omitted, Apollo will display an auto-generated title based on the task type and contact name. Example: Follow up on demo request

notestring

Add a description for the task. This should be a human-readable message. 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. Example: This contact expressed interest in the Sequences feature specifically. Be prepared to discuss.

Response

200

Example response

{
  "task": {
    "id": "66e8cc45028aed019c25d724",
    "user_id": "66a3d80d4238fe02d2baaaaf",
    "created_at": "2024-09-17T00:24:37.436Z",
    "due_at": "2024-09-21T00:00:00.000+00:00",
    "type": "action_item",
    "priority": "medium",
    "status": "scheduled",
    "opportunity_id": "66e8c4567f32a501b2605004",
    "title": "Reminder - Schedule Demo Call",
    "creator_id": "60affe7d6e270a00f5db6fe4",
    "opportunity": {
      "id": "66e8c4567f32a501b2605004",
      "team_id": "6095a710bd01d100a506d4ac",
      "owner_id": "66a3d80d4238fe02d2baaaaf",
      "amount": 3000,
      "closed_date": "2024-11-03T00:00:00.000+00:00",
      "account_id": "612f9d6cd26c290001d9bda0",
      "name": "5 Seats of Acme | $2K | Google",
      "opportunity_stage_id": "66e4b9b5e5aa6b0e57f078a1",
      "source": "ui_form",
      "created_at": "2024-09-16T23:50:46.311Z",
      "next_step": "Schedule Demo",
      "forecast_category": "omitted",
      "deal_probability": 50,
      "created_by_id": "60affe7d6e270a00f5db6fe4",
      "opportunity_pipeline_id": "66e4b85ce5aa6b03f3f08b6e",
      "stage_updated_at": "2024-09-17T16:44:07.133+00:00",
      "next_step_last_updated_at": "2024-09-17T00:03:13.420+00:00",
      "exchange_rate_code": "USD",
      "exchange_rate_value": 1,
      "amount_in_team_currency": 3000,
      "forecasted_revenue": 1500,
      "last_activity_date": "2024-09-17T16:44:07.134Z",
      "existence_level": "full",
      "typed_custom_fields": {
        "6095a711bd01d100a506d4da": [
          "6153414ac0559d00016ce5eb"
        ],
        "6095a711bd01d100a506d4dc": [
          "6153414ac0559d00016ce5f3"
        ],
        "66e4ba346fe95a073461e00e": [
          "66e4ba346fe95a073461e00c"
        ]
      },
      "opportunity_contact_roles": [
        {
          "id": "66e8c9d7320e8a01b44f1e82",
          "contact_id": "665c3338da53130001243ac4",
          "is_primary": true,
          "created_at": "2024-09-17T00:14:15.655Z",
          "updated_at": "2024-09-17T00:14:15.655Z",
          "role": [
            {
              "opportunity_contact_role_type_id": "64288550ffb0470001cbf2b0",
              "is_primary": true
            }
          ]
        }
      ],
      "currency": {
        "name": "US Dollar",
        "iso_code": "USD",
        "symbol": "$"
      },
      "account": {
        "id": "612f9d6cd26c290001d9bda0",
        "domain": "google.com",
        "name": "Google",
        "team_id": "6095a710bd01d100a506d4ac",
        "organization_id": "5fc93db64c38d300d6aa24e6",
        "account_stage_id": "6095a710bd01d100a506d4b9",
        "source": "csv_import",
        "original_source": "csv_import",
        "created_at": "2021-09-01T15:34:04.371Z",
        "phone_status": "no_status",
        "account_rule_config_statuses": [
          {
            "_id": "6466e8047759270001e53509",
            "rule_action_config_id": "64650edd434f8f00a3b13938",
            "rule_config_id": "64650edd434f8f00a3b13939",
            "status_cd": "completed",
            "id": "6466e8047759270001e53509",
            "key": "6466e8047759270001e53509"
          }
        ],
        "existence_level": "full",
        "label_ids": [
          "6466e8261e13be000133f25d"
        ],
        "modality": "account",
        "source_display_name": "Uploaded from CSV"
      }
    }
  }
}