Outfox Health API — Price, quality & network data

Guide

What you can do

I want to…	Endpoint
Find facilities that perform a procedure near a member, sorted by price, with quality	`GET /providers/facilities`
Find doctors who perform a procedure in the member's network, with quality	`GET /providers/doctors`
Get the negotiated or cash price for a procedure at one facility	`GET /pricing/cpt/{code}`
See a facility's quality scores and outcomes by procedure	`GET /providers/facilities/{npi}`
See a doctor's quality, specialties, accepted insurance and hospital affiliations	`GET /providers/doctors/{npi}`
See which insurance networks a facility accepts	`GET /reference/insurance`

Guide

Prices: negotiated or cash

GET /providers/facilities and GET /pricing/cpt/{code} take rate_type:

negotiated (default): the carrier's contracted (negotiated) in-network rate. Choose the carrier with carrier (see Carriers below).
cash: the facility's published cash (self-pay) price. carrier is ignored. If a facility does not publish a cash price, the price is null.

Prices are the rates for the service, not what a member will pay out of pocket.

Guide

Carriers

Negotiated rates are available for these carriers. Pass the value in the carrier parameter; it is not case-sensitive. For most carriers, a plan name that contains the carrier name also works, for example Aetna Choice POS II.

Carrier	Value	Notes
Aetna	`Aetna`
Blue Cross Blue Shield	`BCBS`	Covers the state Blue plans
Cigna	`Cigna`
Harvard Pilgrim	`Harvard Pilgrim`
MedCost	`MedCost`
Sentara	`Sentara`
UnitedHealthcare	`UnitedHealthcare`	`UHC` also works
UMR	`UMR`	Exact value only

Each carrier's rates cover the areas where it operates, so a carrier can have no rates near a given ZIP. If you need a carrier that isn't listed, tell us.

Guide

Quality

Quality scores and outcome measures come from FoxIndex, Outfox's clinical-outcomes quality index. Quality comes back with providers and prices, so there is no separate quality endpoint.

Where	Fields	What it tells you
Facility search results	`quality_score`, `quality_tier`	The facility's quality score and whether it meets benchmark
Facility profile	`overall_quality_score`, `episodes[].measures`, `specialties[].specialty_score`	Overall score, outcome measures for each procedure, score for each specialty
Doctor search results	`episode_benchmark_band`, `quality_measures`	Quality for the searched procedure and its outcome measures
Doctor profile	`overall_quality_score`, `episodes[].benchmark_band`	Overall score and quality for each procedure

Scores and bands run from 1 to 5. A 3 means in line with peers, and higher is better. overall_quality_score covers everything a provider treats. For quality on one procedure, use episode_benchmark_band (doctor search) or the matching entry in episodes (profiles).

Guide

How search works

Search starts from a procedure. You pass the procedure (CPT/HCPCS codes, or a plain-language term for doctor search), the member's ZIP and the carrier. You get back providers near the member, priced and sorted by price.

The procedure shapes the search. It sets the care setting (inpatient or outpatient), how far to search, and how the price is calculated. meta shows what was used.
Search radius. It depends on the procedure and on whether the member's ZIP is urban, suburban or rural. Facilities within meta.preferred_radius_miles come before facilities further out, up to meta.radius_miles.
Order. Within each distance group, facilities are sorted by price, lowest first.
Quality bar. Providers that fall below the quality bar for the procedure are left out of search results.
Repeatable results. When you search doctors by term without codes, the codes are inferred from the term, and that can vary from call to call. Pass codes when you need the same results every time.

Guide

Conventions

Base URL: https://api.outfoxhealth.com/external/v1
Authentication: send your API key in the X-API-Key header on every request. To get a key, use the Request API access form.
Pagination: page (starts at 1) and per_page (max 100). List responses include a pagination object. Use has_more to decide whether to fetch another page, because total_items and total_pages can be estimates.
Money: USD, as a decimal number. null means unknown, not zero.
Providers are identified by NPI (National Provider Identifier).
Errors return JSON {"detail": "..."}: 400 for missing or invalid parameters, 401 for a missing or invalid API key, 404 when nothing matches the inputs.

GET/providers/facilities

Search facilities for a procedure

Facilities near the member that perform the procedure, sorted by price, with quality for each one.

Use this to answer "where can this member get this procedure, and what will it cost?" To price one facility you already know, use GET /pricing/cpt/{code}.

meta shows how the search was resolved (care setting, area type, radius, codes). A stored response stays readable later, and you can compare two searches.

Parameters

Name	In	Description
`codes` Required	query	CPT/HCPCS codes for the procedure, comma-separated, e.g. `27447` or `72141,71250`. Several codes are priced together as one procedure.Example: `27447`
`zipcode` Required	query	The member's 5-digit ZIP. Results are limited to a radius around it.Example: `75201`
`carrier`	query	Required when `rate_type=negotiated`. The carrier to price against, e.g. `Aetna`. Supported values are listed under Carriers. Ignored when `rate_type=cash`.Example: `Aetna`
`rate_type`	query	`negotiated` (default): the carrier's contracted (negotiated) in-network rate. `cash`: the facility's published cash (self-pay) price. Same search either way.Example: `negotiated`
`setting`	query	`auto` (default, determined from the procedure), `inpatient`, `outpatient` or `mixed`. Set it when you already know where the procedure will be done.Example: `auto`
`search_text`	query	Filter by facility or health-system name.
`page`	query	Page number, starting at 1.Example: `1`
`per_page`	query	Results per page (max 100).Example: `20`

Response fields: `data[]`

Field	Description
`npi`	Facility NPI
`hospital_name`, `health_system`	Facility name and parent health system (`null` if none)
`cms_facility_id`	Medicare (CMS) provider ID
`city`, `state`, `zip_code`, `phone_number`	Location and contact
`billing_code`, `billing_code_type`	The code that was priced and its type, e.g. `CPT`
`carrier`, `rate_label`	Carrier the rate belongs to, and `Negotiated Rate` or `Cash Price`
`site_of_care`	`HOPD` (hospital outpatient department), `ASC` (ambulatory surgery center) or `OFFICE`. `null` for inpatient
`has_facility_fee`	`true` when the price includes a facility fee
`episode_price`	Estimated price of the procedure at this facility, in USD, at the requested `rate_type`
`distance_miles`	Distance from the member's ZIP
`beyond_preferred_radius`	`true` when the facility is past the preferred radius. These come after closer facilities
`quality_score`	Facility quality score, 1 to 5 (3 = in line with peers). `null` if there is no data
`quality_tier`	`meets` (at or above benchmark), `below` (below benchmark) or `no_data`
`medicare_prof_benchmark`, `medicare_facility_benchmark`	Medicare professional and facility rates for the same service, for reference

Response fields: `meta`

Field	Description
`setting`	Care setting used: `inpatient`, `outpatient` or `mixed`
`urbanicity`	`urban`, `suburban` or `rural`, from the member's ZIP
`radius_miles`	Maximum search radius
`preferred_radius_miles`	Facilities within this radius come first
`codes`, `zipcode`, `carrier`	The inputs used

Example request

curl -G "https://api.outfoxhealth.com/external/v1/providers/facilities" \
  -H "X-API-Key: $OUTFOX_API_KEY" \
  --data-urlencode "codes=27447" \
  --data-urlencode "zipcode=75201" \
  --data-urlencode "carrier=Aetna" \
  --data-urlencode "rate_type=negotiated" \
  --data-urlencode "setting=auto" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=20"

Example responses

200OK

{
  "meta": {
    "setting": "outpatient",
    "urbanicity": "urban",
    "radius_miles": 45,
    "preferred_radius_miles": 30,
    "carrier": "Aetna",
    "codes": "27447",
    "zipcode": "75201"
  },
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_items": 33,
    "total_pages": 2,
    "has_more": true
  },
  "data": [
    {
      "npi": "1234567890",
      "hospital_name": "Memorial General Hospital",
      "health_system": "Memorial Health System",
      "cms_facility_id": "450123",
      "city": "Dallas",
      "state": "TX",
      "zip_code": "75201",
      "phone_number": "214-555-0100",
      "billing_code": "27447",
      "billing_code_type": "CPT",
      "carrier": "Aetna",
      "rate_label": "Negotiated Rate",
      "site_of_care": "HOPD",
      "has_facility_fee": true,
      "episode_price": 24150.0,
      "distance_miles": 4.2,
      "beyond_preferred_radius": false,
      "quality_score": 4,
      "quality_tier": "meets",
      "medicare_prof_benchmark": 1420.55,
      "medicare_facility_benchmark": 18990.0
    },
    {
      "npi": "1234567891",
      "hospital_name": "Northside Surgical Center",
      "health_system": null,
      "cms_facility_id": "450456",
      "city": "Plano",
      "state": "TX",
      "zip_code": "75024",
      "phone_number": "972-555-0144",
      "billing_code": "27447",
      "billing_code_type": "CPT",
      "carrier": "Aetna",
      "rate_label": "Negotiated Rate",
      "site_of_care": "ASC",
      "has_facility_fee": true,
      "episode_price": 26400.0,
      "distance_miles": 11.8,
      "beyond_preferred_radius": false,
      "quality_score": 4,
      "quality_tier": "meets",
      "medicare_prof_benchmark": 1420.55,
      "medicare_facility_benchmark": 18990.0
    }
  ]
}

400Bad Request

{
  "detail": "At least one CPT/HCPCS code is required."
}

404Not Found

{
  "detail": "No data found for the given inputs."
}

GET/providers/facilities/{npi}

Get a facility profile and quality

Full profile for one facility: identity, overall quality score, volume and outcome measures for each procedure, and a score for each specialty.

Parameters

Name	In	Description
`npi` Required	path	Facility NPI (National Provider Identifier).Example: `1234567890`

Response fields

Field	Description
`npi`, `name`, `health_system_name`, `hospital_type`	Identity
`city`, `state`, `zip`, `phone`	Location and contact
`overall_quality_score`	1 to 5 across everything the facility treats (3 = in line with peers)
`episodes[]`	One entry per procedure: `episode_name`, `episode_count` (volume) and outcome `measures` (`measure_name`, `measure_score`, `measure_description`)
`specialties[]`	One entry per specialty: `specialty_name`, `specialty_score` (1 to 5) and `episode_count`

Example request

curl "https://api.outfoxhealth.com/external/v1/providers/facilities/1234567890" \
  -H "X-API-Key: $OUTFOX_API_KEY"

Example responses

200OK

{
  "npi": "1234567890",
  "name": "Memorial General Hospital",
  "health_system_name": "Memorial Health System",
  "hospital_type": "Acute Care",
  "city": "Dallas",
  "state": "TX",
  "zip": "75201",
  "phone": "214-555-0100",
  "overall_quality_score": 4,
  "episodes": [
    {
      "episode_name": "Knee Replacement",
      "episode_count": 142,
      "measures": [
        {
          "measure_name": "Unplanned Readmissions",
          "measure_score": 3.2,
          "measure_description": "In line with peers"
        }
      ]
    }
  ],
  "specialties": [
    {
      "specialty_name": "Orthopedics",
      "specialty_score": 4.1,
      "episode_count": 320
    }
  ]
}

404Not Found

{
  "detail": "Facility not found"
}

GET/providers/doctors

Search doctors for a procedure

Doctors near the member who perform the procedure and are in the member's network, with their quality for that procedure.

Each doctor is paired with the facility where they would perform the procedure (facility_* fields), so you can show the doctor and the price together. Doctors are ordered by the price at that facility.

Describe the procedure with codes (CPT/HCPCS) or term (plain language). If you pass neither, typical procedures for the specialty are used.

Parameters

Name	In	Description
`specialty` Required	query	Doctor specialty, e.g. `Orthopedic Surgery`. Only doctors with this specialty are returned.Example: `Orthopedic Surgery`
`zipcode` Required	query	The member's 5-digit ZIP.Example: `75201`
`carrier` Required	query	Insurance carrier or plan name, e.g. `Aetna`. Supported values are listed under Carriers.Example: `Aetna`
`term`	query	The procedure in plain language, e.g. `knee replacement`. Used to find the procedure codes when `codes` is not set.Example: `knee replacement`
`codes`	query	CPT/HCPCS codes for the procedure, comma-separated. Takes priority over `term`. Pass `codes` when you need the same results on every call.Example: `27447`
`doctor_name`	query	Filter by doctor name.
`insurance_accepted`	query	When `true`, only return doctors confirmed to accept the carrier's plan.Example: `false`
`page`	query	Page number, starting at 1.Example: `1`
`per_page`	query	Results per page (max 100).Example: `20`

Response fields: `data[]`

Field	Description
`npi`, `name`, `specialties`	Identity
`address`, `phone_number`	Practice location and contact
`insurance_plan`	Plan matched for the searched carrier
`language`, `doctor_education`, `image`	Languages spoken, medical school, photo URL
`facility_npi`, `facility_name`	Facility the doctor is matched to for this procedure
`facility_match`	`confirmed` (the doctor is confirmed to practice there), `unconfirmed` (linked, not confirmed) or `none`
`facility_episode_price`	Estimated price of the procedure at that facility, in USD
`facility_distance_miles`	Distance from the member's ZIP to that facility
`episode_name`, `episode_type`, `episode_count`	The procedure, and how many of them the doctor has performed
`episode_benchmark_band`	The doctor's quality for this procedure, 1 to 5 (3 = in line with peers)
`quality_measures[]`	Outcome measures compared with peers

Response fields: `meta`

Field	Description
`specialty`, `term`, `codes`, `carrier`, `zipcode`	The inputs used. If you did not pass `codes`, `codes` shows the codes that were inferred
`urbanicity`, `radius_miles`, `preferred_radius_miles`	Same as facility search
`procedure_match`	`exact`: doctors who perform this procedure. `region`: there were no exact matches, so these doctors perform related procedures on the same body region. `none`: no procedure filter was applied

Example request

curl -G "https://api.outfoxhealth.com/external/v1/providers/doctors" \
  -H "X-API-Key: $OUTFOX_API_KEY" \
  --data-urlencode "specialty=Orthopedic Surgery" \
  --data-urlencode "zipcode=75201" \
  --data-urlencode "carrier=Aetna" \
  --data-urlencode "term=knee replacement" \
  --data-urlencode "codes=27447" \
  --data-urlencode "insurance_accepted=false" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=20"

Example responses

200OK

{
  "meta": {
    "specialty": "Orthopedic Surgery",
    "term": "knee replacement",
    "codes": "27447",
    "carrier": "Aetna",
    "zipcode": "75201",
    "urbanicity": "urban",
    "radius_miles": 45,
    "preferred_radius_miles": 30,
    "procedure_match": "exact"
  },
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_items": 22,
    "total_pages": 2,
    "has_more": true
  },
  "data": [
    {
      "npi": "1987654321",
      "name": "Jane Smith, MD",
      "specialties": [
        "Orthopedic Surgery",
        "Sports Medicine"
      ],
      "address": "123 Main St, Dallas, TX 75201",
      "phone_number": "214-555-0111",
      "insurance_plan": "Aetna Choice POS II",
      "language": [
        "English",
        "Spanish"
      ],
      "doctor_education": "UT Southwestern Medical School",
      "image": "https://cdn.outfoxhealth.com/providers/1987654321.jpg",
      "facility_npi": "1234567890",
      "facility_name": "Memorial General Hospital",
      "facility_match": "confirmed",
      "facility_episode_price": 24150.0,
      "facility_distance_miles": 4.2,
      "episode_name": "Knee Replacement",
      "episode_type": "procedure",
      "episode_count": 86,
      "episode_benchmark_band": 4,
      "quality_measures": [
        {
          "measure": "Complication rate",
          "description": "Better than peers"
        }
      ]
    }
  ]
}

404Not Found

{
  "detail": "No doctors found for the given inputs."
}

GET/providers/doctors/{npi}

Get a doctor profile and quality

Full profile for one doctor: identity, specialties, education, languages, accepted insurance, hospital affiliations and quality for each procedure.

overall_quality_score covers everything the doctor treats. For quality on one procedure, use episodes[].benchmark_band here, or episode_benchmark_band from doctor search.

Parameters

Name	In	Description
`npi` Required	path	Doctor NPI (National Provider Identifier).Example: `1987654321`

Response fields

Field	Description
`npi`, `name`, `specialties`, `education`, `languages`	Identity
`address`, `phone`	Practice location and contact
`insurance_accepted`	Networks and plans the doctor accepts
`accepting_new_patients`	Whether the doctor is taking new patients
`overall_quality_score`	1 to 5 across everything the doctor treats (3 = in line with peers)
`quality_scope`	`overall`: the scope of `overall_quality_score`
`hospital_affiliations[]`	Facilities the doctor is affiliated with (`npi`, `name`)
`episodes[]`	One entry per procedure: `episode_name`, `episode_count` (volume) and `benchmark_band` (quality, 1 to 5)

Example request

curl "https://api.outfoxhealth.com/external/v1/providers/doctors/1987654321" \
  -H "X-API-Key: $OUTFOX_API_KEY"

Example responses

200OK

{
  "npi": "1987654321",
  "name": "Jane Smith, MD",
  "specialties": [
    "Orthopedic Surgery",
    "Sports Medicine"
  ],
  "address": "123 Main St, Dallas, TX 75201",
  "phone": "214-555-0111",
  "insurance_accepted": [
    "Aetna PPO",
    "MedCost"
  ],
  "accepting_new_patients": true,
  "languages": [
    "English",
    "Spanish"
  ],
  "education": "UT Southwestern Medical School",
  "overall_quality_score": 4,
  "quality_scope": "overall",
  "hospital_affiliations": [
    {
      "npi": "1234567890",
      "name": "Memorial General Hospital"
    }
  ],
  "episodes": [
    {
      "episode_name": "Knee Replacement",
      "episode_count": 86,
      "benchmark_band": 4
    }
  ]
}

404Not Found

{
  "detail": "Doctor not found"
}

GET/pricing/cpt/{code}

Get the price of a procedure at one facility

The price of one procedure code at one facility, for one rate type. rate_type=negotiated returns the carrier's in-network rate. rate_type=cash returns the facility's published cash price.

This is a direct lookup for one facility, with no distance or quality filter. To find what a procedure costs near a member, use GET /providers/facilities.

Parameters

Name	In	Description
`code` Required	path	CPT/HCPCS code.Example: `27447`
`npi` Required	query	Facility NPI.Example: `1234567890`
`carrier`	query	Required when `rate_type=negotiated`. The carrier for the negotiated rate, e.g. `Aetna`. Supported values are listed under Carriers. Ignored when `rate_type=cash`.Example: `Aetna`
`rate_type`	query	`negotiated` (default): the carrier's contracted (negotiated) in-network rate. `cash`: the facility's published cash (self-pay) price.Example: `negotiated`
`setting`	query	`auto` (default, determined from the procedure), `inpatient`, `outpatient` or `mixed`. Set it when you already know where the procedure will be done.Example: `auto`

Response fields

Field	Description
`cpt_code`, `description`, `billing_code_type`	The code and what it is
`npi`, `facility_name`	The facility
`carrier`, `plan_name`	Carrier and plan of the negotiated rate (negotiated only)
`rate_type`, `rate_label`	`negotiated` / `Negotiated Rate`, or `cash` / `Cash Price`
`setting`	Care setting used
`negotiated_rate`	Negotiated rate in USD (`rate_type=negotiated`)
`cash_price`	Cash price in USD (`rate_type=cash`). `null` if the facility does not publish one
`billing_basis`	Whether the rate is the facility fee (`institutional`) or the doctor's fee (`professional`)
`professional_component`	The doctor's fee, in USD
`institutional_low`, `institutional_high`	Lowest and highest facility rate on file for this code, in USD
`medicare_facility_benchmark`	Medicare facility rate for the same service, for reference

Example request

curl -G "https://api.outfoxhealth.com/external/v1/pricing/cpt/27447" \
  -H "X-API-Key: $OUTFOX_API_KEY" \
  --data-urlencode "npi=1234567890" \
  --data-urlencode "carrier=Aetna" \
  --data-urlencode "rate_type=negotiated" \
  --data-urlencode "setting=auto"

Example responses

200OK

{
  "cpt_code": "27447",
  "description": "Total knee arthroplasty",
  "billing_code_type": "CPT",
  "npi": "1234567890",
  "facility_name": "Memorial General Hospital",
  "carrier": "Aetna",
  "plan_name": "Aetna Choice POS II",
  "rate_type": "negotiated",
  "rate_label": "Negotiated Rate",
  "setting": "outpatient",
  "negotiated_rate": 24150.0,
  "billing_basis": "institutional",
  "professional_component": 1420.55,
  "institutional_low": 21900.0,
  "institutional_high": 28400.0,
  "medicare_facility_benchmark": 18990.0
}

200OK (rate_type=cash)

{
  "cpt_code": "27447",
  "description": "Total knee arthroplasty",
  "npi": "1234567890",
  "facility_name": "Memorial General Hospital",
  "rate_type": "cash",
  "rate_label": "Cash Price",
  "setting": "outpatient",
  "cash_price": 18750.0
}

404Not Found

{
  "detail": "No pricing found for this code / facility / carrier."
}

GET/reference/insurance

List insurance networks a facility accepts

Insurance networks and plans on file for a facility. Use an insurance_net value as the carrier parameter in the other endpoints.

Parameters

Name	In	Description
`npi` Required	query	Facility NPI.Example: `1234567890`

Response fields

Field	Description
`npi`	Facility NPI
`networks[]`	`insurance_net` (network or carrier name) and `insurance_plan` (plan name)

Example request

curl -G "https://api.outfoxhealth.com/external/v1/reference/insurance" \
  -H "X-API-Key: $OUTFOX_API_KEY" \
  --data-urlencode "npi=1234567890"

Example responses

200OK

{
  "npi": "1234567890",
  "networks": [
    {
      "insurance_net": "Aetna PPO",
      "insurance_plan": "Aetna Choice POS II"
    },
    {
      "insurance_net": "MedCost",
      "insurance_plan": "MedCost Network"
    }
  ]
}

Feedback

Tell us what you need

This is a first version, and we want to shape it around how you will use it:

Do you need the searches (/providers/facilities, /providers/doctors), the single-facility price lookup (/pricing/cpt/{code}), or both?
Which carriers and networks do you need?
When you pass several CPT codes in one call, they are priced as one procedure. Do you also need each code priced separately?
Will you send CPT codes directly, or would a lookup from procedure name to codes help?

Parameters

Response fields: data[]

Response fields: meta

Example request

Example responses

Parameters

Response fields

Example request

Example responses

Parameters

Response fields: data[]

Response fields: meta

Example request

Example responses

Parameters

Response fields

Example request

Example responses

Parameters

Response fields

Example request

Example responses

Parameters

Response fields

Example request

Example responses

Response fields: `data[]`

Response fields: `meta`

Response fields: `data[]`

Response fields: `meta`