> ## Documentation Index > Fetch the complete documentation index at: https://docs.pipecorn.com/llms.txt > Use this file to discover all available pages before exploring further. # Bulk Contact Enrichment > Enrich up to 100 contacts in a single asynchronous batch Enqueue up to **100 contacts** for waterfall enrichment in a single request. The endpoint returns immediately with an `enrichment_id` for the bulk job; each contact is enriched asynchronously and results are delivered to your `webhook_url` as each contact completes. ## Constraints * **Minimum:** 2 contacts per request. For a single contact, use the [single async endpoint](/api-reference/endpoints/enrichments/single). * **Maximum:** 100 contacts per request. * A single `enrichment_type` applies to every contact in the batch. ## Enrichment Types Pass `enrichment_type` as an array containing one of: * `["email"]` — Find and validate professional emails * `["phone"]` — Find phone numbers (requires `linkedin_url` on every contact) * `["personal_email"]` — Find personal emails (requires `linkedin_url` **and** account-level consent — see below) Requesting `personal_email` requires the authenticated user to have consented to personal email enrichment in their account settings. If consent is missing the entire batch is rejected with `422 Unprocessable Entity`. This consent gate is required for GDPR compliance. ## Required Fields per contact The required per-contact fields depend on the batch-wide `enrichment_type`: | `enrichment_type` | Required fields per contact | | -------------------- | ----------------------------------------------------------------------------------- | | `["email"]` | `firstname`, `lastname`, **and** one of `linkedin_url`, `domain`, or `company_name` | | `["phone"]` | `linkedin_url` | | `["personal_email"]` | `linkedin_url` | Phone and personal email batches run off each contact's `linkedin_url` alone, so `firstname`/`lastname` are not required for those types. ## Receiving results Provide `webhook_url` to receive results — we POST one payload per contact as each one finishes. The webhook payload echoes the `custom` fields you sent with that contact, so you can correlate results back to your records. ## Credits Credits are checked up-front for the entire batch. If your balance is insufficient the request is rejected with `422 Unprocessable Entity` and no contacts are enqueued. ## OpenAPI ````yaml POST /contacts/bulk_enrich openapi: 3.0.1 info: title: Pipecorn List API description: Pipecorn List API license: name: MIT version: 1.0.0 servers: - url: https://app.pipecorn.com/api/v2/ security: - defaultApiKey: [] paths: /contacts/bulk_enrich: post: summary: Enrich multiple contacts description: Enriches multiple contacts in bulk with specified data points. requestBody: description: Bulk contact information for enrichment required: true content: application/json: schema: type: object required: - contacts properties: webhook_url: type: string format: uri description: Webhook URL to receive enrichment results phone_country_codes: type: array items: type: string description: ISO 3166-1 alpha-2 country code (e.g. "US", "FR", "GB") description: >- Optional. Restrict phone enrichment to phone numbers from these countries (applies to every contact in the batch). When omitted, the user's account-level default phone country codes are applied. oneOf: - title: Email batch required: - enrichment_type - contacts properties: enrichment_type: type: array maxItems: 1 items: type: string enum: - email description: Set to ["email"] for the whole batch. contacts: type: array maxItems: 100 items: type: object required: - firstname - lastname properties: firstname: type: string description: First name of the contact. lastname: type: string description: Last name of the contact. linkedin_url: type: string format: uri description: LinkedIn profile URL of the contact. example: https://www.linkedin.com/in/mathieu-brun-picard/ domain: type: string description: Company domain. example: pipecorn.com company_name: type: string description: Company name. example: Pipecorn custom: type: object description: Custom fields to include with the enrichment. additionalProperties: true anyOf: - required: - linkedin_url - required: - domain - required: - company_name description: >- Each contact requires `firstname`, `lastname`, and one of `linkedin_url`, `domain`, or `company_name`. - title: Phone batch required: - enrichment_type - contacts properties: enrichment_type: type: array maxItems: 1 items: type: string enum: - phone description: Set to ["phone"] for the whole batch. contacts: type: array maxItems: 100 items: type: object required: - linkedin_url properties: firstname: type: string description: First name of the contact. lastname: type: string description: Last name of the contact. linkedin_url: type: string format: uri description: LinkedIn profile URL of the contact. example: https://www.linkedin.com/in/mathieu-brun-picard/ domain: type: string description: Company domain. example: pipecorn.com company_name: type: string description: Company name. example: Pipecorn custom: type: object description: Custom fields to include with the enrichment. additionalProperties: true description: Each contact requires only `linkedin_url`. - title: Personal email batch required: - enrichment_type - contacts properties: enrichment_type: type: array maxItems: 1 items: type: string enum: - personal_email description: >- Set to ["personal_email"] for the whole batch. Requires GDPR consent. contacts: type: array maxItems: 100 items: type: object required: - linkedin_url properties: firstname: type: string description: First name of the contact. lastname: type: string description: Last name of the contact. linkedin_url: type: string format: uri description: LinkedIn profile URL of the contact. example: https://www.linkedin.com/in/mathieu-brun-picard/ domain: type: string description: Company domain. example: pipecorn.com company_name: type: string description: Company name. example: Pipecorn custom: type: object description: Custom fields to include with the enrichment. additionalProperties: true description: >- Each contact requires `linkedin_url`; the account must have GDPR consent. example: contacts: - firstname: Mathieu lastname: Brun-Picard domain: pipecorn.com company_name: Pipecorn linkedin_url: https://www.linkedin.com/in/mathieu-brun-picard/ custom: hubspot_id: '4447901' - firstname: Nicolas lastname: Fernandez-Le Follic domain: pipecorn.com company_name: Pipecorn linkedin_url: https://www.linkedin.com/in/nicolasfernandezlefollic/ custom: hubspot_id: '4447902' webhook_url: https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8 enrichment_type: - email responses: '200': description: >- Bulk enrichment request accepted. Each contact is enriched asynchronously; results are delivered via the `webhook_url` callback as each contact finishes. content: application/json: schema: type: object properties: enrichment_id: type: string format: uuid description: The ID of the bulk enrichment job example: enrichment_id: 123e4567-e89b-12d3-a456-426614174000 '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- Unprocessable Entity. Returned when validation fails (e.g. unsupported `enrichment_type` value, missing required identifiers), when the user has not consented to personal email enrichment but requested `personal_email`, or when there are not enough credits. content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_credits: summary: Insufficient credits value: error: 422 message: Not enough enrichment credits left personal_email_consent_missing: summary: Personal email consent missing value: error: 422 message: >- You can't use the personal email enrichment feature without consenting with our terms of use components: schemas: Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string securitySchemes: defaultApiKey: type: apiKey in: header description: Your API key name: X-API-KEY ````