API Documentation

Integrate NPI lookup functionality into your applications

RESTful API
JSON Responses
Analytics & Stats
Custom Config
Rate Limited

Quick Start

Our API provides programmatic access to the National Provider Identifier (NPI) database. All endpoints return JSON responses and follow RESTful conventions.

Base URL
https://api.usnpi.com

Authentication

API Key Required

Most endpoints require an API key for authentication. Include your API key in the request headers.

X-API-Key: your-api-key-here

Rate Limits

API requests are rate-limited to ensure fair usage and system stability.

Free Tier:100 requests/day
Pro Tier:10,000 requests/day

API Endpoints

POST/search

Search for healthcare providers by query string

Example Request
POST /api/search
Content-Type: application/json

{
  "query": "John Smith",
  "page": 1,
  "per_page": 20
}
POST/providers/{state}

Get list of providers for a specific state

Example Request
POST /api/providers/california
Content-Type: application/json

{
  "page": 1,
  "filters": []
}
POST/hospitals/{state}

Get list of hospitals for a specific state

Example Request
POST /api/hospitals/texas
Content-Type: application/json

{
  "page": 1,
  "filters": []
}
POST/doctors/{state}

Get list of doctors for a specific state

Example Request
POST /api/doctors/new-york
Content-Type: application/json

{
  "page": 1,
  "filters": []
}
GET/states

Get list of all available states

Example Request
GET /api/states

Above is a selection of example requests. The full API also includes: single entity cards, GeoJSON endpoints for maps, filter configs, nursing homes, home health, help agencies, taxonomies, and comments.

/providers/show/{id}/hospitals/points/{state}/providers/filters/{state}/taxonomies/comments
Useful to explore:OpenAPI specification—full endpoint list

Custom Configuration

We offer tailored API solutions for individual requirements. Whether you need higher rate limits, dedicated support, custom data exports, or integration with your existing infrastructure — we can configure the API to match your specific use case.

  • Custom rate limits and quotas
  • Dedicated endpoints or priority access
  • Bulk data access and exports
  • SLA guarantees and technical support

Contact us to discuss your needs and get a custom proposal.

Request custom configuration

Statistics & Analytics

Access aggregated statistics and analytics from our healthcare provider database. The analytics API returns pre-computed metrics: provider counts by type, rating distributions, ownership breakdowns, specialty charts, and payment averages by state.

Analytics Endpoints (GET)

  • /analytics/overview
  • /analytics/hospitals
  • /analytics/nursing-homes
  • /analytics/doctors
  • /analytics/home-health
  • /analytics/hospices
  • /analytics/providers
  • /analytics/payments

Optional parameter

Add ?state=california to filter statistics by state.

Example: GET /api/analytics/overview?state=texas

View public analytics dashboard

Response Format

All API responses are returned in JSON format. Successful responses include:

{
  "data": [...],
  "current_page": 1,
  "last_page": 10,
  "per_page": 20,
  "total": 200,
  "from": 1,
  "to": 20,
  "next_page_url": "https://api.usnpi.com/...?page=2",
  "prev_page_url": null
}

Note: responses may also include a meta object with SEO fields (title, description, h1, canonical). API clients can safely ignore it.

Error Responses

Error responses follow standard HTTP status codes and include an error message in the response body.

Code Examples

JavaScript / Fetch

const response = await fetch('https://api.usnpi.com/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key'
  },
  body: JSON.stringify({
    query: 'John Smith',
    page: 1,
    per_page: 20
  })
});

const data = await response.json();
console.log(data);

cURL

curl -X POST https://api.usnpi.com/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "query": "John Smith",
    "page": 1,
    "per_page": 20
  }'

Python / Requests

import requests

response = requests.post(
    'https://api.usnpi.com/search',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'your-api-key'
    },
    json={
        'query': 'John Smith',
        'page': 1,
        'per_page': 20
    }
)

data = response.json()
print(data)

Best Practices

Follow these guidelines for optimal API usage

Implement Caching

Cache API responses when appropriate to reduce requests and improve performance.

Handle Errors Gracefully

Always implement proper error handling and retry logic for failed requests.

Respect Rate Limits

Monitor your API usage and implement exponential backoff when hitting rate limits.

Keep API Keys Secure

Never expose your API keys in client-side code or public repositories.

Need Help Getting Started?

Our API documentation is comprehensive, but if you need additional support, our team is here to help.

Contact API SupportOpenAPI Specification

Ready to Integrate?

Start building with our API today

Get API Access