Dmand AI API Data Dictionary: Request and Response Fields

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 `100` 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:

{
  "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:

{
  "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.
`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:

{
  "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.

Getting Started

Core Concepts

Implement In Product

API Reference

Dmand AI API Data Dictionary: Request and Response Fields

Submit request body (single)

Submit request body (bulk)

Webhook object

Submit response

Response envelope (single poll, batch poll, and webhook)

Top-level fields

`batch` object

`webhook` object (in envelope)

`usage` object

`data` items

Credits response

​Submit request body (single)

​Submit request body (bulk)

​Webhook object

​Submit response

​Response envelope (single poll, batch poll, and webhook)

​Top-level fields

​batch object

​webhook object (in envelope)

​usage object

​data items

​Credits response

Submit request body (single)

Submit request body (bulk)

Webhook object

Submit response

Response envelope (single poll, batch poll, and webhook)

Top-level fields

`batch` object

`webhook` object (in envelope)

`usage` object

`data` items

Credits response