{"openapi":"3.0.0","info":{"title":"PayerPrice API Documentation","version":"1.0","description":"PayerPrice's healthcare price transparency APIs give you access to negotiated rates, provider information, and market benchmarks across the United States. Use them to power reimbursement analytics, build provider directories, and retrieve fee schedules.\n\n## Start here\n\n1. [Log in](https://app.payerprice.com/app/login?utm_source=api_docs&utm_medium=referral&utm_campaign=login&redirectTo=%2Fapi%2Fdoc) or [sign up](https://app.payerprice.com/app/sign-up?utm_source=api_docs&utm_medium=referral&utm_campaign=signup&redirectTo=%2Fapi%2Fdoc) to get an API key. Then find it under [**Your API Keys**](/api/doc#description/your-api-keys).\n2. Make a first request to list available payers and data periods:\n\n```bash\ncurl https://api.payerprice.com/api/v1/payers \\\n  -H 'Authorization: Bearer YOUR_API_KEY'\n```\n\n3. The response is an array of objects with a `payer` name and `yearMonths` entries. Use a returned payer and period when building a pricing request. [See the payer endpoint](/api/doc#tag/payer-apis/GET/api/v1/payers).\n4. Next, [get market benchmarks](/api/doc#tag/pricing-apis/POST/api/v1/market/benchmarks) for a comparable market or [get provider rates](/api/doc#tag/pricing-apis/POST/api/v1/provider/rates) for a specific NPI, TIN, or CCN.\n\nRequests made with an API key can consume credits. Check the credit balance and [usage dashboard](https://app.payerprice.com/app/profile?tab=api-usage) before choosing **Test Request**. Test requests are sent only when you click that button.\n\n## Integration essentials\n\n- Send `Authorization: Bearer YOUR_API_KEY` over HTTPS. A missing or invalid key returns `401`; a forbidden request returns `403`.\n- Invalid filters can return `400`. Insufficient API credit returns `402`. Rate limiting returns `429`; back off before retrying. Retry reads after transient failures, but do not blindly repeat create, update, or delete requests.\n- Pagination and asynchronous processing vary by endpoint. Follow each operation's request and response fields. Report creation can finish after the initial request; use its documented status and data-retrieval workflow.\n- API paths use `/api/v1`. The OpenAPI version describes this contract; payer `yearMonths` describe available source-data periods. These are separate versions.\n\n## OpenAPI specification\n\n[Download the OpenAPI specification](/api/doc/openapi.json) using a signed-in browser session or an `Authorization: Bearer YOUR_API_KEY` header. Credentials are never embedded in the response. [Read Markdown docs](/api/doc.md) or [the API index for agents](/llms.txt).\n\n---\n\n## Your API Keys\n\n❌ You're not logged in. <a href=\"https://app.payerprice.com/app/login?utm_source=api_docs&utm_medium=referral&utm_campaign=login&redirectTo=%2Fapi%2Fdoc\" target=\"_blank\" rel=\"noopener noreferrer\">Log in</a> to view your API keys, or <a href=\"https://app.payerprice.com/app/sign-up?utm_source=api_docs&utm_medium=referral&utm_campaign=signup&redirectTo=%2Fapi%2Fdoc\" target=\"_blank\" rel=\"noopener noreferrer\">sign up</a> to get 5 free API calls.\n\n---\n\n## MCP Server\n\nThe Model Context Protocol (MCP) server lets compatible AI models and agents query PayerPrice data through a standardized interface.\n\n[Read the MCP documentation](/mcp/doc) for setup instructions and available tools."},"components":{"securitySchemes":{"APIKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Pass your API key in the `Authorization` header as a Bearer token. Example: `Authorization: Bearer YOUR_API_KEY`."}},"schemas":{"ReportDataFilterGroup":{"type":"object","description":"A recursive filter group. `op` combines every entry in `filters` with AND or OR. Each entry is either a comparison filter or another group, so groups can be nested. An empty `filters` array applies no filter.","required":["op","filters"],"properties":{"op":{"type":"string","enum":["AND","OR"],"description":"Logical operator joining this group's filters."},"filters":{"type":"array","description":"Comparison filters or nested filter groups.","items":{"oneOf":[{"$ref":"#/components/schemas/ReportDataSingleFilter"},{"$ref":"#/components/schemas/ReportDataFilterGroup"}]}}}},"ReportDataSingleFilter":{"type":"object","description":"One comparison against a report column. Supply `value` for comparisons; omit it for `IS_NULL` and `IS_NOT_NULL`. Filter fields need not appear in `getRawData.columnAggregations` but must be available on the report.","required":["op","field"],"properties":{"op":{"type":"string","enum":["EQUAL","NOT_EQUAL","GREATER_THAN","LESS_THAN","GREATER_THAN_OR_EQUAL","LESS_THAN_OR_EQUAL","IS_NULL","IS_NOT_NULL","CONTAINS","NOT_CONTAINS","MATCH_WORDS"],"description":"Comparison operator. `EQUAL`/`NOT_EQUAL` test equality, `GREATER_THAN`/`LESS_THAN` and their `_OR_EQUAL` variants compare ordered values, `IS_NULL`/`IS_NOT_NULL` test nulls, and `CONTAINS`/`NOT_CONTAINS`/`MATCH_WORDS` perform text matching."},"field":{"type":"string","description":"Report column name to filter, such as `payer` or `service_codes`."},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"Comparison value. Use a string, number, or boolean matching the column's value type. Omit for null checks; arrays and null are not accepted."}}},"ContractModelTin":{"type":"object","required":["value"],"properties":{"value":{"type":"integer","minimum":0,"maximum":9999999999,"description":"TIN value normalized from 8- to 10-digit pasted input. Formatting characters and leading zeroes are removed."},"title":{"type":"string","maxLength":500,"description":"Optional display label. When omitted, the API uses the numeric TIN as the title."},"grouping":{"type":"string","nullable":true,"maxLength":500,"description":"Optional display grouping. When omitted, the API stores null."},"score":{"type":"number","nullable":true,"description":"Optional autocomplete relevance score."}}},"ContractModelRateAggregation":{"type":"string","enum":["max","median","avg","min","modal"],"description":"Allowlisted aggregation used to combine negotiated rates within a Contract Model rate column."},"ContractModelCompetitorColumn":{"type":"object","required":["id","label","tins","aggregation"],"properties":{"id":{"type":"string","pattern":"^[a-z0-9]{8,64}$","description":"Stable lowercase alphanumeric column ID used by `baselineBenchmark` and manual-rate keys."},"label":{"type":"string","minLength":1,"maxLength":500},"tins":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/ContractModelTin"},"description":"Unique TINs whose rates are combined into this competitor column."},"aggregation":{"$ref":"#/components/schemas/ContractModelRateAggregation"}},"additionalProperties":false},"ContractModelMixEntry":{"type":"object","required":["key","percentOfBusiness"],"properties":{"key":{"type":"string"},"percentOfBusiness":{"type":"number"}},"additionalProperties":false},"SavedContractModelConfig":{"type":"object","description":"Saved state for the Contract Modeling report tab. Every property is optional; omitted values use the client defaults. The serialized configuration is limited to 250,000 characters.","properties":{"tabType":{"type":"string","enum":["interactiveChart","summaryPivot","percentile","sample","fullData","rateChange","weightedContract","dummyClaims","modelContract"]},"isBestRateChosen":{"type":"boolean"},"isOutlierRemoved":{"type":"boolean"},"dropdownFilters":{"type":"object","description":"Saved dropdown filter tree using the standard report FilterGroup operators."},"tableFilters":{"type":"object","description":"Saved fuzzy table-filter tree."},"sorts":{"type":"array","items":{"type":"object","required":["id","desc"],"properties":{"id":{"type":"string"},"desc":{"type":"boolean"}},"additionalProperties":false}},"yourTins":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/ContractModelTin"}},"competitorColumns":{"type":"array","maxItems":8,"items":{"$ref":"#/components/schemas/ContractModelCompetitorColumn"}},"payerMix":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/ContractModelMixEntry"}},"billingCodeMix":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/ContractModelMixEntry"}},"totalAnnualRevenue":{"type":"string","maxLength":64},"baselineBenchmark":{"type":"string","default":"p75","example":"competitor_example1","description":"Target scenario used to calculate the modeled opportunity. Use `p50`, `p75`, or `p90` for the 50th-, 75th-, or 90th-percentile market rate. To target a selected competitor column, use `competitor_<columnId>`, where `<columnId>` is the `id` of an entry in `competitorColumns`; for example, `competitor_example1`. The client falls back to `p75` when the saved value is missing or no longer matches an available target."},"baselineColumn":{"type":"string","default":"negotiated_rate","example":"negotiated_rate","description":"Column treated as Your Rate when comparing against `baselineBenchmark`. Use `negotiated_rate` (the public/default value) to calculate Your Rate from `yourTins`. A saved dynamic dollar-rate column's exact `accessorKey` can also be used when that column exists in the same saved configuration; dynamic-column configuration is not part of the currently documented public schema. If the requested column is unavailable, the client prefers `negotiated_rate`, then the first eligible rate column."},"compareColorsEnabled":{"type":"boolean"},"manualRates":{"type":"object","maxProperties":10000,"additionalProperties":{"type":"number"},"description":"Manual rate overrides keyed by the serialized Contract Model column and row identity."}},"additionalProperties":false},"ReportActionRequest":{"type":"object","minProperties":1,"properties":{"archiveAction":{"type":"object","required":["event"],"properties":{"event":{"type":"string","enum":["Archive","Unarchive"],"description":"Archive hides a report from active lists; Unarchive restores it."}},"additionalProperties":false},"deleteAction":{"type":"object","required":["event"],"properties":{"event":{"type":"string","enum":["Delete"],"description":"Soft-deletes the report so it no longer appears in report lists."}},"additionalProperties":false},"contractModelConfigAction":{"type":"object","required":["config"],"properties":{"config":{"$ref":"#/components/schemas/SavedContractModelConfig"}},"additionalProperties":false}},"additionalProperties":false},"ContractManagementEntityEditError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["admin_required","edit_already_applied","entity_id_conflict","entity_not_found","extraction_in_progress","extraction_unavailable","invalid_operation","invalid_request","invalid_value","pricing_not_editable","request_id_reused","required_value","stale_revision","unsupported_target"]},"message":{"type":"string"},"operationIndex":{"type":"integer","minimum":0,"description":"Zero-based index of the invalid operation when the request shape was parseable."}}},"ContractManagementEntityEditResponse":{"type":"object","additionalProperties":false,"required":["id","revision","resolvedEntities"],"properties":{"id":{"type":"string","format":"uuid"},"revision":{"type":"integer","minimum":1},"resolvedEntities":{"type":"object","additionalProperties":true,"description":"Complete schema-v2 resolved contract entities after this edit batch."}}},"ContractManagementEntityEditOperation":{"type":"object","additionalProperties":false,"required":["operation","entityId","fieldPath"],"properties":{"operation":{"type":"string","enum":["set","delete","remove_entity","append_entity"]},"entityId":{"type":"string","description":"Stable entity ID from the resolved document, or `root` for a root field or collection."},"fieldPath":{"type":"string","description":"Allowlisted field or collection path selected by the operation variant."},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"object","additionalProperties":true}],"description":"Required for set and append_entity. Append values must be a canonical named-party, named-scope, location, contract-clause, or non-pricing payment-policy entity."}},"oneOf":[{"title":"Set an attribute value","required":["value"],"properties":{"operation":{"enum":["set"]},"fieldPath":{"enum":["payerpricePayer","name","value","address","city","state","postalCode","normalizedValue","rawText","contractTerms.signedDate","contractTerms.effectivePeriod.start","contractTerms.effectivePeriod.end","contractTerms.executionStatus"]},"value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}},{"title":"Delete an attribute value","properties":{"operation":{"enum":["delete"]},"fieldPath":{"enum":["payerpricePayer","name","value","address","city","state","postalCode","normalizedValue","rawText","contractTerms.signedDate","contractTerms.effectivePeriod.start","contractTerms.effectivePeriod.end","contractTerms.executionStatus"]}}},{"title":"Remove an entity","properties":{"operation":{"enum":["remove_entity"]},"entityId":{"type":"string","description":"Stable ID of an existing non-pricing entity; `root` is invalid."},"fieldPath":{"enum":[""]}}},{"title":"Append an entity","required":["value"],"properties":{"operation":{"enum":["append_entity"]},"entityId":{"enum":["root"]},"fieldPath":{"enum":["parties.payers","parties.administrators","parties.providers","parties.contractingEntities","contractScope.linesOfBusiness","contractScope.plans","contractScope.products","contractScope.networks","contractScope.states","contractScope.benefitChannels","providerContext.specialties","providerContext.taxonomies","providerContext.tins","providerContext.npis","providerContext.ccns","providerContext.locations","contractTerms.clauses","paymentPolicies"]},"value":{"description":"Canonical entity object for the selected collection, including a stable unique `id`. Pricing policies and reimbursement clauses are rejected.","oneOf":[{"title":"Named party","type":"object","additionalProperties":false,"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"normalizedName":{"type":"string"},"payerpricePayer":{"type":"string"},"evidenceIds":{"type":"array","items":{"type":"string"}}}},{"title":"Named scope value","type":"object","additionalProperties":false,"required":["id","value"],"properties":{"id":{"type":"string"},"value":{"type":"string"},"normalizedValue":{"type":"string"},"evidenceIds":{"type":"array","items":{"type":"string"}}}},{"title":"Provider location","type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string"},"address":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"evidenceIds":{"type":"array","items":{"type":"string"}}}},{"title":"Contract clause","type":"object","additionalProperties":false,"required":["id","clauseType","category","value","evidenceIds"],"properties":{"id":{"type":"string"},"clauseType":{"type":"string","description":"Reimbursement-rule and lesser-of clause types are rejected in v1."},"category":{"type":"string","enum":["renewal","termination","claims_submission","payment_timing","appeal","recoupment","audit","authorization","referral","confidentiality","privacy","insurance","assignment","participation","network","policy","payment_responsibility","patient_protection","continuity_of_care","delegation","other"]},"value":{"type":"string"},"normalizedValue":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"applicability":{"type":"object","additionalProperties":true},"effectivePeriod":{"type":"object","additionalProperties":true},"evidenceIds":{"type":"array","items":{"type":"string"}}}},{"title":"Non-pricing payment policy","type":"object","additionalProperties":false,"required":["id","category","policyType","applicability","rawText","evidenceIds"],"properties":{"id":{"type":"string"},"category":{"type":"string","enum":["authorization","billing","claims_administration","coverage","other"],"description":"`pricing_adjustment` is intentionally excluded in v1."},"policyType":{"type":"string"},"applicability":{"type":"object","additionalProperties":true},"condition":{"type":"object","additionalProperties":true},"effect":{"type":"object","additionalProperties":true,"description":"Effects containing pricing are rejected in v1."},"effectivePeriod":{"type":"object","additionalProperties":true},"sequence":{"type":"integer"},"stacksWithPolicyIds":{"type":"array","items":{"type":"string"}},"rawText":{"type":"string"},"evidenceIds":{"type":"array","items":{"type":"string"}}}}]}}}]},"Payer":{"type":"string","enum":["BCBS","United","Aetna","Cigna","FirstHealth","BannerHealth","MeritainHealth","Centene","Fidelis","Ambetter","QualChoice","HealthNet","ManagedHealthNetwork","WellCare","DeanHealthPlan","Prevea360","TripleSSalud","AlliantHealthPlans","AmeriHealth","AveraHealthPlans","BaylorScottWhiteHealthPlan","CareSource","CommunityCareOklahoma","PriorityHealth","TuftsHealthPlan","MVPHealthCare","HarvardPilgrimHealthCare","HealthAlliance","HealthAllianceHAP","HealthFirst","HealthLink","HealthNewEngland","HealthPartners","HealthSmart","HometownHealth","IndependentHealthAssociation","InterWestHealth","JohnsHopkinsHealthPlans","KaiserPermanente","LyraHealth","LuminareHealth","MagnaCare","MassGeneralBrigham","Medica","MedicalMutual","MidlandsChoice","ModaHealth","Molina","MultiPlan","NeighborhoodHealthPlanOfRhodeIsland","OSUHealthPlan","OptimaHealth","Oscar","PacificSource","PhysiciansHealthPlan","PresbyterianHealthPlan","ProvidenceHealthPlan","Quartz","SanfordHealthPlan","SelectHealth","TexasChildrensHealthPlan","TheAlliance","TrilogyHealthSolutions","UCare","UHAHealthInsurance","UPMCHealthPlan"],"description":"Insurance payer identifier"},"State":{"type":"string","enum":["AL","AK","AZ","AR","CA","CO","CT","DE","FL","GA","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VT","VA","WA","WV","WI","WY"],"description":"Two-letter US state code."},"TaxonomyCode":{"type":"string","enum":["193200000X","193400000X","207K00000X","207KA0200X","207KI0005X","207L00000X","207LA0401X","207LC0200X","207LH0002X","207LP2900X","207LP3000X","208U00000X","208C00000X","207N00000X","207NI0002X","207ND0900X","207ND0101X","207NP0225X","207NS0135X","204R00000X","207P00000X","207PE0004X","207PH0002X","207PT0002X","207PP0204X","207PS0010X","207PE0005X","207Q00000X","207QA0401X","207QA0000X","207QA0505X","207QG0300X","207QH0002X","207QB0002X","207QS1201X","207QS0010X","208D00000X","208M00000X","202C00000X","202D00000X","207R00000X","207RA0401X","207RA0000X","207RA0002X","207RA0001X","207RA0201X","207RC0000X","207RI0001X","207RC0001X","207RC0200X","207RE0101X","207RG0100X","207RG0300X","207RH0000X","207RH0003X","207RI0008X","207RH0002X","207RH0005X","207RI0200X","207RI0011X","207RM1200X","207RX0202X","207RN0300X","207RB0002X","207RP1001X","207RR0500X","207RS0012X","207RS0010X","207RT0003X","209800000X","207SG0202X","207SC0300X","207SG0201X","207SG0203X","207SM0001X","207SG0205X","207T00000X","204D00000X","204C00000X","207U00000X","207UN0903X","207UN0901X","207UN0902X","207V00000X","207VC0300X","207VC0200X","207VF0040X","207VX0201X","207VG0400X","207VH0002X","207VM0101X","207VB0002X","207VX0000X","207VE0102X","207W00000X","207WX0120X","207WX0009X","207WX0109X","207WX0200X","207WX0110X","207WX0107X","207WX0108X","204E00000X","207X00000X","207XS0114X","207XX0004X","207XS0106X","207XS0117X","207XX0801X","207XP3100X","207XX0005X","207Y00000X","207YS0123X","207YX0602X","207YX0905X","207YX0901X","207YP0228X","207YX0007X","207YS0012X","208VP0014X","208VP0000X","207ZP0101X","207ZP0102X","207ZB0001X","207ZP0104X","207ZC0008X","207ZC0006X","207ZP0105X","207ZC0500X","207ZD0900X","207ZF0201X","207ZH0000X","207ZI0100X","207ZM0300X","207ZP0007X","207ZN0500X","207ZP0213X","208000000X","2080A0000X","2080C0008X","2080I0007X","2080P0006X","2080H0002X","2080T0002X","2080N0001X","2080P0008X","2080B0002X","2080P0201X","2080P0202X","2080P0203X","2080P0204X","2080P0205X","2080P0206X","2080P0207X","2080P0208X","2080P0210X","2080P0214X","2080P0216X","2080T0004X","2080S0012X","2080S0010X","202K00000X","208100000X","2081P0301X","2081H0002X","2081N0008X","2081P2900X","2081P0010X","2081P0004X","2081S0010X","208200000X","2082S0099X","2082S0105X","2083A0300X","2083A0100X","2083C0008X","2083T0002X","2083B0002X","2083X0100X","2083P0500X","2083P0901X","2083S0010X","2083P0011X","2084A0401X","2084P0802X","2084B0040X","2084P0301X","2084P0804X","2084N0600X","2084D0003X","2084E0001X","2084F0202X","2084P0805X","2084H0002X","2084A2900X","2084P0005X","2084N0400X","2084N0402X","2084N0008X","2084B0002X","2084P2900X","2084P0800X","2084P0015X","2084S0012X","2084S0010X","2084V0102X","2085B0100X","2085D0003X","2085R0202X","2085U0001X","2085H0002X","2085N0700X","2085N0904X","2085P0229X","2085R0001X","2085R0205X","2085R0203X","2085R0204X","208600000X","2086H0002X","2086S0120X","2086S0122X","2086S0105X","2086S0102X","2086X0206X","2086S0127X","2086S0129X","208G00000X","204F00000X","208800000X","2088F0040X","2088P0231X","106E00000X","106S00000X","103K00000X","103G00000X","103GC0700X","101Y00000X","101YA0400X","101YM0800X","101YP1600X","101YP2500X","101YS0200X","101200000X","106H00000X","102X00000X","102L00000X","103T00000X","103TA0400X","103TA0700X","103TC0700X","103TC2200X","103TB0200X","103TC1900X","103TE1000X","103TE1100X","103TF0000X","103TF0200X","103TP2701X","103TH0004X","103TH0100X","103TM1700X","103TM1800X","103TP0016X","103TP0814X","103TP2700X","103TR0400X","103TS0200X","103TW0100X","104100000X","1041C0700X","1041S0200X","111N00000X","111NI0013X","111NI0900X","111NN0400X","111NN1001X","111NX0100X","111NX0800X","111NP0017X","111NR0200X","111NR0400X","111NS0005X","111NT0100X","125K00000X","126800000X","124Q00000X","126900000X","125J00000X","122300000X","1223D0001X","1223D0004X","1223E0200X","1223G0001X","1223P0106X","1223X0008X","1223S0112X","1223X2210X","1223X0400X","1223P0221X","1223P0300X","1223P0700X","122400000X","125Q00000X","132700000X","136A00000X","133V00000X","133VN1101X","133VN1006X","133VN1201X","133VN1301X","133VN1004X","133VN1401X","133VN1005X","133VN1501X","133N00000X","133NN1002X","146N00000X","146M00000X","146L00000X","146D00000X","152W00000X","152WC0802X","152WL0500X","152WX0102X","152WP0200X","152WS0006X","152WV0400X","156F00000X","156FC0800X","156FC0801X","156FX1700X","156FX1100X","156FX1101X","156FX1800X","156FX1201X","156FX1202X","156FX1900X","164W00000X","167G00000X","164X00000X","163W00000X","163WA0400X","163WA2000X","163WP2201X","163WC3500X","163WC0400X","163WC1400X","163WC1500X","163WC2100X","163WC1600X","163WC0200X","163WD0400X","163WD1100X","163WE0003X","163WE0900X","163WF0300X","163WG0100X","163WG0000X","163WG0600X","163WH0500X","163WH0200X","163WH1000X","163WI0600X","163WI0500X","163WL0100X","163WM0102X","163WM0705X","163WN0002X","163WN0003X","163WN0300X","163WN0800X","163WM1400X","163WN1003X","163WX0002X","163WX0003X","163WX0106X","163WX0200X","163WX1100X","163WX0800X","163WX1500X","163WX0601X","163WP0000X","163WP0218X","163WP0200X","163WP1700X","163WS0121X","163WP0808X","163WP0809X","163WP0807X","163WR0006X","163WR0400X","163WR1000X","163WS0200X","163WU0100X","163WW0101X","163WW0000X","372600000X","372500000X","373H00000X","374J00000X","374U00000X","376J00000X","376K00000X","376G00000X","374T00000X","374K00000X","374700000X","3747A0650X","3747P1801X","171100000X","171M00000X","174V00000X","172V00000X","171W00000X","171WH0202X","171WV0202X","172A00000X","176P00000X","170300000X","171400000X","174H00000X","175L00000X","171R00000X","174N00000X","175M00000X","173000000X","172M00000X","176B00000X","171000000X","1710I1002X","1710I1003X","172P00000X","175F00000X","175T00000X","170100000X","405300000X","173C00000X","173F00000X","174400000X","1744G0900X","1744P3200X","1744R1103X","1744R1102X","174M00000X","174MM1900X","183500000X","1835P2201X","1835C0206X","1835C0207X","1835C0205X","1835E0208X","1835G0000X","1835G0303X","1835I0206X","1835N0905X","1835N1003X","1835X0200X","1835P0200X","1835P0018X","1835P1200X","1835P1300X","1835S0206X","183700000X","367A00000X","367H00000X","364S00000X","364SA2100X","364SA2200X","364SC2300X","364SC1501X","364SC0200X","364SE0003X","364SE1400X","364SF0001X","364SG0600X","364SH1100X","364SH0200X","364SI0800X","364SL0600X","364SM0705X","364SN0000X","364SN0800X","364SX0106X","364SX0200X","364SX0204X","364SP0200X","364SP1700X","364SP2800X","364SP0808X","364SP0809X","364SP0807X","364SP0810X","364SP0811X","364SP0812X","364SP0813X","364SR0400X","364SS0200X","364ST0500X","364SW0102X","367500000X","363L00000X","363LA2100X","363LA2200X","363LC1500X","363LC0200X","363LF0000X","363LG0600X","363LN0000X","363LN0005X","363LX0001X","363LX0106X","363LP0200X","363LP0222X","363LP1700X","363LP2300X","363LP0808X","363LS0200X","363LW0102X","363A00000X","363AM0700X","363AS0400X","211D00000X","213E00000X","213ES0103X","213ES0131X","213EG0000X","213EP1101X","213EP0504X","213ER0200X","213ES0000X","229N00000X","221700000X","224Y00000X","225600000X","222Q00000X","226300000X","225700000X","224900000X","225A00000X","225X00000X","225XR0403X","225XE0001X","225XE1200X","225XF0002X","225XG0600X","225XH1200X","225XH1300X","225XL0004X","225XM0800X","225XN1300X","225XP0200X","225XP0019X","224Z00000X","224ZR0403X","224ZE0001X","224ZF0002X","224ZL0004X","225000000X","222Z00000X","224L00000X","225100000X","2251C2600X","2251E1300X","2251E1200X","2251G0304X","2251H1200X","2251H1300X","2251N0400X","2251X0800X","2251P0200X","2251S0007X","225200000X","224P00000X","225B00000X","225800000X","226000000X","225C00000X","225CA2400X","225CA2500X","225CX0006X","225400000X","227800000X","2278C0205X","2278E1000X","2278E0002X","2278G1100X","2278G0305X","2278H0200X","2278P3900X","2278P3800X","2278P4000X","2278P1004X","2278P1006X","2278P1005X","2278S1500X","227900000X","2279C0205X","2279E1000X","2279E0002X","2279G1100X","2279G0305X","2279H0200X","2279P3900X","2279P3800X","2279P4000X","2279P1004X","2279P1006X","2279P1005X","2279S1500X","225500000X","2255A2300X","2255R0406X","231H00000X","231HA2400X","231HA2500X","237600000X","237700000X","235500000X","2355A2700X","2355S0801X","235Z00000X","390200000X","242T00000X","247100000X","2471B0102X","2471C1106X","2471C1101X","2471C3401X","2471M1202X","2471M2300X","2471N0900X","2471Q0001X","2471R0002X","2471C3402X","2471S1302X","2471V0105X","2471V0106X","243U00000X","246X00000X","246XC2901X","246XS1301X","246XC2903X","246Y00000X","246YC3301X","246YC3302X","246YR1600X","246Z00000X","246ZA2600X","246ZB0500X","246ZB0301X","246ZB0302X","246ZB0600X","246ZE0500X","246ZE0600X","246ZG1000X","246ZG0701X","246ZI1000X","246ZN0300X","246ZX2200X","246ZC0007X","246ZS0410X","246Q00000X","246QB0000X","246QC1000X","246QC2700X","246QH0401X","246QH0000X","246QH0600X","246QI0000X","246QL0900X","246QL0901X","246QM0706X","246QM0900X","246W00000X","247000000X","2470A2800X","247200000X","2472B0301X","2472D0500X","2472E0500X","2472R0900X","2472V0600X","246R00000X","247ZC0005X","246RH0600X","246RM2200X","246RP1900X","251B00000X","251S00000X","251C00000X","252Y00000X","253J00000X","251E00000X","251F00000X","251G00000X","253Z00000X","251300000X","251J00000X","251T00000X","251K00000X","251X00000X","251V00000X","261Q00000X","261QM0855X","261QA0600X","261QM0850X","261QA0005X","261QA0006X","261QA1903X","261QA0900X","261QA3000X","261QB0400X","261QC1500X","261QC1800X","261QC0050X","261QD0000X","261QD1600X","261QE0002X","261QE0700X","261QE0800X","261QF0050X","261QF0400X","261QG0250X","261QH0100X","261QH0700X","261QI0500X","261QL0400X","261QM1200X","261QM2500X","261QM3000X","261QM0801X","261QM2800X","261QM1000X","261QM1103X","261QM1101X","261QM1102X","261QM1100X","261QM1300X","261QX0100X","261QX0200X","261QX0203X","261QS0132X","261QS0112X","261QP3300X","261QP2000X","261QP1100X","261QP2300X","261QP2400X","261QP0904X","261QP0905X","261QR0200X","261QR0206X","261QR0208X","261QR0207X","261QR0800X","261QR0400X","261QR0404X","261QR0401X","261QR0405X","261QR1100X","261QR1300X","261QS1200X","261QS1000X","261QU0200X","261QV0200X","273100000X","275N00000X","273R00000X","273Y00000X","276400000X","287300000X","281P00000X","281PC2000X","282N00000X","282NC2000X","282NC0060X","282NR1301X","282NW0100X","282E00000X","286500000X","2865C1500X","2865M2000X","2865X1600X","283Q00000X","283X00000X","283XC2000X","282J00000X","284300000X","291U00000X","292200000X","291900000X","293D00000X","302F00000X","302R00000X","305S00000X","305R00000X","311500000X","310400000X","3104A0630X","3104A0625X","317400000X","311Z00000X","311ZA0620X","315D00000X","310500000X","313M00000X","314000000X","3140N1450X","177F00000X","174200000X","320800000X","320900000X","323P00000X","322D00000X","320600000X","320700000X","324500000X","3245S0500X","385H00000X","385HR2050X","385HR2055X","385HR2060X","385HR2065X","331L00000X","332100000X","332B00000X","332BC3200X","332BD1200X","332BN1400X","332BX2000X","332BP3500X","333300000X","332G00000X","332H00000X","332S00000X","332U00000X","332800000X","335G00000X","332000000X","332900000X","335U00000X","333600000X","3336C0002X","3336C0003X","3336C0004X","3336H0001X","3336I0012X","3336L0003X","3336M0002X","3336M0003X","3336N0007X","3336S0011X","335V00000X","335E00000X","344800000X","341600000X","3416A0800X","3416L0300X","3416S0300X","347B00000X","341800000X","3418M1120X","3418M1110X","3418M1130X","343900000X","347C00000X","343800000X","344600000X","347D00000X","347E00000X","342000000X"],"description":"NUCC healthcare provider taxonomy code (10-character alphanumeric, e.g., `208000000X` for Pediatrics)."},"BillingCodeType":{"type":"string","enum":["CPT","HCPCS","RC","MS-DRG","APR-DRG","LOCAL","CSTM-ALL"],"description":"Billing code system. `CPT` = Current Procedural Terminology, `HCPCS` = Healthcare Common Procedure Coding System, `RC` = Revenue Code, `MS-DRG` / `APR-DRG` = Diagnosis Related Group, `LOCAL` = payer-specific code, `CSTM-ALL` = custom/all codes."},"EntityType":{"type":"string","enum":["individual","group"],"description":"Provider entity type (individual or group)"},"BillingClass":{"type":"string","enum":["professional","institutional"],"description":"Billing class (professional or institutional)"},"ServiceCode":{"type":"string","enum":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,19,20,21,22,23,24,25,26,27,31,32,33,34,41,42,49,50,51,52,53,54,55,56,57,58,60,61,62,65,71,72,81,99,"CSTM-00","none"],"description":"CMS place of service code (e.g., `11` for office, `21` for inpatient hospital, `22` for outpatient hospital)."},"BillingCodeModifier":{"type":"string","enum":["none","TC","26"],"description":"CPT/HCPCS modifier. `TC` = technical component, `26` = professional component, `none` = no modifier."},"YearMonth":{"type":"object","required":["year","month"],"properties":{"year":{"type":"integer","description":"4-digit year (e.g., 2024, 2025)."},"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month number, 1-12 (1=January, 12=December)."}},"description":"Year and month specifier for a time period."},"NegotiatedType":{"type":"string","enum":["negotiated","derived","fee schedule","percentage","per diem"],"description":"How the rate was negotiated. `negotiated` = directly negotiated between payer and provider. `derived` = derived from another rate arrangement. `fee schedule` = from a published fee schedule. `percentage` = expressed as a percentage of a base amount. `per diem` = daily rate for inpatient services."},"AggregationType":{"type":"string","enum":["avg_rate","median_rate","percentile_1","percentile_2","percentile_3","percentile_4","percentile_5","percentile_10","percentile_15","percentile_20","percentile_25","percentile_30","percentile_35","percentile_40","percentile_45","percentile_50","percentile_55","percentile_60","percentile_65","percentile_70","percentile_75","percentile_80","percentile_85","percentile_90","percentile_95","percentile_96","percentile_97","percentile_98","percentile_99","max_rate","min_rate"],"description":"Statistical aggregation type"},"GroupByField":{"type":"string","enum":["payer","npiState","taxonomyCode","entityType","negotiatedType","billingClass","billingCodeType","billingCode","billingCodeGroup","billingCodeSubgroup","serviceCode","billingCodeModifier","network"],"description":"Field to group results by. 'network' splits results per individual (un-normalized) network name; a rate in multiple networks contributes to each."},"ProviderGroupByField":{"type":"string","enum":["payer","npiState","taxonomyCode","entityType","negotiatedType","billingClass","billingCodeType","billingCode","billingCodeGroup","billingCodeSubgroup","serviceCode","billingCodeModifier","network","planName"],"description":"Field to group provider-rate results by. 'network' and 'planName' return deduplicated arrays without splitting otherwise-identical rate rows. 'planName' arrays are sorted and limited to at most 30 names."}}},"security":[{"APIKeyAuth":[]}],"servers":[{"url":"https://api.payerprice.com","description":"Production API Server"}],"paths":{"/api/v1/npis":{"post":{"summary":"Look up providers by NPI","description":"Retrieve provider information for one or more National Provider Identifiers (NPIs).","tags":["Provider APIs"],"requestBody":{"required":true,"content":{"application/json":{"examples":{"npiQuery":{"summary":"Example 1: Query NPI information","description":"Query NPI information","value":{"npis":[1073502985],"includeFields":["npi","name","state","counties","entityType","payers","tins","primaryTaxonomyCode"]}}},"schema":{"type":"object","required":["npis"],"properties":{"npis":{"type":"array","items":{"type":"number"},"description":"Array of NPI numbers to query","maxItems":10},"includeFields":{"type":"array","items":{"type":"string","enum":["npi","name","credentials","state","counties","entityType","payers","tins","primaryTaxonomyCode"]},"description":"List of fields to include in the response"}}}}}},"responses":{"200":{"description":"Array of NPI information objects","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"npi":{"type":"number"},"name":{"type":"string"},"credentials":{"type":"string"},"primaryTaxonomyCode":{"type":"string"},"state":{"type":"string"},"counties":{"type":"array","items":{"type":"string"}},"entityType":{"type":"string"},"payers":{"type":"array","items":{"type":"string"}},"tins":{"type":"array","items":{"type":"number"}}}}}}}},"400":{"description":"Invalid request parameters"}}}},"/api/v1/npiSearch":{"post":{"summary":"Search NPIs by name","description":"Fuzzy search for NPIs by name or NPI. Optionally filter results by taxonomy, state, county, or entity type.","tags":["Provider APIs"],"requestBody":{"required":true,"content":{"application/json":{"examples":{"npiSearch":{"summary":"Example 1: Search for NPI by name","description":"Search for NPI by name","value":{"searchTerm":"Chu Chen","includeFields":["npi","displayName","state","inNetworkPayers","tins"],"states":["MA"],"limit":50}}},"schema":{"type":"object","properties":{"searchTerm":{"type":"string","maxLength":40,"description":"Search term to match against provider names or NPIs."},"matchFields":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"string","enum":["displayName","ccns","otherName","tins"]},"description":"Fields used for text matching. Defaults to displayName, ccns, otherName, and tins."},"includeFields":{"type":"array","items":{"type":"string","enum":["npi","displayName","state","counties","taxonomyCodes","entityType","relatedNpis","inNetworkPayers","tins","otherName"]},"description":"List of fields to include in the response"},"taxonomyCodes":{"type":"array","items":{"type":"string"},"description":"List of taxonomy codes to filter by","maxItems":10},"states":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"description":"List of two-letter state codes to filter by","maxItems":5},"counties":{"type":"array","items":{"type":"string"},"description":"List of county names to filter by","maxItems":10},"entityTypes":{"type":"array","items":{"type":"string","enum":["Individual","Group"]},"description":"Filter by provider entity types","maxItems":2},"inNetworkPayers":{"type":"array","items":{"$ref":"#/components/schemas/Payer"},"description":"Restrict results to entries whose inNetworkPayers contains at least one of the given payers.","maxItems":1},"limit":{"type":"number","description":"Maximum number of results to return; requests above 3,000 return at most 3,000.","minimum":1}}}}}},"responses":{"200":{"description":"List of matching providers","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"npi":{"type":"string"},"value":{"type":"number","description":"NPI number"},"counties":{"type":"string"},"title":{"type":"string","description":"Display name with state"},"ccns":{"type":"string"},"credentials":{"type":"string"},"displayName":{"type":"string"},"state":{"type":"string"},"taxonomyCodes":{"type":"string"},"entityType":{"type":"string"},"relatedNpis":{"type":"string"},"inNetworkPayers":{"type":"string"},"tins":{"type":"string"},"otherName":{"type":"string"}}}}}}},"400":{"description":"Invalid request parameters"}}}},"/api/v1/market/benchmarks":{"post":{"summary":"Get market rate benchmarks","description":"Search for **market-level aggregate statistics** and benchmarks. Results summarize published rates in the selected payer, geography, taxonomy, billing-code, and period cohort; they are not prices for a specific provider or a guarantee of claim payment. Keep billing class, service code, modifier, and negotiated type comparable when interpreting percentiles. An empty result may reflect an overly narrow filter or missing published data.","tags":["Pricing APIs"],"security":[{"APIKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"marketBenchmarksExample":{"summary":"Example: Market Benchmarks for Office Visits","description":"Get market statistics (50th, 75th, 90th, 95th percentiles) for pediatric office visits in Massachusetts","value":{"filters":{"states":["MA"],"taxonomyCodes":["208000000X"],"payers":["United","Cigna"],"billingCodeAndTypes":[{"code":"99213","type":"CPT"},{"code":"99214","type":"CPT"}],"serviceCodes":["11"],"negotiatedTypes":["negotiated","fee schedule"],"billingClasses":["professional"]},"metrics":{"aggregations":["percentile_50","percentile_75","percentile_90","percentile_95"]},"groupBy":["payer","billingCode"]}}},"schema":{"type":"object","required":["filters","metrics"],"properties":{"filters":{"type":"object","required":["states","taxonomyCodes","payers","billingCodeAndTypes"],"properties":{"states":{"type":"array","items":{"$ref":"#/components/schemas/State"},"description":"Array of US state codes to filter by (required for market benchmarks)."},"zipCodes":{"type":"array","items":{"type":"string"},"description":"5-digit US ZIP codes to filter results by provider location (e.g., 02451, 90210)."},"taxonomyCodes":{"type":"array","items":{"$ref":"#/components/schemas/TaxonomyCode"},"description":"Array of provider taxonomy codes (required for market benchmarks)."},"payers":{"type":"array","items":{"$ref":"#/components/schemas/Payer"},"description":"Array of payer identifiers (required)."},"billingCodeAndTypes":{"type":"array","items":{"type":"object","required":["code","type"],"properties":{"code":{"type":"string","description":"Billing code (e.g., 99213)"},"type":{"$ref":"#/components/schemas/BillingCodeType"}}},"description":"Specific billing codes to search for (required)."},"entityTypes":{"type":"array","items":{"$ref":"#/components/schemas/EntityType"},"description":"Individual or group practice filter (optional)"},"billingClasses":{"type":"array","items":{"$ref":"#/components/schemas/BillingClass"},"description":"Professional vs institutional (optional)"},"serviceCodes":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCode"},"description":"Place of service codes (e.g., office, hospital, telehealth) to search for (optional)"},"billingCodeModifiers":{"type":"array","items":{"$ref":"#/components/schemas/BillingCodeModifier"},"description":"CPT modifiers to search for (optional)"},"negotiatedTypes":{"type":"array","items":{"$ref":"#/components/schemas/NegotiatedType"},"description":"Rate negotiation types to search for (optional)"},"yearMonths":{"type":"array","items":{"type":"object","required":["year","month"],"properties":{"year":{"type":"number","description":"Year (e.g., 2025)"},"month":{"type":"number","description":"Month (1-12)"}}},"description":"Year/month periods to filter by (optional). Leave empty to query the latest available data; supply specific periods only when comparing rates across time."},"planNames":{"type":"array","items":{"type":"string"},"description":"Normalized plan names to narrow results to specific insurance plans (optional)."},"networks":{"type":"array","items":{"type":"string"},"description":"Individual (un-normalized) network names to narrow results to specific networks, exactly as reported in the payer transparency file (optional)."}}},"metrics":{"type":"object","required":["aggregations"],"properties":{"aggregations":{"type":"array","items":{"type":"string","enum":["avg_rate","median_rate","max_rate","min_rate","num_distinct_rates","num_distinct_npis","num_distinct_tins","num_entries","percentile_1","percentile_2","percentile_3","percentile_4","percentile_5","percentile_10","percentile_15","percentile_20","percentile_25","percentile_30","percentile_35","percentile_40","percentile_45","percentile_50","percentile_55","percentile_60","percentile_65","percentile_70","percentile_75","percentile_80","percentile_85","percentile_90","percentile_95","percentile_96","percentile_97","percentile_98","percentile_99"]},"description":"Statistical metrics to calculate (required for market benchmarks)"},"comparedTo":{"type":"string","enum":["none","medicare_2025","medicare_2024","medicare_2023","medicare_2022","medicare_2021","medicare_2020"],"description":"Optional Medicare comparison baseline for the benchmark values."}}},"groupBy":{"type":"array","items":{"$ref":"#/components/schemas/GroupByField"},"description":"Fields to group results by (optional). Including network returns a separate benchmark group for each individual network name."}}}}}},"responses":{"200":{"description":"Array of market benchmark results.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["metrics","value"],"properties":{"metrics":{"type":"string","description":"The metric type returned (aggregation name)","example":"percentile_50"},"value":{"type":"number","description":"The numeric value for the metric","example":125.5},"payer":{"type":"string","description":"Payer name (included when groupBy contains 'payer')","example":"United"},"npiState":{"type":"string","description":"State code (included when groupBy contains 'npiState')","example":"MA"},"taxonomyCode":{"type":"string","description":"Provider taxonomy code (included when groupBy contains 'taxonomyCode')","example":"208000000X"},"entityType":{"description":"Provider entity type (included when groupBy contains 'entityType')","$ref":"#/components/schemas/EntityType"},"billingCode":{"type":"string","description":"Billing code (included when groupBy contains 'billingCode')","example":"99213"},"billingCodeType":{"description":"Billing code type (included when groupBy contains 'billingCodeType')","$ref":"#/components/schemas/BillingCodeType"},"billingClass":{"description":"Billing class (included when groupBy contains 'billingClass')","$ref":"#/components/schemas/BillingClass"},"negotiatedType":{"description":"Negotiated rate type (included when groupBy contains 'negotiatedType')","$ref":"#/components/schemas/NegotiatedType"},"serviceCode":{"type":"string","description":"Service code (included when groupBy contains 'serviceCode')","example":"11"},"billingCodeModifier":{"type":"string","description":"Billing code modifier (included when groupBy contains 'billingCodeModifier')","example":"none"},"network":{"type":"string","description":"Individual (un-normalized) network name defining the benchmark group (included when groupBy contains 'network')","example":"Choice Plus"}}},"description":"Array of market benchmark results. Each object contains grouping dimensions (based on groupBy parameter) and a metrics/value pair representing the calculated statistics.","example":[{"payer":"United","billingCode":"99213","metrics":"percentile_50","value":125.5},{"payer":"United","billingCode":"99213","metrics":"percentile_75","value":145.75},{"payer":"Cigna","billingCode":"99214","metrics":"percentile_90","value":180.25}]}}}},"400":{"description":"Invalid request parameters or query limits exceeded."},"401":{"description":"User not authenticated or invalid API key"},"403":{"description":"User does not have permission to access this endpoint"}}}},"/api/v1/provider/rates":{"post":{"summary":"Get provider negotiated rates","description":"Search for **published provider-specific negotiated rates** by NPI, TIN, or CCN. Preserve the matched provider identifier, payer, plan or network, billing code and type, billing class, service code, modifier, negotiated type, and source period when comparing rows. Multiple rows for one payer and code may represent different contracts or contexts. A published rate does not by itself establish a claim's allowed or paid amount. For cursor pagination, send `pagination: {}` (default page size 1,000), then repeat the same request with `pagination.cursor` set to the returned `nextCursor` until it is null. Each page is billed separately. The organization's configured maximum can be lower or higher than 1,000, up to 10,000. Without `pagination`, the legacy array response is unchanged.","tags":["Pricing APIs"],"security":[{"APIKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"providerRatesByNpi":{"summary":"Example 1: Rates for Specific Provider (NPI)","description":"Get negotiated rates for provider with NPI 1073502985 for specific billing codes","value":{"providers":{"npis":[1073502985]},"payers":["United"],"billingCodeAndTypes":[{"code":"99213","type":"CPT"},{"code":"99214","type":"CPT"}],"serviceCodes":["11"],"negotiatedTypes":["negotiated","fee schedule"],"billingClasses":["professional"],"groupBy":["payer","billingCode","serviceCode","billingCodeModifier"]}},"providerRatesByTin":{"summary":"Example 2: Rates for Provider Group (TIN)","description":"Get negotiated rates for provider group with TIN 123456789","value":{"providers":{"tins":[123456789]},"payers":["United","Cigna"],"billingCodeAndTypes":[{"code":"99211","type":"CPT"},{"code":"99213","type":"CPT"},{"code":"99214","type":"CPT"},{"code":"99215","type":"CPT"}],"billingClasses":["professional"],"groupBy":["payer","billingCode"]}},"providerRatesByCcn":{"summary":"Example 3: Hospital Rates by CCN","description":"Get negotiated institutional rates for hospital with CCN 050001","value":{"providers":{"ccns":["050001"]},"payers":["Aetna"],"billingCodeAndTypes":[{"code":"470","type":"MS-DRG"},{"code":"478","type":"MS-DRG"}],"billingClasses":["institutional"],"groupBy":["payer","billingCode","billingCodeType"]}}},"schema":{"type":"object","required":["providers","payers","billingCodeAndTypes"],"properties":{"providers":{"type":"object","minProperties":1,"anyOf":[{"required":["npis"]},{"required":["tins"]},{"required":["ccns"]}],"properties":{"npis":{"type":"array","minItems":1,"items":{"type":"number"},"description":"NPIs to query negotiated rates for (optional, specify at least one of npis, tins, or ccns)"},"tins":{"type":"array","minItems":1,"items":{"type":"number"},"description":"TINs to query negotiated rates for (optional, specify at least one of npis, tins, or ccns)"},"ccns":{"type":"array","minItems":1,"items":{"type":"string"},"description":"CCNs to query negotiated rates for (optional, specify at least one of npis, tins, or ccns)"}},"description":"Provider identifiers to query rates for. At least one provider identifier (NPI, TIN, or CCN) must be specified."},"payers":{"type":"array","items":{"$ref":"#/components/schemas/Payer"},"description":"Array of payer identifiers (required)"},"billingCodeAndTypes":{"type":"array","items":{"type":"object","required":["code","type"],"properties":{"code":{"type":"string","description":"Billing code (e.g., 99213)"},"type":{"$ref":"#/components/schemas/BillingCodeType"}}},"description":"Specific billing codes to search for (optional)"},"billingClasses":{"type":"array","items":{"$ref":"#/components/schemas/BillingClass"},"description":"Professional vs institutional (optional)"},"serviceCodes":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCode"},"description":"Place of service codes to filter by (optional)"},"billingCodeModifiers":{"type":"array","items":{"$ref":"#/components/schemas/BillingCodeModifier"},"description":"Billing code modifiers to filter by (optional)"},"negotiatedTypes":{"type":"array","items":{"$ref":"#/components/schemas/NegotiatedType"},"description":"Rate negotiation types to search for (optional)"},"yearMonths":{"type":"array","items":{"type":"object","required":["year","month"],"properties":{"year":{"type":"number","description":"Year (e.g., 2025)"},"month":{"type":"number","description":"Month (1-12)"}}},"description":"Year/month periods to filter by (optional). Leave empty to query the latest available data; supply specific periods only when comparing rates across time."},"planNames":{"type":"array","items":{"type":"string"},"description":"Normalized plan names to narrow results to specific insurance plans (optional)."},"networks":{"type":"array","items":{"type":"string"},"description":"Individual (un-normalized) network names to narrow results to specific networks, exactly as reported in the payer transparency file (optional)."},"groupBy":{"type":"array","items":{"$ref":"#/components/schemas/ProviderGroupByField"},"description":"Fields to group results by (optional). Including network or planName adds the corresponding deduplicated array without splitting otherwise-identical provider-rate groups. planName arrays are sorted and limited to at most 30 names."},"pagination":{"type":"object","description":"Opt in to cursor pagination. Omit for the legacy array response.","properties":{"pageSize":{"type":"integer","minimum":1,"maximum":10000,"default":1000,"description":"Rows per page. Limited by the organization's configured maximum; defaults to the smaller of 1,000 and that maximum."},"cursor":{"type":"string","description":"Opaque nextCursor from the preceding page. Keep every other request field unchanged."}}}}}}}},"responses":{"200":{"description":"Legacy array response, or {data, nextCursor} when pagination is supplied.","content":{"application/json":{"schema":{"oneOf":[{"type":"array","items":{"type":"object","required":["metrics","value"],"properties":{"metrics":{"type":"string","description":"The metric type returned (NPI/TIN/CCN identifier prefixed with npi_, tin_, or ccn_)","example":"npi_1073502985"},"value":{"type":"number","description":"The negotiated rate value for the provider","example":150},"payer":{"type":"string","description":"Payer name (included when groupBy contains 'payer')","example":"United"},"npiState":{"type":"string","description":"State code (included when groupBy contains 'npiState')","example":"MA"},"taxonomyCode":{"type":"string","description":"Provider taxonomy code (included when groupBy contains 'taxonomyCode')","example":"208000000X"},"entityType":{"description":"Provider entity type (included when groupBy contains 'entityType')","$ref":"#/components/schemas/EntityType"},"billingCode":{"type":"string","description":"Billing code (included when groupBy contains 'billingCode')","example":"99213"},"billingCodeType":{"description":"Billing code type (included when groupBy contains 'billingCodeType')","$ref":"#/components/schemas/BillingCodeType"},"billingClass":{"description":"Billing class (included when groupBy contains 'billingClass')","$ref":"#/components/schemas/BillingClass"},"negotiatedType":{"description":"Negotiated rate type (included when groupBy contains 'negotiatedType')","$ref":"#/components/schemas/NegotiatedType"},"serviceCode":{"type":"string","description":"Service code (included when groupBy contains 'serviceCode')","example":"11"},"billingCodeModifier":{"type":"string","description":"Billing code modifier (included when groupBy contains 'billingCodeModifier')","example":"none"},"network":{"type":"array","items":{"type":"string"},"description":"Individual (un-normalized) network names aggregated across otherwise-identical result rows (included when groupBy contains 'network')","example":["Choice Plus","Navigate"]},"planName":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"Up to 30 sorted, normalized plan names aggregated across otherwise-identical result rows (included when groupBy contains 'planName')","example":["HMO","PPO"]}}},"description":"Array of provider-specific rate results. Each object contains grouping dimensions (based on groupBy parameter) and a metrics/value pair representing the provider's negotiated rate.","example":[{"payer":"United","billingCode":"99213","serviceCode":"11","billingCodeModifier":"none","metrics":"npi_1073502985","value":150},{"payer":"United","billingCode":"99214","serviceCode":"11","billingCodeModifier":"none","metrics":"npi_1073502985","value":175.5},{"payer":"Cigna","billingCode":"99213","metrics":"tin_123456789","value":145}]},{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/paths/~1api~1v1~1provider~1rates/post/responses/200/content/application~1json/schema/oneOf/0/items"}},"nextCursor":{"type":"string","nullable":true,"description":"Use in the next request; null means no more rows."}}}]}}}},"400":{"description":"Invalid request parameters or query limits exceeded."},"401":{"description":"User not authenticated or invalid API key"},"403":{"description":"User does not have permission to access this endpoint"}}}},"/api/v1/ccns":{"post":{"summary":"Look up hospitals by CCN","description":"Retrieve hospital information keyed by CMS Certification Number (CCN).","tags":["Provider APIs"],"requestBody":{"required":true,"content":{"application/json":{"example":{"ccns":["100154"],"includeFields":["name","state","city","npi"]},"schema":{"type":"object","required":["ccns"],"properties":{"ccns":{"type":"array","items":{"type":"string"},"description":"Six-digit CMS Certification Numbers."},"ccnCategories":{"type":"array","items":{"type":"string","nullable":true}},"ccnFacilityTypes":{"type":"array","items":{"type":"string","nullable":true}},"includeFields":{"type":"array","items":{"type":"string"},"description":"Optional hospital fields to include."}}}}}},"responses":{"200":{"description":"Hospital information keyed by CCN; an empty lookup returns an empty object.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","required":["ccn"],"properties":{"ccn":{"type":"string"},"name":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"npi":{"type":"number","nullable":true}}}}}}},"400":{"description":"Invalid request body or CCN"}}}},"/api/v1/ccnSearch":{"post":{"summary":"Search hospitals by name or CCN","description":"Search hospitals by name or CCN, with optional state, category, and facility type filters.","tags":["Provider APIs"],"requestBody":{"required":true,"content":{"application/json":{"example":{"searchTerms":["Memorial"],"state":"FL","limit":20},"schema":{"type":"object","additionalProperties":false,"properties":{"searchTerms":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":40}},"state":{"$ref":"#/components/schemas/State"},"ccn":{"type":"string","description":"Exact six-digit CCN to match."},"limit":{"type":"integer","minimum":1,"default":20,"description":"Maximum number of results to return; requests above 10,000 return at most 10,000."},"ccnFacilityTypes":{"type":"array","items":{"type":"string","nullable":true}},"ccnCategories":{"type":"array","items":{"type":"string","nullable":true}},"includeFields":{"type":"array","nullable":true,"items":{"type":"string","enum":["ccn","name","street","zipCode","address","phone","providerType","ownership","bedCount","careQuality","clinicalServices","affiliatedHealthSystem","tins","inNetworkPayers","groupNpis","npi"]}}}}}}},"responses":{"200":{"description":"Matching hospitals, at most the requested limit.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["value","ccn","title","grouping","name","city","state","affiliatedHealthSystem"],"properties":{"value":{"type":"string"},"ccn":{"type":"string"},"title":{"type":"string"},"grouping":{"type":"string","nullable":true},"name":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"affiliatedHealthSystem":{"type":"string","nullable":true}}}}}}},"400":{"description":"Invalid request body, state, or CCN"}}}},"/api/v1/tins":{"post":{"summary":"Look up providers by TIN","description":"Retrieve provider information for one or more Taxpayer Identification Numbers (TINs). **Note:** CMS allows insurers to report provider TINs using either an NPI or Employer Identification Number (EIN).","tags":["Provider APIs"],"requestBody":{"required":true,"content":{"application/json":{"examples":{"tinQuery":{"summary":"Example 1: Query TIN information","description":"Query TIN information","value":{"tins":[42103590,42484572,42774441],"includeFields":["tinName","states","relatedGroupNpis"]}}},"schema":{"type":"object","properties":{"tins":{"type":"array","items":{"type":"number"},"description":"Array of TIN numbers to query","maxItems":10},"includeFields":{"type":"array","items":{"type":"string","enum":["tinName","states","relatedGroupNpis"]},"description":"List of fields to include in the response. Use relatedGroupNpis to return a sample of group NPIs associated with each TIN."}}}}}},"responses":{"200":{"description":"Successfully retrieved TIN information","content":{"application/json":{"schema":{"type":"object","properties":{"tins":{"type":"array","items":{"type":"object","properties":{"tinName":{"type":"string"},"states":{"type":"array","items":{"type":"string"}},"relatedGroupNpis":{"type":"array","items":{"type":"string"},"description":"Sample of group NPIs associated with the TIN"}}}}}}}}},"400":{"description":"Invalid request parameters"}}}},"/api/v1/tinSearch":{"post":{"summary":"Search TINs by name","description":"Fuzzy search for TINs by name, provider taxonomy codes, state, or TIN type (ein/npi).","tags":["Provider APIs"],"requestBody":{"required":true,"content":{"application/json":{"examples":{"tinSearch":{"summary":"Example 1: Search for TIN by name, type and state","description":"Search TINs with a specific type (e.g., EIN) and state","value":{"searchTerm":"Medical Group","tinTypes":["ein"],"states":["CA"],"includeFields":["tinValue","tinType","tinName","tinState"],"limit":50}}},"schema":{"type":"object","properties":{"searchTerm":{"type":"string","maxLength":40,"description":"Term to match against organization names (fuzzy match). Provide either `searchTerm` (single) or `searchTerms` (multiple)."},"searchTerms":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":40},"description":"Multiple terms to match against organization names. Use instead of `searchTerm` when querying several names at once."},"matchFields":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"string","enum":["tinName","tinValue"]},"description":"Fields used for text matching. Defaults to tinName and tinValue."},"taxonomyCodes":{"type":"array","items":{"type":"string"},"description":"Taxonomy codes to filter by (optional).","maxItems":10},"states":{"type":"array","items":{"type":"string"},"description":"Two-letter state codes to filter by (optional).","maxItems":10},"tinTypes":{"type":"array","items":{"type":"string","enum":["ein","npi"]},"description":"TIN type filter. `ein` = Employer Identification Number, `npi` = National Provider Identifier.","maxItems":2},"limit":{"type":"number","description":"Maximum number of results to return; requests above 3,000 return at most 3,000.","minimum":1},"includeFields":{"type":"array","items":{"type":"string","enum":["tinValue","tinType","tinName","tinState","tinAddress","tinTaxonomyCodes","tinSize","inNetworkPayers","sampleNpis1","sampleNpis2"]},"description":"Fields to include in the response."}}}}}},"responses":{"200":{"description":"List of matching TINs"},"400":{"description":"Invalid request parameters"}}}},"/api/v1/payers":{"get":{"summary":"List available payers","description":"Retrieve supported payers and available year/month source-data periods. A listed period means data is available for that payer; it does not establish a contract effective date for any returned rate.","tags":["Payer APIs"],"responses":{"200":{"description":"Array of payer availability objects","content":{"application/json":{"example":[{"payer":"Aetna","yearMonths":[{"year":2025,"month":1}]}],"schema":{"type":"array","items":{"type":"object","properties":{"payer":{"type":"string","description":"The payer identifier"},"yearMonths":{"type":"array","description":"Available data periods sorted by most recent first","items":{"type":"object","properties":{"year":{"type":"integer","description":"Four-digit year"},"month":{"type":"integer","description":"Month number (1-12)"}}}}}}}}}},"401":{"description":"Missing or invalid API key."},"402":{"description":"Insufficient API credit for an API-key request."},"403":{"description":"The API key cannot access this endpoint."},"429":{"description":"Request rate limit exceeded; retry after backing off."}}}},"/api/v1/payer/plans":{"post":{"summary":"List plans for a payer","description":"Retrieve the list of normalized plan names for a given payer, ordered by frequency (most common first).","tags":["Payer APIs"],"requestBody":{"required":true,"content":{"application/json":{"examples":{"bcbsExample":{"summary":"Example: Query BCBS plan names","description":"Query all plan names across BCBS-affiliated payers","value":{"payer":"BCBS"}}},"schema":{"type":"object","required":["payer"],"properties":{"payer":{"$ref":"#/components/schemas/Payer"}}}}}},"responses":{"200":{"description":"Array of payer plan objects","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"payer":{"type":"string","description":"The payer identifier from the request"},"planName":{"type":"string","description":"Normalized plan name"}}}}}}},"400":{"description":"Invalid payer"}}}}},"tags":[{"name":"Payer APIs","description":"Retrieve payer-level metadata — supported payers, available data periods, and plan names for a given insurance payer."},{"name":"Provider APIs","description":"Look up and search for healthcare providers by NPI, TIN, name, location, taxonomy, entity type, in-network payers, or affiliations. Supports both direct lookups and fuzzy search — suited for building provider directories and network analysis."},{"name":"Pricing APIs","description":"Retrieve negotiated rates and market statistics. Includes market-wide benchmarks (percentiles, averages, min/max), provider-specific rates (by NPI, TIN, or CCN), individual rate records across a market segment, and hospital-published rates from price transparency files."}]}