> ## 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. # Dmand AI API Data Dictionary: Request and Response Fields > Complete field reference for Dmand AI API request bodies, submit responses, poll and webhook envelopes, and the credits balance endpoint. This page documents every field in Dmand AI API request bodies and responses. Use it alongside the endpoint references to understand exactly what to send and what to expect back. ## Submit request body (single) `POST /api/v1/email` accepts the following fields: | Field | Type | Required | Description | | ----------------------- | ------ | -------- | ----------------------------------------------------------- | | `npi` | string | Yes | The NPI to enrich. | | `enrichment_email_type` | string | No | `any` (default), `personal`, or `professional`. | | `webhook` | object | No | Delivery configuration. See webhook object below. | | `custom_data` | object | No | Any JSON object. Echoed back in poll and webhook responses. | ## Submit request body (bulk) `POST /api/v1/email/bulk` accepts the following fields: | Field | Type | Required | Description | | ----------------------- | ---------------- | -------- | ----------------------------------------------------------- | | `npis` | array of strings | Yes | 1 to `60` NPIs per request. | | `enrichment_email_type` | string | No | `any` (default), `personal`, or `professional`. | | `webhook` | object | No | Delivery configuration. See webhook object below. | | `custom_data` | object | No | Any JSON object. Echoed back in poll and webhook responses. | ## Webhook object Include this object in the `webhook` field when you want Dmand to POST results to your server. | Field | Type | Required | Description | | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `url` | string | Yes | The HTTPS URL to deliver results to. | | `mode` | string | No | `real-time` (default) or `batch`. `real-time` sends one delivery per NPI. `batch` sends one delivery when the whole batch completes. | ## Submit response Both single and bulk submits return HTTP **202** with the same shape: ```json theme={null} { "batch_id": "b_123", "status": "in-progress", "requests": [ { "npi": "1003158791", "request_id": "r_456", "poll_url": "/api/v1/email/r_456" } ] } ``` | Field | Type | Description | | ----------------------- | ------ | ------------------------------------------------------------------------ | | `batch_id` | string | Unique identifier for the batch. Even single submits are a batch of one. | | `status` | string | Batch status: `in-progress` or `completed`. | | `requests` | array | One entry per submitted NPI. | | `requests[].npi` | string | The submitted NPI. | | `requests[].request_id` | string | Unique identifier for this NPI's enrichment request. | | `requests[].poll_url` | string | Relative URL to poll this individual request. | ## Response envelope (single poll, batch poll, and webhook) `GET /api/v1/email/{request_id}`, `GET /api/v1/batch/{batch_id}`, and webhook deliveries all share the same envelope: ```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:04Z" }, "webhook": { "url": "https://example.com/hooks/dmand", "mode": "real-time", "status": "delivered" }, "custom_data": { "crm_record_id": "abc123" }, "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" } ] } ``` ### Top-level fields | Field | Type | Description | | ------------- | -------------- | ------------------------------------------------------------------------------------------------ | | `batch` | object | Required. Summary of the batch. | | `webhook` | object \| null | The webhook configuration used for this batch, plus delivery status. Null if no webhook was set. | | `custom_data` | object \| null | The `custom_data` you sent at submit. Null if none was provided. | | `usage` | object \| null | Credits consumed by this batch and your remaining balance. | | `data` | array | Required. One item per submitted NPI. | ### `batch` object | Field | Type | Description | | ----------------- | -------------- | ---------------------------------------------- | | `id` | string | Batch identifier. | | `status` | string | Batch status: `in-progress` or `completed`. | | `total` | integer | Total number of requests in the batch. | | `completed_count` | integer | Number of requests that have finished. | | `created_at` | string \| null | ISO 8601 timestamp when the batch was created. | | `updated_at` | string \| null | ISO 8601 timestamp of the most recent update. | ### `webhook` object (in envelope) | Field | Type | Description | | -------- | -------------- | ------------------------------------------------------------- | | `url` | string \| null | The delivery URL. | | `mode` | string \| null | `real-time` or `batch`. | | `status` | string \| null | Delivery status: `pending`, `delivered`, `failed`, or `none`. | ### `usage` object | Field | Type | Description | | -------------- | -------------- | ---------------------------------------- | | `credits_used` | number \| null | Credits charged for this batch. | | `balance` | number \| null | Remaining credits for your organization. | ### `data` items | Field | Type | Description | | ---------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | | `request_id` | string | Unique request identifier. | | `npi` | string | The submitted NPI. | | `status` | string | Request status. `accepted`, `in-progress`, `completed`, `not_found`, or `failed`. See [Statuses](/general/contact-status). | | `replayed` | boolean | `true` if this result was returned from cache within `30` days. Default is `false`. | | `email_type` | string \| null | Type of email returned, for example `professional` or `personal`. | | `email` | string \| null | The enriched email address. Null when not found. | | `email_last_validated` | string \| null | ISO 8601 timestamp of the last validation. | | `email_status` | string \| null | Verification status: `valid` when an email is returned, otherwise `null`. | ## Credits response `GET /api/v1/credits` returns your organization's credit balance: ```json theme={null} { "balance": 850, "total": 1000, "used": 150 } ``` | Field | Type | Description | | --------- | ------ | --------------------------------------------- | | `balance` | number | Remaining credits available. | | `total` | number | Total credits allocated to your organization. | | `used` | number | Total credits already consumed. |