> ## 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 Started with the Dmand AI API in Four Steps

> Learn how to submit an NPI to the Dmand AI API, receive a batch ID, poll for the result, and optionally add a webhook for async delivery.

This quickstart walks you through your first Dmand AI enrichment. You submit a provider NPI, the API accepts it asynchronously, and you fetch the email once it resolves. You need a Dmand AI API key.

<Steps>
  <Step title="Get your API key">
    Get your API key from the Dmand AI team. Send it on every request as `Authorization: Bearer YOUR_API_KEY`. See [Authentication](/general/authentication) for details.
  </Step>

  <Step title="Submit an NPI">
    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url https://ext-api.dmand.ai/api/v1/email \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'Content-Type: application/json' \
        --data '{"npi": "1003158791", "enrichment_email_type": "any"}'
      ```

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

      url = "https://ext-api.dmand.ai/api/v1/email"
      headers = {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      }
      payload = {"npi": "1003158791", "enrichment_email_type": "any"}

      response = requests.post(url, headers=headers, json=payload)
      print(response.json())
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch("https://ext-api.dmand.ai/api/v1/email", {
        method: "POST",
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          npi: "1003158791",
          enrichment_email_type: "any",
        }),
      });

      const data = await response.json();
      console.log(data);
      ```
    </CodeGroup>

    The API returns HTTP 202 with a `batch_id`, `status`, and a `requests` array:

    ```json theme={null}
    {
      "batch_id": "b_8f2c1a7e",
      "status": "in-progress",
      "requests": [
        {
          "npi": "1003158791",
          "request_id": "r_abc123",
          "poll_url": "/api/v1/email/r_abc123"
        }
      ]
    }
    ```
  </Step>

  <Step title="Poll for the result">
    ```bash theme={null}
    curl --request GET \
      --url https://ext-api.dmand.ai/api/v1/email/r_abc123 \
      --header 'Authorization: Bearer YOUR_API_KEY'
    ```

    Example poll response:

    ```json theme={null}
    {
      "batch": {
        "id": "b_8f2c1a7e",
        "status": "completed",
        "total": 1,
        "completed_count": 1,
        "created_at": "2026-09-28T10:00:00Z",
        "updated_at": "2026-09-28T10:00:05Z"
      },
      "webhook": null,
      "custom_data": null,
      "usage": {
        "credits_used": 1,
        "balance": 999
      },
      "data": [
        {
          "request_id": "r_abc123",
          "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"
        }
      ]
    }
    ```

    When `data[0].status` is `completed`, the result fields contain the verified email. If it is `accepted` or `in-progress`, check again later. A `not_found` status means no email was found, and you are not charged. A `failed` status means the request timed out; credits are refunded.
  </Step>

  <Step title="Add a webhook (optional)">
    Pass a `webhook` object in the submit body to receive results instead of polling:

    ```json theme={null}
    {
      "npi": "1003158791",
      "enrichment_email_type": "any",
      "webhook": {
        "url": "https://your-server.com/webhook",
        "mode": "real-time"
      }
    }
    ```

    See [Webhooks](/general/webhooks) for payload details and best practices.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Enrich in bulk" icon="layer-group" href="/api-reference/email/submit-bulk">
    Submit up to `60` NPIs per request
  </Card>

  <Card title="Credits & Billing" icon="coins" href="/general/credits">
    Learn when credits are held, charged, and refunded
  </Card>
</CardGroup>