> ## 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.

# Get Bulk Email Enrichment Status and Results

> Poll the status of a bulk enrichment batch by batch_id. Returns the response envelope with per-request results, progress, and usage.

Poll the status of a previously submitted bulk enrichment batch. The response uses the same envelope shape as single-request polling and webhooks, with multiple items in the `data` array. Track progress by comparing `completed_count` to `total`.

## Path parameters

<ParamField path="batch_id" type="string" required>
  The batch ID returned by `POST /api/v1/email/bulk`.
</ParamField>

## Header parameters

<ParamField header="Authorization" type="string" required>
  `Bearer <your_api_key>`
</ParamField>

<ParamField header="X-API-Key" type="string">
  Optional alternative to the Authorization Bearer scheme. Your API key sent as a header.
</ParamField>

## Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ext-api.dmand.ai/api/v1/batch/b_456" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

  response = requests.get(
      "https://ext-api.dmand.ai/api/v1/batch/b_456",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://ext-api.dmand.ai/api/v1/batch/b_456", {
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
  });
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

<ResponseField name="batch" type="object" required>
  Batch metadata.

  <Expandable title="batch fields">
    <ResponseField name="id" type="string" required>
      Batch identifier.
    </ResponseField>

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

    <ResponseField name="total" type="integer" required>
      Total number of requests in the batch.
    </ResponseField>

    <ResponseField name="completed_count" type="integer" required>
      Number of requests that have finished.
    </ResponseField>

    <ResponseField name="created_at" type="string | null">
      ISO 8601 timestamp when the batch was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string | null">
      ISO 8601 timestamp when the batch was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="webhook" type="object | null">
  Webhook configuration and delivery status. `null` when no webhook was provided at submission.

  <Expandable title="webhook fields">
    <ResponseField name="url" type="string | null">
      The callback URL.
    </ResponseField>

    <ResponseField name="mode" type="string | null">
      `real-time` or `batch`.
    </ResponseField>

    <ResponseField name="status" type="string | null">
      Webhook delivery status: `pending`, `delivered`, `failed`, or `none`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="custom_data" type="object | null">
  The exact JSON object you provided in the submission request.
</ResponseField>

<ResponseField name="usage" type="object | null">
  Credit usage for this response.

  <Expandable title="usage fields">
    <ResponseField name="credits_used" type="number | null">
      Credits consumed for this batch.
    </ResponseField>

    <ResponseField name="balance" type="number | null">
      Remaining credit balance after this batch.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="object[]" required>
  Array of per-request results for every NPI in the batch.

  <Expandable title="data item fields">
    <ResponseField name="request_id" type="string" required>
      Unique request identifier.
    </ResponseField>

    <ResponseField name="npi" type="string" required>
      The submitted 10-digit NPI.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Request status. See status values below.
    </ResponseField>

    <ResponseField name="replayed" type="boolean" default="false">
      `true` when this result is a free replay within `30` days for the same organization and NPI.
    </ResponseField>

    <ResponseField name="email_type" type="string | null">
      Type of email found. Example values include `personal` and `professional`.
    </ResponseField>

    <ResponseField name="email" type="string | null">
      The enriched email address, if found.
    </ResponseField>

    <ResponseField name="email_last_validated" type="string | null">
      ISO 8601 date when the email was last validated.
    </ResponseField>

    <ResponseField name="email_status" type="string | null">
      Validation status of the email. `valid` when an email is returned, otherwise `null`.
    </ResponseField>
  </Expandable>
</ResponseField>

### Status values

| Status        | Meaning                                                                       |
| ------------- | ----------------------------------------------------------------------------- |
| `accepted`    | The request was received and is queued for processing.                        |
| `in-progress` | The request is still being resolved.                                          |
| `completed`   | An email was found and the email fields are populated.                        |
| `not_found`   | No email was found. No credits are charged.                                   |
| `failed`      | The request could not finish within about `15` minutes. Credits are refunded. |

### Example response

```json theme={null}
{
  "batch": {
    "id": "b_456",
    "status": "in-progress",
    "total": 3,
    "completed_count": 2,
    "created_at": "2026-09-28T10:00:00Z",
    "updated_at": "2026-09-28T10:05:00Z"
  },
  "webhook": {
    "url": "https://example.com/hooks/dmand",
    "mode": "batch",
    "status": "pending"
  },
  "custom_data": {
    "campaign": "q3-outreach"
  },
  "usage": {
    "credits_used": 1,
    "balance": 999
  },
  "data": [
    {
      "request_id": "r_789",
      "npi": "1003158791",
      "status": "completed",
      "replayed": false,
      "email_type": "professional",
      "email": "jane.doe@examplehealth.org",
      "email_last_validated": "2026-09-20T00:00:00Z",
      "email_status": "valid"
    },
    {
      "request_id": "r_790",
      "npi": "1234567890",
      "status": "not_found",
      "replayed": false,
      "email_type": null,
      "email": null,
      "email_last_validated": null,
      "email_status": null
    },
    {
      "request_id": "r_791",
      "npi": "9876543210",
      "status": "in-progress",
      "replayed": false,
      "email_type": null,
      "email": null,
      "email_last_validated": null,
      "email_status": null
    }
  ]
}
```

## Errors

* Missing or invalid API keys are rejected.
* `403`: Revoked or inactive API key.
* `422`: Validation error, with a response body like:

```json theme={null}
{
  "detail": [
    {
      "loc": ["path", "batch_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

## Tips

* There is no pagination on this endpoint. The `data` array contains all requests in the batch.
* Compare `completed_count` to `total` to know when the entire batch is done.
* Use webhooks as your primary notification mechanism and poll only as a fallback if a webhook does not arrive.
* Dedupe updates by `request_id` so replays and retries do not create duplicate records in your system.