--- title: "Bulk People Enrichment" method: POST path: "/people/bulk_match" tags: ["Enrichment"] --- # Bulk People Enrichment `POST /people/bulk_match` This endpoint consumes **1-9 Apollo credits per person** when credit-consuming data is found: **1 credit** for demographics/email, plus **8 credits** if a mobile phone is returned. You can enrich up to 10 people per request. If Apollo doesn't return credit-consuming data for a person, that person consumes **0 credits**. If you use waterfall enrichment for phone or email, credit usage depends on the returned data and the vendors included in your [waterfall enrichment configuration](https://knowledge.apollo.io/hc/en-us/articles/34071121664781-Use-Waterfall-Enrichment). Learn more about [API pricing and credits](https://docs.apollo.io/docs/api-pricing). Enrichment is when you refresh existing records so your prospecting data is up-to-date.

Use the Bulk People Enrichment endpoint to enrich data for up to ten people with a single API call. To enrich data for a single person, use the People Enrichment endpoint instead.

Apollo relies on the information you pass via the endpoint's parameters to identify the correct people to enrich. When you provide more information, Apollo is more likely to find matches within its database. If you only provide general information, such as a name without a domain or email address, you may receive a `200` response, but the response indicates that no records have been enriched. The details for each person should be passed as an object in the `details[]` array.

By default, this endpoint doesn't return personal emails or phone numbers. Use the `reveal_personal_emails` parameter to retrieve personal emails and `reveal_phone_number` to retrieve phone numbers. If you set either of these parameters to `true`, Apollo attempts to provide emails or phone numbers for all matches.

When you use `reveal_phone_number`, a valid `webhook_url` is required so Apollo can deliver the completed phone enrichment results. Apollo returns the main enrichment response synchronously, then sends the requested phone numbers to the webhook asynchronously. [See webhook details](#webhook-details).

You can also use the `run_waterfall_email` and `run_waterfall_phone` parameters to run waterfall enrichment via this endpoint. [Waterfall enrichment](https://knowledge.apollo.io/hc/en-us/articles/34071089002509-Waterfall-Enrichment-Overview) gives you broader data coverage by checking connected third-party data sources for contact emails and phone numbers.

When you call this endpoint and include at least one waterfall parameter, a valid `webhook_url` is required so Apollo can deliver the completed waterfall enrichment results. Apollo returns an immediate synchronous response with demographic and firmographic data, along with a waterfall enrichment request status. Apollo then delivers enriched emails or phone numbers asynchronously to the configured webhook.

### Webhook Details * When using native phone enrichment, the webhook response follows: [Native webhook response details](https://docs.apollo.io/docs/retrieve-mobile-phone-numbers-for-contacts#webhook-response-details). * When using waterfall enrichment, the webhook response follows: [Waterfall webhook response details](https://docs.apollo.io/docs/enrich-phone-and-email-using-data-waterfall#response-details). * You can poll webhook results with the [Poll Webhook Result](https://docs.apollo.io/docs/poll-webhook-result) endpoint by passing request_id. ### Webhook Requirements * **HTTPS Required:** Your endpoint must be publicly accessible over HTTPS. * **Rate Limiting:** Ensure your webhook endpoint can handle the volume of webhook traffic sent by Apollo. * **Idempotency:** Apollo may retry webhook calls. Your endpoint should be idempotent to handle duplicate payloads safely. ## Query parameters - `run_waterfall_email` boolean - `run_waterfall_phone` boolean - `reveal_personal_emails` boolean - `reveal_phone_number` boolean - `webhook_url` string ## Request body - object - `details` object[], required — Provide info for each person you want to enrich as an object within this array. Add up to 10 people. - `first_name` string — The first name of the person. This is typically used in combination with the `last_name` parameter.

Example: `tim` - `last_name` string — The last name of the person. This is typically used in combination with the `first_name` parameter.

Example: `zheng` - `name` string — The full name of the person. This will typically be a first name and last name separated by a space. If you use this parameter, you do not need to use the `first_name` and `last_name` parameters.

Example: `tim zheng` - `email` string — The email address of the person.

Example: `example@email.com` - `hashed_email` string — The hashed email of the person. The email should adhere to either the MD5 or SHA-256 hash format.

Example: `8d935115b9ff4489f2d1f9249503cadf` (MD5) or `97817c0c49994eb500ad0a5e7e2d8aed51977b26424d508f66e4e8887746a152` (SHA-256) - `organization_name` string — The name of the person's employer. This can be the current employer or a previous employer.

Example: `apollo` - `domain` string — The domain name for the person's employer. This can be the current employer or a previous employer. Do not include `www.`, the `@` symbol, or similar.

Example: `apollo.io` or `microsoft.com` - `id` string — The Apollo ID for the person. Each person in the Apollo database is assigned a unique ID.

To find IDs, call the People API Search endpoint and identify the values for `person_id`.

Example: `587cf802f65125cad923a266` - `linkedin_url` string — The URL for the person's LinkedIn profile.

Example: `http://www.linkedin.com/in/tim-zheng-677ba010` ## Response `200` 200 - object - `request_id` integer — The request ID for the enrichment request. Save this ID to map this request with the corresponding webhook result. - `status` string - `error_code` unknown - `error_message` unknown - `total_requested_enrichments` integer - `unique_enriched_records` integer - `missing_records` integer - `credits_consumed` integer - `matches` object[] - `id` string - `first_name` string - `last_name` string - `name` string - `linkedin_url` string - `title` string - `email_status` string - `photo_url` string - `twitter_url` unknown - `github_url` unknown - `facebook_url` unknown - `extrapolated_email_confidence` number, nullable - `headline` string - `email` string - `organization_id` string - `employment_history` object[] - `_id` string - `created_at` unknown - `current` boolean - `degree` unknown - `description` unknown - `emails` unknown - `end_date` unknown - `grade_level` unknown - `kind` unknown - `major` unknown - `organization_id` string - `organization_name` string - `raw_address` unknown - `start_date` string - `title` string - `updated_at` unknown - `id` string - `key` string - `state` string - `city` string - `country` string - `organization` object - `id` string - `name` string - `website_url` string - `blog_url` unknown - `angellist_url` unknown - `linkedin_url` string - `twitter_url` string - `facebook_url` string - `primary_phone` object - `languages` unknown[] - unknown - `alexa_ranking` integer - `phone` unknown - `linkedin_uid` string - `founded_year` integer - `publicly_traded_symbol` unknown - `publicly_traded_exchange` unknown - `logo_url` string - `crunchbase_url` unknown - `primary_domain` string - `industry` string - `keywords` string[] - `estimated_num_employees` integer - `industries` string[] - `secondary_industries` unknown[] - unknown - `snippets_loaded` boolean - `industry_tag_id` string - `industry_tag_hash` object - `information technology & services` string - `retail_location_count` integer - `raw_address` string - `street_address` string - `city` string - `state` string - `postal_code` string - `country` string - `is_likely_to_engage` boolean - `account_id` string - `account` object - `id` string - `name` string - `website_url` string - `blog_url` unknown - `angellist_url` unknown - `linkedin_url` string - `twitter_url` string - `facebook_url` string - `primary_phone` object - `languages` unknown[] - unknown - `alexa_ranking` integer - `phone` string - `linkedin_uid` string - `founded_year` integer - `publicly_traded_symbol` unknown - `publicly_traded_exchange` unknown - `logo_url` string - `crunchbase_url` unknown - `primary_domain` string - `domain` string - `team_id` string - `organization_id` string - `account_stage_id` unknown - `source` string - `original_source` string - `creator_id` unknown - `owner_id` string - `created_at` string - `phone_status` string - `hubspot_id` unknown - `salesforce_id` string - `crm_owner_id` string - `parent_account_id` unknown - `sanitized_phone` string - `account_playbook_statuses` unknown[] - unknown - `account_rule_config_statuses` object[] - `_id` string - `created_at` unknown - `rule_action_config_id` string - `rule_config_id` string - `status_cd` string - `updated_at` unknown - `id` string - `key` string - `existence_level` string - `label_ids` string[] - `typed_custom_fields` object - `custom_field_errors` unknown - `modality` string - `source_display_name` string - `salesforce_record_url` string - `crm_record_url` string - `departments` string[] - `subdepartments` string[] - `seniority` string - `functions` string[] - `intent_strength` unknown - `show_intent` boolean - `revealed_for_current_team` boolean ## Other responses - `400` — 400 - `401` — 401 - `422` — 422 - `429` — 429 --- [API](https://skmtc.dev/apollo/apis/apollo-rest-api.md) · [All operations](https://skmtc.dev/apollo/apis/apollo-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/apollo/apollo-rest-api/revisions/c715a05fa6e2/schema)