# ProviderSignal API — Full Reference for LLM Agents

> Single-document reference covering every agent-callable endpoint, pricing in USDC, the citation envelope, and the free evaluation tier. Generated dynamically from canonical sources.

Last generated: 2026-08-10
Base URL: https://providersignal.com

## Quick start

The fastest path from zero to a working call is the free evaluation tier. No API key, no signup, no contract.

```
GET https://providersignal.com/api/v1/free/lookup?npi=1234567890
```

Returns up to 100 valid responses per source IP per day (rolling 24-hour window). Use to evaluate data quality before integrating into a paid workflow.

## Citation envelope

Every ProviderSignal API response uses the same JSON envelope:

```json
{
  "data": <T> | null,
  "error": null | string,
  "meta": {
    "envelope_version": "1.0",
    "source_attribution": [
      { "table": "...", "last_refresh": "ISO-8601", "schema_version": "v2", "license": "..." }
    ],
    "request": {
      "id": "req_...",
      "endpoint": "...",
      "billed_credits": 0,
      "billing_method": "free" | "subscription" | "per_query"
    },
    "confidence": { /* paid endpoints only */ }
  }
}
```

Field stability commitments live at https://providersignal.com/docs/fields. Stable fields carry a 6-month deprecation window; new fields are non-breaking additions.

## Free evaluation tier

### Endpoint

`GET /api/v1/free/lookup?npi=<10-digit-npi>`

No authentication header required. The endpoint is rate-limited by source IP, not by API key.

### Fields returned

- `npi`: 10-digit National Provider Identifier
- `first_name` / `last_name`: provider name (null for organizations)
- `organization_name`: entity name when entity_type_code = 2
- `specialty`: primary NUCC taxonomy specialty
- `practice_address` / `city` / `state` / `zip`: primary practice location
- `enumeration_date`: when the NPI was first issued
- `entity_type_code`: 1 (individual) or 2 (organization)
- Citation envelope (`meta.envelope_version`, `meta.source_attribution`, `meta.request`)

### What's excluded

The free tier intentionally excludes value-add fields. These require a paid plan or per-query billing:

- DSO affiliation flag and brand label
- License events feed (status changes, disciplinary actions, expiration alerts)
- License status, expiration date, disciplinary history
- HRSA HPSA shortage area cross-reference
- NPDB cross-reference
- CMS Medicare Part B billing aggregates
- Confidence scoring
- Co-located providers / practice-entity grouping
- State Medicaid fee-schedule data

### Rate limits

- 100 requests per day per source IP (rolling 24-hour window)
- 10 requests per minute per source IP (burst cap)
- Hard 429 on quota exhaustion. `Retry-After` returned in seconds.
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` returned in headers.

### Health check

`GET /api/v1/free/health` — no rate limit, validates connectivity.

Full docs: https://providersignal.com/docs/free-tier

## Agent payments via x402

### How it works

1. Agent makes a request to `https://providersignal.com/api/v1/agent/<endpoint>`
2. Server returns `402 Payment Required` with `PaymentRequirements` in the body (price, network, receiving address, asset)
3. Agent signs a payment authorization with its USDC wallet and retries the request with an `X-PAYMENT` header
4. Coinbase's x402 facilitator verifies the signature, the receiver is paid in USDC, and the API returns the response in the citation envelope

Any agent that already speaks the x402 protocol (https://x402.org) works with ProviderSignal out of the box. There is no custom payment flow.

### Network and asset

- Production: Base mainnet (chain id `eip155:8453`), Circle USDC at `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- Testnet: Base Sepolia (chain id `eip155:84532`), Circle USDC test token at `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
- Facilitator: `https://x402.org/facilitator` (testnet, no auth) or `https://api.cdp.coinbase.com/platform/v2/x402` (mainnet, requires CDP project)
- Settlement: on-chain USDC transfer to the receiving wallet. Gas is paid by the facilitator in most flows; agents only pay the per-call USDC amount.

### Status codes

- 200: payment verified, response in citation envelope
- 400: request validation failed (e.g. malformed npi)
- 402: no payment header, or payment did not satisfy the route's requirements. Body contains `PaymentRequirements`
- 404: payment verified, but the requested resource does not exist
- 429: rate limit exceeded at the sidecar (separate buckets for unpaid 402 traffic vs paid traffic)

### Pricing schedule

USDC has 6 decimals: 1 USDC = 1,000,000 atomic units. Atomic units are authoritative; USD figures are derived for display.

| Endpoint | Tier | USD | USDC atomic | Credits |
|----------|------|-----|-------------|---------|
| `/api/v1/agent/lookup-by-npi` | basic | $0.50 | 500,000 | 5 |
| `/api/v1/agent/search` | basic | $0.50 | 500,000 | 5 |
| `/api/v1/agent/dso/affiliation` | moat | $1.00 | 1,000,000 | 10 |
| `/api/v1/agent/scoring` | moat | $1.00 | 1,000,000 | 10 |
| `/api/v1/agent/license/events/historical` | moat | $1.50 | 1,500,000 | 15 |
| `/api/v1/agent/territory/rollup` | moat | $2.50 | 2,500,000 | 25 |
| `/api/v1/agent/market/positioning` | moat | $0.50 | 500,000 | 5 |
| `/api/v1/agent/medicaid/rates` | basic | $0.50 | 500,000 | 5 |
| `/api/v1/agent/medicaid/dentists` | basic | $0.50 | 500,000 | 5 |
| `/api/v1/free/lookup` | eval | free | 100/day | 0 |

Basic-tier endpoints (lookup, search) are priced near commodity because the underlying data is largely derivable from public NPI. Moat-tier endpoints (DSO inference, scoring, territory rollup, license event history) encode work that takes months to replicate from raw sources, and are priced 10-25x basic.

### Response shape (paid endpoints)

Paid endpoints return the same citation envelope as subscription endpoints. `meta.request.billing_method` is `per_query`. `meta.request.billed_credits` reports the credit weight charged.

Full docs: https://providersignal.com/docs/agent-payments

## Subscription tiers

Subscription becomes more economical above ~$30/mo of per-call spend.

Dashboard tiers (include full UI plus the API at the listed throughput):

- Rep: $149/mo or $1,290/yr (founding pricing: $79/mo for the first 25 customers, monthly billing only) — 1 seat, 500 req/min API, 5 PDF briefs/mo, CSV export
- Team: $499/mo + $79/seat over 5 — 5 seats included, 200 req/min API, shared territories, 50 briefs/mo
- Enterprise: $1,999/mo + $59/seat over 15 — 15 seats, 1,000 req/min, SSO, white-label, custom territories, exclusive Acquisition Targets dashboard (buy-side ranking by acquisition fit, contact-ready exports), exclusive NPDB Risk Trends dashboard (state-level malpractice and adverse-action trends for acquisition risk modeling)

API-only tiers (no dashboard):

- API Starter: $99/mo or $990/yr — 60 req/min, basic search endpoints
- API Pro: $299/mo or $2,990/yr — 500 req/min, all endpoints

Auth: `Authorization: Bearer ps_live_<key>`. Generate keys in dashboard Settings -> API Keys.

## Endpoint catalog (paid agent endpoints)

### /api/v1/agent/lookup-by-npi

Full provider record by NPI, including taxonomy, practice address, license metadata, and confidence score.

- Tier: basic
- Price: $0.50 (500,000 USDC atomic)
- Credits: 5
- Example input: `{"npi":"1376155820"}`

### /api/v1/agent/search

Filtered provider list with pagination. Filter on state, county, ZIP, specialty, DSO/Independent, license status, Medicaid state-roster enrollment.

- Tier: basic
- Price: $0.50 (500,000 USDC atomic)
- Credits: 5
- Example input: `{"state":"TX","per_page":25}`

### /api/v1/agent/dso/affiliation

DSO affiliation context for a single NPI: cluster size, sibling sample, parent-org / inferred-practice context.

- Tier: moat
- Price: $1.00 (1,000,000 USDC atomic)
- Credits: 10
- Example input: `{"npi":"1376155820"}`

### /api/v1/agent/scoring

Acquisition-readiness score with per-component breakdown (retirement, CMS billing, discipline, license freshness).

- Tier: moat
- Price: $1.00 (1,000,000 USDC atomic)
- Credits: 10
- Example input: `{"state":"TX","min_score":70,"per_page":25}`

### /api/v1/agent/license/events/historical

Per-NPI license event history: status changes, discipline events, board actions across the full retention window.

- Tier: moat
- Price: $1.50 (1,500,000 USDC atomic)
- Credits: 15
- Example input: `{"npi":"1376155820","limit":100}`

### /api/v1/agent/territory/rollup

Aggregate territory analysis: provider counts, DSO/Independent split, retirement-risk and CMS-billing rollups, plus a state-level Market Multiple Positioning band (Premium/Average/Discount vs the public national practice-sale benchmark) on single-state requests.

- Tier: moat
- Price: $2.50 (2,500,000 USDC atomic)
- Credits: 25
- Example input: `{"state":"TX"}`

### /api/v1/agent/market/positioning

Market Multiple Positioning band (Premium/Average/Discount) for a state or ZIP-prefix metro vs the PUBLIC national practice-sale benchmark (Levin/FOCUS/BizBuySell), with the four driving factors, a 0-100 confidence score, and a disclaimer that it is market context, not a transaction comp or practice-specific valuation. Cheaper, single-metric alternative to the positioning block embedded in the territory rollup.

- Tier: moat
- Price: $0.50 (500,000 USDC atomic)
- Credits: 5
- Example input: `{"state":"TX","zip":"770"}`

### /api/v1/agent/medicaid/rates

State Medicaid dental fee schedule: a fixed common-procedure basket (exam, cleanings, filling, crown, extraction), the state's national rank on that basket, locality structure (adult/pediatric or geographic schedules), latest effective year, and an optional raw lookup for one CDT code. Public fee-schedule amounts, not eligibility. All 50 states + DC.

- Tier: basic
- Price: $0.50 (500,000 USDC atomic)
- Credits: 5
- Example input: `{"state":"TX"}`

### /api/v1/agent/medicaid/dentists

Find dentists that take Medicaid or CHIP near a location: state-listed providers from every state's federally mandated InsureKidsNow submission (CMS-10291), including managed-care networks. Provider-location grain with participating plans aggregated, accepting-new-patient status where the state publishes it, phone, address, languages spoken and special-needs accommodation (filterable via language= and special_needs=true), and ProviderSignal's NPI resolution for chaining into lookup-by-npi. Listings are state-reported rosters, not verified acceptance. All 50 states + DC.

- Tier: basic
- Price: $0.50 (500,000 USDC atomic)
- Credits: 5
- Example input: `{"state":"TX","city":"Houston","accepting":"true"}`

## Resources

- OpenAPI 3.1 specification: https://providersignal.com/openapi.json
- Field glossary: https://providersignal.com/docs/fields
- API reference (subscription): https://providersignal.com/api-docs
- Free tier docs: https://providersignal.com/docs/free-tier
- Agent payments docs: https://providersignal.com/docs/agent-payments
- x402 protocol: https://x402.org
- Pricing: https://providersignal.com/pricing
- Privacy: https://providersignal.com/privacy
- Terms: https://providersignal.com/terms
- Contact: https://providersignal.com/contact