---
updatedAt: 2026-07-28T19:59:56.000Z
---

Fetch the complete documentation index at: https://docs.apollo.io/llms.txt. Use this file to discover all available pages before exploring further.

# Bulk Update Contacts

 

<table>
  <thead>
    <tr style="background-color :#FEFFD9; color:#000000">
      <th colspan="2" align="left">Endpoint essentials</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>API key access</strong></td>
      <td><code>api/v1/contacts/bulk_update</code> or <code>Master API key</code></td>
    </tr>
    <tr>
      <td><strong>OAuth scopes</strong></td>
      <td><code>contacts_bulk_update</code></td>
    </tr>
    <tr>
      <td><strong>Credit usage</strong></td>
      <td><code>0 credits</code><br><a href="https://docs.apollo.io/docs/api-pricing">Learn more about API pricing and credits</a>.</td>
    </tr>
  </tbody>
</table>

<a href="https://knowledge.apollo.io/hc/en-us/articles/5995459280525-View-and-Edit-Contacts" target="_blank">Contacts</a> are people saved in Apollo.<br><br>Use the Bulk Update Contacts endpoint to update multiple contacts in your team's Apollo account simultaneously.<br><br>This endpoint allows you to update common fields across multiple contacts efficiently, such as contact stages, owners, custom fields, and other contact attributes.<br><br>You can update up to 1000 contacts per request; requests with more than 1000 contacts are rejected with a <code>422</code> error. Requests of 100 or fewer contacts are processed synchronously and return the updated contacts immediately. Requests of 101 to 1000 contacts are processed asynchronously. You can also force asynchronous processing at any batch size by setting the <code>async</code> parameter to <code>true</code>.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "apollo-rest-api",
    "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.\n\n## Base URL\n\nAll API requests are made to `https://api.apollo.io/api/v1`.\n\n## Authentication\n\n- **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).\n- **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).\n\n## Rate limits & credits\n\nRate 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).\n\nNew 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": "Contacts",
      "description": "Create, update, and search the people your team saves in Apollo."
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "[Recommended] API key, passed in the `x-api-key` request header.\nSee [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.\nSee the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners)."
      }
    }
  },
  "security": [
    {
      "apiKey": []
    },
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/contacts/bulk_update": {
      "post": {
        "summary": "Bulk Update Contacts",
        "description": "## Endpoint essentials\n\n**API key access:** `api/v1/contacts/bulk_update` or `Master API key`\n\n**OAuth scopes:** `contacts_bulk_update`\n\n**Credit usage:** `0 credits` — [Learn more about API pricing and credits](https://docs.apollo.io/docs/api-pricing).\n\n<a href=\"https://knowledge.apollo.io/hc/en-us/articles/5995459280525-View-and-Edit-Contacts\" target=\"_blank\">Contacts</a> are people saved in Apollo.<br><br>Use the Bulk Update Contacts endpoint to update multiple contacts in your team's Apollo account simultaneously.<br><br>This endpoint allows you to update common fields across multiple contacts efficiently, such as contact stages, owners, custom fields, and other contact attributes.<br><br>You can update up to 1000 contacts per request; requests with more than 1000 contacts are rejected with a <code>422</code> error. Requests of 100 or fewer contacts are processed synchronously and return the updated contacts immediately. Requests of 101 to 1000 contacts are processed asynchronously. You can also force asynchronous processing at any batch size by setting the <code>async</code> parameter to <code>true</code>.",
        "tags": [
          "Contacts"
        ],
        "operationId": "bulk-update-contacts",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contact_ids": {
                    "type": "array",
                    "description": "Array of contact IDs to update with the same values. Use this for applying the same updates to multiple contacts.",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "66e34b81740c50074e3d1bd4",
                      "66e370fbf5f5c003f0e1d0cf"
                    ]
                  },
                  "contact_attributes": {
                    "type": "array",
                    "description": "Array of contact objects with individual updates. Use this for applying different updates to each contact.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The contact ID to update",
                          "example": "66e34b81740c50074e3d1bd4"
                        },
                        "first_name": {
                          "type": "string",
                          "description": "The contact's first name",
                          "example": "John"
                        },
                        "last_name": {
                          "type": "string",
                          "description": "The contact's last name",
                          "example": "Doe"
                        },
                        "email": {
                          "type": "string",
                          "description": "The contact's email address",
                          "example": "john.doe@example.com"
                        },
                        "title": {
                          "type": "string",
                          "description": "The contact's job title",
                          "example": "Senior Manager"
                        },
                        "organization_name": {
                          "type": "string",
                          "description": "The contact's organization name",
                          "example": "Example Corp"
                        },
                        "owner_id": {
                          "type": "string",
                          "description": "The Apollo user ID to assign as owner",
                          "example": "66302798d03b9601c7934ebf"
                        },
                        "account_id": {
                          "type": "string",
                          "description": "The Apollo account ID to associate with the contact",
                          "example": "63f53afe4ceeca00016bdd2f"
                        },
                        "present_raw_address": {
                          "type": "string",
                          "description": "The contact's location",
                          "example": "San Francisco, CA"
                        },
                        "linkedin_url": {
                          "type": "string",
                          "description": "The contact's LinkedIn profile URL",
                          "example": "https://www.linkedin.com/in/john-doe-3f9a7c21"
                        },
                        "typed_custom_fields": {
                          "type": "object",
                          "description": "Custom field values as key-value pairs",
                          "additionalProperties": {
                            "type": "string"
                          },
                          "example": {
                            "60c39ed82bd02f01154c470a": "2025-08-07"
                          }
                        }
                      },
                      "required": [
                        "id"
                      ]
                    }
                  },
                  "owner_id": {
                    "type": "string",
                    "description": "When using contact_ids, apply this owner to all contacts",
                    "example": "66302798d03b9601c7934ebf"
                  },
                  "email": {
                    "type": "string",
                    "description": "When using contact_ids, apply this email to all contacts",
                    "example": "updated@example.com"
                  },
                  "organization_name": {
                    "type": "string",
                    "description": "When using contact_ids, apply this organization name to all contacts",
                    "example": "Updated Corp"
                  },
                  "title": {
                    "type": "string",
                    "description": "When using contact_ids, apply this title to all contacts",
                    "example": "Updated Title"
                  },
                  "first_name": {
                    "type": "string",
                    "description": "When using contact_ids, apply this first name to all contacts",
                    "example": "Updated"
                  },
                  "last_name": {
                    "type": "string",
                    "description": "When using contact_ids, apply this last name to all contacts",
                    "example": "Name"
                  },
                  "account_id": {
                    "type": "string",
                    "description": "When using contact_ids, apply this account ID to all contacts",
                    "example": "63f53afe4ceeca00016bdd2f"
                  },
                  "present_raw_address": {
                    "type": "string",
                    "description": "When using contact_ids, apply this address to all contacts",
                    "example": "New York, NY"
                  },
                  "linkedin_url": {
                    "type": "string",
                    "description": "When using contact_ids, apply this LinkedIn URL to all contacts",
                    "example": "https://www.linkedin.com/in/updated"
                  },
                  "typed_custom_fields": {
                    "type": "object",
                    "description": "When using contact_ids, apply these custom fields to all contacts",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "example": {
                      "60c39ed82bd02f01154c470a": "2025-08-07"
                    }
                  },
                  "async": {
                    "type": "boolean",
                    "description": "Force asynchronous processing. Automatically enabled for >100 contacts.",
                    "example": false
                  },
                  "visible_entity_ids": {
                    "type": "array",
                    "description": "Specific contact IDs to return in the response (for performance)",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "66e34b81740c50074e3d1bd4"
                    ]
                  }
                },
                "anyOf": [
                  {
                    "required": [
                      "contact_ids"
                    ]
                  },
                  {
                    "required": [
                      "contact_attributes"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "summary": "Synchronous response for ≤100 contacts",
                    "value": "{\n  \"contacts\": [\n    {\n      \"id\": \"66e34b81740c50074e3d1bd4\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"email\": \"john.doe@example.com\",\n      \"title\": \"Senior Manager\",\n      \"organization_name\": \"Example Corp\",\n      \"owner_id\": \"66302798d03b9601c7934ebf\",\n      \"account_id\": \"63f53afe4ceeca00016bdd2f\",\n      \"present_raw_address\": \"San Francisco, CA\",\n      \"linkedin_url\": \"https://www.linkedin.com/in/john-doe-3f9a7c21\",\n      \"updated_at\": \"2024-09-12T10:30:00.000Z\"\n    }\n  ]\n}"
                  },
                  "Asynchronous-Update": {
                    "summary": "Asynchronous response for >100 contacts or async=true",
                    "value": "{\n  \"entity_progress_job\": {\n    \"id\": \"66e34b81740c50074e3d1234\",\n    \"job_type\": \"contact_bulk_update\",\n    \"status\": \"pending\",\n    \"entity_ids\": [\"66e34b81740c50074e3d1bd4\", \"66e370fbf5f5c003f0e1d0cf\"],\n    \"created_at\": \"2024-09-12T10:30:00.000Z\",\n    \"updated_at\": \"2024-09-12T10:30:00.000Z\"\n  }\n}"
                  }
                },
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "contacts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "example": "66e34b81740c50074e3d1bd4"
                              },
                              "first_name": {
                                "type": "string",
                                "example": "John"
                              },
                              "last_name": {
                                "type": "string",
                                "example": "Doe"
                              },
                              "email": {
                                "type": "string",
                                "example": "john.doe@example.com"
                              },
                              "title": {
                                "type": "string",
                                "example": "Senior Manager"
                              },
                              "organization_name": {
                                "type": "string",
                                "example": "Example Corp"
                              },
                              "owner_id": {
                                "type": "string",
                                "example": "66302798d03b9601c7934ebf"
                              },
                              "account_id": {
                                "type": "string",
                                "example": "63f53afe4ceeca00016bdd2f"
                              },
                              "present_raw_address": {
                                "type": "string",
                                "example": "San Francisco, CA"
                              },
                              "linkedin_url": {
                                "type": "string",
                                "example": "https://www.linkedin.com/in/john-doe-3f9a7c21"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2024-09-12T10:30:00.000Z"
                              }
                            }
                          }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "entity_progress_job": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "example": "66e34b81740c50074e3d1234"
                            },
                            "job_type": {
                              "type": "string",
                              "example": "contact_bulk_update"
                            },
                            "status": {
                              "type": "string",
                              "example": "pending"
                            },
                            "entity_ids": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "example": [
                                "66e34b81740c50074e3d1bd4",
                                "66e370fbf5f5c003f0e1d0cf"
                              ]
                            },
                            "created_at": {
                              "type": "string",
                              "format": "date-time",
                              "example": "2024-09-12T10:30:00.000Z"
                            },
                            "updated_at": {
                              "type": "string",
                              "format": "date-time",
                              "example": "2024-09-12T10:30:00.000Z"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "401",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": "Invalid API key. See https://docs.apollo.io/reference/authentication for how to authenticate."
                  }
                }
              }
            }
          },
          "422": {
            "description": "422",
            "content": {
              "application/json": {
                "examples": {
                  "Missing Parameters": {
                    "summary": "Missing required parameters",
                    "value": "{\n  \"error\": \"Please provide either contact_ids or contact_attributes\"\n}"
                  },
                  "Too Many Contacts": {
                    "summary": "Exceeds maximum limit",
                    "value": "{\n  \"error\": \"Please limit your array to fewer than 1000.\"\n}"
                  },
                  "Update Error": {
                    "summary": "Validation or update error",
                    "value": "{\n  \"error\": \"Validation failed\",\n  \"error_details\": {\n    \"contact_id\": \"66e34b81740c50074e3d1bd4\",\n    \"field\": \"email\",\n    \"message\": \"Invalid email format\"\n  }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Please provide either contact_ids or contact_attributes"
                    },
                    "error_details": {
                      "type": "object",
                      "properties": {
                        "contact_id": {
                          "type": "string",
                          "example": "66e34b81740c50074e3d1bd4"
                        },
                        "field": {
                          "type": "string",
                          "example": "email"
                        },
                        "message": {
                          "type": "string",
                          "example": "Invalid email format"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "429",
            "content": {
              "application/json": {
                "examples": {
                  "Too many requests": {
                    "value": "{\n    \"message\": \"The maximum number of api calls allowed for api/v1/contacts/bulk_update 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/contacts/bulk_update is 600 times per hour. Please upgrade your plan from https://app.apollo.io/#/settings/plans/upgrade."
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "key": "Cache-Control",
        "value": "no-cache"
      },
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```