← Guides

Check coverage before you query

Try it on a test key

curl -s "https://api.wellwardhealth.com/v1/coverage?near=00020" -H "Authorization: Bearer $WELLWARD_KEY"

The pattern that makes the fewest billed calls and the fewest dead ends:

coverage → prices → request

1. Ask what we have. GET /v1/coverage?near=<zip> is free (never a Read) and has its own rate limit. For each service that has prices nearby it returns price_count, provider_count and coverage: full (at least 5 prices from at least 4 practices) or partial (at least one). A service with nothing nearby is left out, so compare against GET /v1/services: anything missing from coverage is none. It never returns prices, practices or dates.
2. Fetch prices where there are some. GET /v1/prices?service=<slug>&near=<zip> for services with full or partial coverage. Each call that returns prices is one Read.
3. Ask us to gather where there are none. POST /v1/price-requests for a none (or thin partial) service. We contact providers; you hear back by webhook (request.completed) or by polling. You pay only if we obtain a price.

const H = { Authorization: `Bearer ${process.env.WELLWARD_KEY}` };
const base = "https://api.wellwardhealth.com/v1";

const catalog = await (await fetch(`${base}/services`, { headers: H })).json();
const cov = await (await fetch(`${base}/coverage?near=00020`, { headers: H })).json();
const covered = new Map(cov.data.services.map((s) => [s.service, s]));

for (const svc of catalog.data) {
  if (covered.has(svc.slug)) {
    const prices = await (await fetch(`${base}/prices?service=${svc.slug}&near=00020`, { headers: H })).json();
    // …show prices.data.prices
  } else {
    // Nothing nearby: offer to ask for it, e.g.
    // POST /v1/price-requests with { service: svc.slug, zip: "00020" } and an Idempotency-Key.
  }
}

Why not just call /v1/prices? An empty /v1/prices result is free too, and returns service_coverage: { level: "none" } with a link to request gathering — so nothing is lost. But /v1/coverage answers for every priced service in one call, which is what you want when building a menu.

A request where coverage is already full is refused with 409 coverage_exists — we already have the prices. If you need fresher quotes, send max_age_days (at least 30) and we will gather anyway.

Idempotency-Key is required on POST /v1/price-requests. Send a fresh unique value per request; for 24 hours, a retry with the same key and body returns the original successful response instead of creating a second request, and the same key with a different body gets 409 idempotency_conflict.

API reference · Dashboard · Questions: hello@wellwardhealth.com