v1

latestOpenAPI 3.1.02026-07-247601.0 MB

Tasks

Update 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 Update a Task endpoint to change the details of an existing task that belongs to your team's Apollo account. The fields you can update depend on the task's current status. For a task with a scheduled status, you can update any of the parameters listed below. For a task that's already completed or skipped, you can only update note, priority, priority_cd, and contact_id. To find task IDs, use the <a href="https://docs.apollo.io/reference/search-tasks">Search for Tasks endpoint</a> and identify the id value for the task you want to update.

patch/tasks/{id}

Path parameters

idstring required

The Apollo ID for the task. To find task IDs, call the <a href="https://docs.apollo.io/reference/search-tasks">Search for Tasks endpoint</a> and identify the id value for the task. Example: 67a1b2c3d4e5f60001234567

Request body

user_idstring

The ID for the task owner within your team's Apollo account. Only applies to tasks with a scheduled status. Example: 66302798d03b9601c7934ebf

creator_idstring

The ID of the user considered the creator of this task. Only applies to tasks with a scheduled status. If this task currently has a scheduled status and you omit this parameter, Apollo resets it to the user associated with your API key. Example: 60affe7d6e270a00f5db6fe4

contact_idstring

The Apollo ID for the contact you want on the receiving end of the action. Example: 66e34b81740c50074e3d1bd4

notestring

A description for the task. This should be a human-readable message. Example: This contact expressed interest in the Sequences feature specifically. Be prepared to discuss.

typestring

Only applies to tasks with a scheduled status. Set the task to 1 of the following task types: <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. </li> </ul>

prioritystring

Assign a priority to the task: high, medium, or low. If this task currently has a scheduled status and you omit this parameter, Apollo resets its priority to medium.

{"stackTrail":"paths:/tasks/{id}:patch:requestBody:content:application/json:schema:properties:priority_cd","oasType":"schema","type":"unknown","description":"Numeric-coded alternative to `priority`. Only applies to tasks that are not `scheduled` (already `completed` or `skipped`)."}

statusstring

Only applies to tasks with a scheduled status. To mark a task done, use the <a href="https://docs.apollo.io/reference/complete-a-task">Complete a Task</a> or <a href="https://docs.apollo.io/reference/skip-a-task">Skip a Task</a> endpoints instead of setting this directly. Example: scheduled

due_atstring date-time

Only applies to tasks with a scheduled status. The full date and time when the task is due, in <a href="https://www.rfc-editor.org/rfc/rfc3339#section-5.6" target="_blank">ISO 8601</a> format. Example: 2025-02-15T08:10:30Z

titlestring

Only applies to tasks with a scheduled status. A title for the task. Example: Follow up on demo request

call_scriptstring

Only applies to tasks with a scheduled status. A call script or talking points for a call type task.

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",
    "phone_call": {
      "id": "66e8cc45028aed019c25d720",
      "answered": true,
      "created_at": "2024-09-17T00:24:37.436Z",
      "to_number": "+1 (555) 555-****"
    },
    "account": {
      "id": "612f9d6cd26c290001d9bda0",
      "name": "Example Corp",
      "website_url": "http://www.example.com",
      "domain": "example.com",
      "linkedin_url": "https://www.linkedin.com/company/example-corp",
      "linkedin_uid": "18511550",
      "phone": "+1 (555) 555-0164",
      "phone_status": "no_status",
      "owner_id": "66302798d03b9601c7934ebf",
      "organization_id": "5fc93db64c38d300d6aa24e6",
      "industry": "information technology & services",
      "estimated_num_employees": 910,
      "created_at": "2021-09-01T15:34:04.371Z"
    },
    "contact": {
      "id": "66e34b81740c50074e3d1bd4",
      "first_name": "John",
      "last_name": "Smith",
      "name": "John Smith",
      "email": "john.smith@example.com",
      "title": "VP of Sales",
      "organization_name": "Example Corp",
      "account_id": "612f9d6cd26c290001d9bda0",
      "owner_id": "66302798d03b9601c7934ebf",
      "linkedin_url": "https://www.linkedin.com/in/john-smith-6b2d9f84",
      "created_at": "2024-09-12T18:45:21.456Z",
      "updated_at": "2024-09-17T00:24:37.436Z"
    },
    "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"
      }
    }
  }
}