> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bizzy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Enrich Contacts

Queues email and/or mobile phone enrichment for many (company, contact) pairs at once. Returns one result per requested pair, in request order — poll each result's `enrichmentId` via [Enrichment Status](../enrichments/status). A bad or unaffordable pair degrades to a per-item `message` instead of failing the whole batch.

<Note>
  Enriching costs credits - see the [Credit usage section](../credits)
</Note>

## Request

#### Header

<ParamField header="Accept-Language" type="string" default="EN">
  * NL: Dutch - FR: French - EN: English
</ParamField>

#### Body

<ParamField path="companyContacts" type="array">
  <Expandable title="companyContact properties">
    <ResponseField name="companyIdentifier" type="object" required>
      <Expandable title="companyIdentifier properties">
        <ResponseField name="companyId" type="string" required>
          Obfuscated companyId returned by the search endpoint.
        </ResponseField>

        <ResponseField name="countryCode" type="string" required>
          Any supported country code — see [Supported countries](/api-reference/v2/supported-countries).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="contacts" type="array" required>
      <Expandable title="contact properties">
        <ResponseField name="contactId" type="string" required>
          contactId is the unique identifier you get from the contacts endpoint.
        </ResponseField>
      </Expandable>

      <Note>
        You can request up to 50 contacts per company at once.
      </Note>
    </ResponseField>
  </Expandable>

  <Note>
    You can request up to 100 companies at once.
  </Note>
</ParamField>

<ParamField body="enrichEmail" type="boolean" default="false">
  Enrich contacts with an email address, if available.
</ParamField>

<ParamField body="enrichMobilePhone" type="boolean" default="false">
  Enrich contacts with a mobile phone number, if available.
</ParamField>

<Note>
  At least one of `enrichEmail` or `enrichMobilePhone` must be `true`.
</Note>

## Response

Returns `202 Accepted`. Unlike the single endpoint, no `Location` header is set (there's no single created resource to point at).

<Note>
  When any pair in the batch is charged, the response includes `X-Bizzy-Credits-Balance` and `X-Bizzy-Credits-Charged` headers — the balance reflects the post-charge total, and the charged amount is summed across all charged pairs in the batch. See [Credit usage](../credits).
</Note>

<ResponseField name="results" type="array">
  One entry per requested (company, contact) pair, in request order.
</ResponseField>

<ResponseField name="enrichmentId" type="string | null">
  Obfuscated id used to poll the [Enrichment Status](../enrichments/status) endpoint. `null` when `message` is set.
</ResponseField>

<ResponseField name="status" type="string | null">
  Always `PENDING` on creation, or `null` when `message` is set.
</ResponseField>

<ResponseField name="message" type="string | null">
  Set when this pair could not be queued (e.g. contact not found), leaving `enrichmentId`/`status` `null`. Other pairs in the batch are unaffected.
</ResponseField>

<ResponseExample>
  ```json Response - 202 theme={null}
  {
      "results": [
          {
              "companyIdentifier": {
                  "countryCode": "BE",
                  "companyId": "1778186251",
                  "name": "Bizzy"
              },
              "contactIdentifier": {
                  "contactId": "1234567890",
                  "firstName": "John",
                  "lastName": "Doe"
              },
              "enrichmentId": "8817263",
              "status": "PENDING",
              "message": null
          },
          {
              "companyIdentifier": {
                  "countryCode": "BE",
                  "companyId": "1778186251",
                  "name": "Bizzy"
              },
              "contactIdentifier": {
                  "contactId": "123",
                  "firstName": null,
                  "lastName": ""
              },
              "enrichmentId": null,
              "status": null,
              "message": "Contact not found"
          }
      ]
  }
  ```
</ResponseExample>