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

# Submit Bulk NPIs for Email Enrichment via Dmand AI

> Submit multiple NPIs in a single batch request. Returns 202 with batch_id, status, and request references. Poll or use webhooks to receive results.

Submit multiple NPIs in one call to enrich emails for several healthcare providers at once. The endpoint accepts up to `60` NPIs per request and returns a `batch_id`. Dmand AI processes the batch asynchronously and delivers results via polling or webhooks.

## Header parameters

<ParamField header="Idempotency-Key" type="string">
  Optional. Send a unique value so retrying the same submit does not create a duplicate request. Use a UUID or a hash of the request body.
</ParamField>

<ParamField header="X-API-Key" type="string">
  Optional alternative to the `Authorization: Bearer` header.
</ParamField>

## Body parameters

<ParamField body="npis" type="string[]" required>
  Array of 10-digit NPI strings. Minimum 1 item, maximum `60` items per request.
</ParamField>

<ParamField body="enrichment_email_type" default="any" type="string">
  Preferred email category. Options: `any` (`1` credit), `professional` (`1` credit), `personal` (`3` credits). Credits are charged per email found. See [Credits](/general/credits).
</ParamField>

<ParamField body="webhook" type="object">
  Optional webhook configuration. When provided, Dmand AI POSTs the response envelope to the specified URL as results become available.

  <Expandable title="webhook fields">
    <ResponseField name="url" type="string" required>
      The HTTPS URL that receives the webhook POST.
    </ResponseField>

    <ResponseField name="mode" type="string" default="real-time">
      `real-time` sends one webhook per NPI as it finishes. `batch` sends one webhook when the whole batch completes.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="custom_data" type="object">
  Optional JSON object that Dmand AI echoes back in poll responses and webhooks. Use it to attach your own IDs or metadata.
</ParamField>

## Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://ext-api.dmand.ai/api/v1/email/bulk \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 7f8a9b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c" \
    -d '{
      "npis": [
        "1003158791",
        "1234567890",
        "9876543210"
      ],
      "enrichment_email_type": "any",
      "webhook": {
        "url": "https://example.com/webhooks/dmand",
        "mode": "batch"
      },
      "custom_data": { "campaign": "q3-outreach" }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://ext-api.dmand.ai/api/v1/email/bulk",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
          "Idempotency-Key": "7f8a9b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c"
      },
      json={
          "npis": ["1003158791", "1234567890", "9876543210"],
          "enrichment_email_type": "any",
          "webhook": {
              "url": "https://example.com/webhooks/dmand",
              "mode": "batch"
          },
          "custom_data": {"campaign": "q3-outreach"}
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://ext-api.dmand.ai/api/v1/email/bulk", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "7f8a9b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c"
    },
    body: JSON.stringify({
      npis: ["1003158791", "1234567890", "9876543210"],
      enrichment_email_type: "any",
      webhook: {
        url: "https://example.com/webhooks/dmand",
        mode: "batch"
      },
      custom_data: { campaign: "q3-outreach" }
    })
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

<ResponseField name="batch_id" type="string">
  Unique identifier for the submitted batch. Use it to poll batch status.
</ResponseField>

<ResponseField name="status" type="string">
  Overall status of the submitted batch: `in-progress` or `completed`.
</ResponseField>

<ResponseField name="requests" type="array">
  Array of request references containing the NPI, request\_id, and a relative poll URL.

  <Expandable title="request item fields">
    <ResponseField name="npi" type="string">
      The submitted 10-digit NPI.
    </ResponseField>

    <ResponseField name="request_id" type="string">
      Unique identifier for this request. Use it to poll status or deduplicate webhook deliveries.
    </ResponseField>

    <ResponseField name="poll_url" type="string">
      A relative URL you can GET to check status. Example: `/api/v1/email/r_456`.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example response (202 Accepted)

```json theme={null}
{
  "batch_id": "b_789",
  "status": "in-progress",
  "requests": [
    {
      "npi": "1003158791",
      "request_id": "r_456",
      "poll_url": "/api/v1/email/r_456"
    },
    {
      "npi": "1234567890",
      "request_id": "r_457",
      "poll_url": "/api/v1/email/r_457"
    },
    {
      "npi": "9876543210",
      "request_id": "r_458",
      "poll_url": "/api/v1/email/r_458"
    }
  ]
}
```

## Errors

* Missing or invalid API keys are rejected.
* `403`: Revoked or inactive API key.
* `422`: Validation error. The response body contains `{"detail": [{"loc": [...], "msg": "...", "type": "..."}]}` with the location, message, and error type for each invalid field.
* Requests over the rate limit are rejected. Default limit is `100` requests per minute. See [Rate Limits](/general/rate-limits).