How Dmand AI Webhooks Deliver Enrichment Results

The Dmand AI API is fully asynchronous. When you submit an enrichment, the API immediately returns a batch_id and a requests array. Results are delivered later by webhook or retrieved by polling. Webhooks are the recommended way to receive results because they do not count against your rate limit.

Why webhooks

Webhooks push results to your server as soon as they are ready. You do not need to poll or keep a connection open. They are faster than polling and do not consume your rate limit.

How it works

Include a webhook object in your single or bulk submit request.
Dmand processes the NPI and resolves or verifies the email.
Dmand POSTs the result to your callback URL in the same envelope format used by polling.

Webhook modes

Choose how you want to receive notifications with the webhook.mode field.

real-time (default): One webhook per NPI as it resolves. Use this when you want to act on each result immediately.
batch: One webhook when the entire batch completes. Use this when you only need the final summary.

Submit with a webhook

{
  "npi": "1003158791",
  "webhook": {
    "url": "https://your-server.com/webhook",
    "mode": "real-time"
  },
  "custom_data": {
    "internal_id": "contact_42"
  }
}

Webhook payload

The payload uses the same envelope as polling and batch poll responses. The webhook object describes the delivery configuration, and data contains the per-NPI results.

{
  "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://your-server.com/webhook",
    "mode": "real-time",
    "status": "delivered"
  },
  "custom_data": {
    "internal_id": "contact_42"
  },
  "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"
    }
  ]
}

If no webhook was provided, the webhook field is null.

Echoing custom data with custom_data

Include custom_data in the submit body to attach any JSON object. It is echoed verbatim in every poll response and webhook payload. Use it to pass internal identifiers, correlation IDs, or tags so you can match results to your own records.

Responding to webhooks and retry behavior

Your endpoint must return an HTTP 2xx response as quickly as possible. Perform heavy processing asynchronously so you do not block the response. If your endpoint returns a non-2xx response, Dmand retries delivery with backoff. Make your handler idempotent and deduplicate by request_id to avoid processing the same result more than once.

Testing webhooks

Use webhook.site to get a temporary URL and inspect real payloads without setting up your own server.

Polling fallback

If you cannot receive webhooks, you can poll GET /api/v1/email/{request_id} or GET /api/v1/batch/{batch_id}. Polling consumes your rate limit and delivers results more slowly. If you must poll, space requests at reasonable intervals. Do not rely solely on webhooks; poll as a fallback if a webhook does not arrive.

Getting Started

Core Concepts

Implement In Product

API Reference

How Dmand AI Webhooks Deliver Enrichment Results

Why webhooks

How it works

Webhook modes

Submit with a webhook

Webhook payload

Echoing custom data with custom_data

Responding to webhooks and retry behavior

Testing webhooks

Polling fallback

​Why webhooks

​How it works

​Webhook modes

​Submit with a webhook

​Webhook payload

​Echoing custom data with custom_data

​Responding to webhooks and retry behavior

​Testing webhooks

​Polling fallback

Why webhooks

How it works

Webhook modes

Submit with a webhook

Webhook payload

Echoing custom data with custom_data

Responding to webhooks and retry behavior

Testing webhooks

Polling fallback