> ## 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 Single Email Request Status and Enrichment Result

> Poll the status of a single email enrichment request by request_id. Returns batch metadata, webhook, usage, and email result fields.

Poll the status of a previously submitted single NPI enrichment request. The response includes a unified envelope with batch metadata, webhook details, your `custom_data`, credit usage, and the per-request result. Prefer webhooks over polling to avoid hitting rate limits.

## Path parameters

<ParamField path="request_id" type="string" required>
  The request ID returned by `POST /api/v1/email`.
</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/email/r_456" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

  response = requests.get(
      "https://ext-api.dmand.ai/api/v1/email/r_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/email/r_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 for this request.

  <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 request.
    </ResponseField>

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

<ResponseField name="data" type="object[]" required>
  Array of per-request results. For a single request this contains one item.

  <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_123",
    "status": "completed",
    "total": 1,
    "completed_count": 1,
    "created_at": "2026-09-28T10:00:00Z",
    "updated_at": "2026-09-28T10:00:05Z"
  },
  "webhook": {
    "url": "https://example.com/hooks/dmand",
    "mode": "real-time",
    "status": "delivered"
  },
  "custom_data": {
    "lead_id": "lead-48291"
  },
  "usage": {
    "credits_used": 1,
    "balance": 999
  },
  "data": [
    {
      "request_id": "r_456",
      "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"
    }
  ]
}
```

## 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", "request_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

## Tips

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