Get Bulk Email Enrichment Status and Results
curl --request GET \
--url https://ext-api.dmand.ai/api/v1/batch/{batch_id} \
--header 'Authorization: <authorization>'import requests
url = "https://ext-api.dmand.ai/api/v1/batch/{batch_id}"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://ext-api.dmand.ai/api/v1/batch/{batch_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://ext-api.dmand.ai/api/v1/batch/{batch_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://ext-api.dmand.ai/api/v1/batch/{batch_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://ext-api.dmand.ai/api/v1/batch/{batch_id}")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://ext-api.dmand.ai/api/v1/batch/{batch_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"batch": {
"id": "<string>",
"status": "<string>",
"total": 123,
"completed_count": 123,
"created_at": {},
"updated_at": {}
},
"webhook": {
"url": {},
"mode": {},
"status": {}
},
"custom_data": {},
"usage": {
"credits_used": {},
"balance": {}
},
"data": [
{
"request_id": "<string>",
"npi": "<string>",
"status": "<string>",
"replayed": true,
"email_type": {},
"email": {},
"email_last_validated": {},
"email_status": {}
}
]
}API Reference
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.
GET
/
api
/
v1
/
batch
/
{batch_id}
Get Bulk Email Enrichment Status and Results
curl --request GET \
--url https://ext-api.dmand.ai/api/v1/batch/{batch_id} \
--header 'Authorization: <authorization>'import requests
url = "https://ext-api.dmand.ai/api/v1/batch/{batch_id}"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://ext-api.dmand.ai/api/v1/batch/{batch_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://ext-api.dmand.ai/api/v1/batch/{batch_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://ext-api.dmand.ai/api/v1/batch/{batch_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://ext-api.dmand.ai/api/v1/batch/{batch_id}")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://ext-api.dmand.ai/api/v1/batch/{batch_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"batch": {
"id": "<string>",
"status": "<string>",
"total": 123,
"completed_count": 123,
"created_at": {},
"updated_at": {}
},
"webhook": {
"url": {},
"mode": {},
"status": {}
},
"custom_data": {},
"usage": {
"credits_used": {},
"balance": {}
},
"data": [
{
"request_id": "<string>",
"npi": "<string>",
"status": "<string>",
"replayed": true,
"email_type": {},
"email": {},
"email_last_validated": {},
"email_status": {}
}
]
}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
string
required
The batch ID returned by
POST /api/v1/email/bulk.Header parameters
string
required
Bearer <your_api_key>string
Optional alternative to the Authorization Bearer scheme. Your API key sent as a header.
Request example
curl -X GET "https://ext-api.dmand.ai/api/v1/batch/b_456" \
-H "Authorization: Bearer YOUR_API_KEY"
import requests
response = requests.get(
"https://ext-api.dmand.ai/api/v1/batch/b_456",
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
print(response.json())
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);
Response
object
required
Batch metadata.
Show batch fields
Show batch fields
string
required
Batch identifier.
string
required
Overall batch status:
in-progress or completed.integer
required
Total number of requests in the batch.
integer
required
Number of requests that have finished.
string | null
ISO 8601 timestamp when the batch was created.
string | null
ISO 8601 timestamp when the batch was last updated.
object | null
object | null
The exact JSON object you provided in the submission request.
object | null
object[]
required
Array of per-request results for every NPI in the batch.
Show data item fields
Show data item fields
string
required
Unique request identifier.
string
required
The submitted 10-digit NPI.
string
required
Request status. See status values below.
boolean
default:"false"
true when this result is a free replay within 30 days for the same organization and NPI.string | null
Type of email found. Example values include
personal and professional.string | null
The enriched email address, if found.
string | null
ISO 8601 date when the email was last validated.
string | null
Validation status of the email.
valid when an email is returned, otherwise null.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
{
"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:
{
"detail": [
{
"loc": ["path", "batch_id"],
"msg": "Field required",
"type": "missing"
}
]
}
Tips
- There is no pagination on this endpoint. The
dataarray contains all requests in the batch. - Compare
completed_counttototalto 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_idso replays and retries do not create duplicate records in your system.