diff --git a/SUMMARY.md b/SUMMARY.md index e1beefb..df5b584 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -90,8 +90,20 @@ * [Pharmacy](data-integration/carin-bb/pharmacy.md) * [Oral](data-integration/carin-bb/oral.md) * [Drug Formulary](data-integration/drug-formulary/README.md) - * [Payer Plans](data-integration/drug-formulary/payer-plans.md) + * [Payer Plans](data-integration/drug-formulary/payer-plans/README.md) + * [Plan Identifiers](data-integration/drug-formulary/payer-plans/plan-identifiers.md) + * [Plan Contacts](data-integration/drug-formulary/payer-plans/plan-contacts.md) + * [Coverage Areas](data-integration/drug-formulary/payer-plans/coverage-areas.md) + * [Drug Coverages](data-integration/drug-formulary/payer-plans/drug-coverages.md) + * [Drug Coverage Benefits](data-integration/drug-formulary/payer-plans/drug-coverage-benefits.md) + * [Drug Plans](data-integration/drug-formulary/payer-plans/drug-plans.md) + * [Drug Plan Specific Costs](data-integration/drug-formulary/payer-plans/drug-plan-specific-costs.md) + * [Drug Plan Tier Benefits](data-integration/drug-formulary/payer-plans/drug-plan-tier-benefits.md) + * [Drug Plan Tier Costs](data-integration/drug-formulary/payer-plans/drug-plan-tier-costs.md) + * [Drug Plan General Costs](data-integration/drug-formulary/payer-plans/drug-plan-general-costs.md) * [Formularies](data-integration/drug-formulary/formularies.md) + * [Formulary Identifiers](data-integration/drug-formulary/formulary-identifiers.md) + * [Formulary Contacts](data-integration/drug-formulary/formulary-contacts.md) * [Formulary Drugs](data-integration/drug-formulary/formulary-drugs.md) * [Formulary Items](data-integration/drug-formulary/formulary-items.md) * [Releases](releases.md) diff --git a/assets/data-integration/coverage_areas.75383ebd.csv b/assets/data-integration/coverage_areas.75383ebd.csv new file mode 100644 index 0000000..0a6fadc --- /dev/null +++ b/assets/data-integration/coverage_areas.75383ebd.csv @@ -0,0 +1,4 @@ +coverage_area_id,name,aliases,status,type_codes,phone,fax,email,url,address_line1,address_line2,city,state,zip,latitude,longitude,region_geojson,managing_org_npi,last_updated,is_deleted +AREA-NY,New York State,,active,,8885551002,,,https://example.org/areas/ny,,,,NY,,42.9538,-75.5268,,9999999993,2026-10-01T09:00:00-05:00, +AREA-BRONX,Bronx County,,active,,,,,,,,Bronx,NY,,40.8448,-73.8648,"{""type"":""Polygon"",""coordinates"":[[[-73.933,40.785],[-73.748,40.785],[-73.748,40.916],[-73.933,40.916],[-73.933,40.785]]]}",9999999993,2026-10-01T09:00:00-05:00, +AREA-US,United States,,active,,,,,,,,,,,,,"{""type"":""Polygon"",""coordinates"":[[[-125.0,24.5],[-66.9,24.5],[-66.9,49.4],[-125.0,49.4],[-125.0,24.5]]]}",9999999993,2026-10-01T09:00:00-05:00, diff --git a/assets/data-integration/drug_coverage_benefits.a5ea5fb1.csv b/assets/data-integration/drug_coverage_benefits.a5ea5fb1.csv new file mode 100644 index 0000000..d4d051d --- /dev/null +++ b/assets/data-integration/drug_coverage_benefits.a5ea5fb1.csv @@ -0,0 +1,3 @@ +benefit_id,coverage_id,requirement,limit_values,limit_units,limit_codes,is_deleted +BEN-DSNP-RX,COV-DSNP-RX,Part D covered drugs only,90,days,days-supply, +BEN-ISNP-RX,COV-ISNP-RX,,,,, diff --git a/assets/data-integration/drug_plan_general_costs.9c2ffe06.csv b/assets/data-integration/drug_plan_general_costs.9c2ffe06.csv new file mode 100644 index 0000000..e4e734a --- /dev/null +++ b/assets/data-integration/drug_plan_general_costs.9c2ffe06.csv @@ -0,0 +1,5 @@ +drug_plan_id,cost_type,cost_type_system,group_size,amount,comment,is_deleted +DP-DSNP,premium,,1,0.00,No monthly premium for members with full Medicaid, +DP-DSNP,deductible,,1,0.00,, +DP-ISNP,premium,,1,38.50,, +DP-ISNP,deductible,,1,590.00,Applies to tiers 3 and above, diff --git a/assets/data-integration/drug_plan_specific_costs.336af84a.csv b/assets/data-integration/drug_plan_specific_costs.336af84a.csv new file mode 100644 index 0000000..df3163e --- /dev/null +++ b/assets/data-integration/drug_plan_specific_costs.336af84a.csv @@ -0,0 +1,4 @@ +drug_plan_id,pharmacy_benefit_type,is_deleted +DP-DSNP,1-month-in-retail, +DP-DSNP,3-month-in-mail, +DP-ISNP,1-month-in-retail, diff --git a/assets/data-integration/drug_plan_tier_benefits.71fa84e0.csv b/assets/data-integration/drug_plan_tier_benefits.71fa84e0.csv new file mode 100644 index 0000000..d8f2005 --- /dev/null +++ b/assets/data-integration/drug_plan_tier_benefits.71fa84e0.csv @@ -0,0 +1,11 @@ +drug_plan_id,pharmacy_benefit_type,drug_tier,is_deleted +DP-DSNP,1-month-in-retail,preferred-generic, +DP-DSNP,1-month-in-retail,generic, +DP-DSNP,1-month-in-retail,preferred-brand, +DP-DSNP,1-month-in-retail,non-preferred-brand, +DP-DSNP,1-month-in-retail,specialty, +DP-DSNP,3-month-in-mail,preferred-generic, +DP-DSNP,3-month-in-mail,generic, +DP-DSNP,3-month-in-mail,preferred-brand, +DP-ISNP,1-month-in-retail,preferred-generic, +DP-ISNP,1-month-in-retail,preferred-brand, diff --git a/assets/data-integration/drug_plan_tier_costs.8119bc4b.csv b/assets/data-integration/drug_plan_tier_costs.8119bc4b.csv new file mode 100644 index 0000000..b6c621a --- /dev/null +++ b/assets/data-integration/drug_plan_tier_costs.8119bc4b.csv @@ -0,0 +1,14 @@ +drug_plan_id,pharmacy_benefit_type,drug_tier,cost_type,value,option,applicability,is_deleted +DP-DSNP,1-month-in-retail,preferred-generic,copay,0.00,no-charge,, +DP-DSNP,1-month-in-retail,generic,copay,5.00,charge,, +DP-DSNP,1-month-in-retail,preferred-brand,copay,47.00,charge,, +DP-DSNP,1-month-in-retail,non-preferred-brand,copay,0.00,copay-not-applicable,, +DP-DSNP,1-month-in-retail,non-preferred-brand,coinsurance,25,after-deductible,, +DP-DSNP,1-month-in-retail,specialty,copay,0.00,copay-not-applicable,, +DP-DSNP,1-month-in-retail,specialty,coinsurance,33,charge,, +DP-DSNP,3-month-in-mail,preferred-generic,copay,0.00,no-charge,, +DP-DSNP,3-month-in-mail,generic,copay,10.00,charge,, +DP-DSNP,3-month-in-mail,preferred-brand,copay,94.00,charge,, +DP-ISNP,1-month-in-retail,preferred-generic,copay,0.00,no-charge,, +DP-ISNP,1-month-in-retail,preferred-generic,coinsurance,0,coinsurance-not-applicable,, +DP-ISNP,1-month-in-retail,preferred-brand,copay,45.00,charge,, diff --git a/assets/data-integration/drug_plans.84771d8d.csv b/assets/data-integration/drug_plans.84771d8d.csv new file mode 100644 index 0000000..182473f --- /dev/null +++ b/assets/data-integration/drug_plans.84771d8d.csv @@ -0,0 +1,3 @@ +drug_plan_id,plan_id,identifier_values,identifier_systems,coverage_area_ids,network_ids,is_deleted +DP-DSNP,PLAN-DSNP,H6776-001-000,http://cms.gov/medicare/ma-plan-id,,NET-001, +DP-ISNP,PLAN-ISNP,,,,NET-001, diff --git a/assets/data-integration/formularies.3b50688b.csv b/assets/data-integration/formularies.3b50688b.csv new file mode 100644 index 0000000..88f9278 --- /dev/null +++ b/assets/data-integration/formularies.3b50688b.csv @@ -0,0 +1,4 @@ +formulary_id,formulary_name,formulary_aliases,status,period_start,period_end,owned_by_org_npi,administered_by_org_npi,network_ids,coverage_area_ids,last_updated,is_deleted +FORM-2027-A,Example Health 2027 Part D Formulary,,active,2027-01-01,2027-12-31,9999999993,,NET-001,AREA-NY,2026-10-01T09:00:00-05:00, +FORM-2027-B,Example Health 2027 I-SNP Formulary,,active,2027-01-01,2027-12-31,9999999993,9999999994,NET-001,AREA-NY,2026-10-01T09:00:00-05:00, +FORM-2026-A,Example Health 2026 Part D Formulary,Example Health 2026 Formulary,retired,2026-01-01,2026-12-31,9999999993,,NET-001,AREA-NY,2026-12-31T23:59:00-05:00, diff --git a/assets/data-integration/formularies.e38cbf0b.csv b/assets/data-integration/formularies.e38cbf0b.csv deleted file mode 100644 index dfdf9ec..0000000 --- a/assets/data-integration/formularies.e38cbf0b.csv +++ /dev/null @@ -1,4 +0,0 @@ -formulary_id,cms_formulary_id,formulary_name,formulary_aliases,status,period_start,period_end,owned_by_org_npi,administered_by_org_npi,network_ids,coverage_area_states,formulary_url,last_updated,is_deleted -FORM-2027-A,00027113,Example Health 2027 Part D Formulary,,active,2027-01-01,2027-12-31,9999999993,,NET-001,NY,https://example.org/formularies/form-2027-a.pdf,2026-10-01T09:00:00-05:00, -FORM-2027-B,00027114,Example Health 2027 I-SNP Formulary,,active,2027-01-01,2027-12-31,9999999993,9999999994,NET-001,NY,https://example.org/formularies/form-2027-b.pdf,2026-10-01T09:00:00-05:00, -FORM-2026-A,00026113,Example Health 2026 Part D Formulary,Example Health 2026 Formulary,retired,2026-01-01,2026-12-31,9999999993,,NET-001,NY,https://example.org/formularies/form-2026-a.pdf,2026-12-31T23:59:00-05:00, diff --git a/assets/data-integration/formulary_contacts.b4214da9.csv b/assets/data-integration/formulary_contacts.b4214da9.csv new file mode 100644 index 0000000..87e52e5 --- /dev/null +++ b/assets/data-integration/formulary_contacts.b4214da9.csv @@ -0,0 +1,3 @@ +contact_id,formulary_id,contact_purpose,contact_name,phone,fax,email,url,address_line1,address_line2,city,state,zip,is_deleted +CT-FORM-2027-A-PDF,FORM-2027-A,FORMULARY,2027 Part D formulary,,,,https://example.org/formularies/form-2027-a.pdf,,,,,, +CT-FORM-2027-B-PDF,FORM-2027-B,FORMULARY,2027 I-SNP formulary,,,,https://example.org/formularies/form-2027-b.pdf,,,,,, diff --git a/assets/data-integration/formulary_drugs.47d248a8.csv b/assets/data-integration/formulary_drugs.56874659.csv similarity index 71% rename from assets/data-integration/formulary_drugs.47d248a8.csv rename to assets/data-integration/formulary_drugs.56874659.csv index ebfbb78..14a6093 100644 --- a/assets/data-integration/formulary_drugs.47d248a8.csv +++ b/assets/data-integration/formulary_drugs.56874659.csv @@ -1,4 +1,4 @@ -drug_id,rxnorm_code,rxnorm_form_group_code,rxnorm_display,ndc_codes,gpi_code,status,dose_form_code,dose_form_text,last_updated,is_deleted +drug_id,rxnorm_code,rxnorm_form_group_codes,rxnorm_display,ndc_codes,gpi_code,status,dose_form_code,dose_form_text,last_updated,is_deleted RX-1000091,1000091,1160770,,,,active,,,2026-10-01T09:00:00-05:00, RX-1049640,1049640,1185784,,,,active,,TABLET,2026-10-01T09:00:00-05:00, RX-209459,209459,1187315,,,,active,385055001,,2026-10-01T09:00:00-05:00, diff --git a/assets/data-integration/formulary_identifiers.3815ad2e.csv b/assets/data-integration/formulary_identifiers.3815ad2e.csv new file mode 100644 index 0000000..4f9642c --- /dev/null +++ b/assets/data-integration/formulary_identifiers.3815ad2e.csv @@ -0,0 +1,4 @@ +formulary_id,identifier_value,identifier_system,is_deleted +FORM-2027-A,00027113,http://cms.gov/medicare/formulary-id, +FORM-2027-B,00027114,http://cms.gov/medicare/formulary-id, +FORM-2026-A,00026113,http://cms.gov/medicare/formulary-id, diff --git a/assets/data-integration/payer_plans.a2023674.csv b/assets/data-integration/payer_plans.a2023674.csv deleted file mode 100644 index eb22b1b..0000000 --- a/assets/data-integration/payer_plans.a2023674.csv +++ /dev/null @@ -1,11 +0,0 @@ -plan_id,plan_identifier,drug_plan_id,plan_name,status,plan_type,period_start,period_end,coverage_area_states,owned_by_org_npi,administered_by_org_npi,network_ids,member_phone,marketing_url,summary_url,formulary_url,formulary_ids,pharmacy_benefit_type,drug_tier,copay_amount,copay_option,coinsurance_rate,coinsurance_option,last_updated,is_deleted -PLAN-DSNP,H6776-001-000,,Example Health D-SNP,active,mediadv,2027-01-01,2027-12-31,NY,9999999993,,NET-001,8885551002,https://example.org/plans/dsnp,https://example.org/plans/dsnp/benefits,https://example.org/plans/dsnp/formulary,FORM-2027-A,1-month-in-retail,preferred-generic,0.00,no-charge,,,2026-10-01T09:00:00-05:00, -PLAN-DSNP,H6776-001-000,,Example Health D-SNP,active,mediadv,2027-01-01,2027-12-31,NY,9999999993,,NET-001,8885551002,https://example.org/plans/dsnp,https://example.org/plans/dsnp/benefits,https://example.org/plans/dsnp/formulary,FORM-2027-A,1-month-in-retail,generic,5.00,charge,,,2026-10-01T09:00:00-05:00, -PLAN-DSNP,H6776-001-000,,Example Health D-SNP,active,mediadv,2027-01-01,2027-12-31,NY,9999999993,,NET-001,8885551002,https://example.org/plans/dsnp,https://example.org/plans/dsnp/benefits,https://example.org/plans/dsnp/formulary,FORM-2027-A,1-month-in-retail,preferred-brand,47.00,charge,,,2026-10-01T09:00:00-05:00, -PLAN-DSNP,H6776-001-000,,Example Health D-SNP,active,mediadv,2027-01-01,2027-12-31,NY,9999999993,,NET-001,8885551002,https://example.org/plans/dsnp,https://example.org/plans/dsnp/benefits,https://example.org/plans/dsnp/formulary,FORM-2027-A,1-month-in-retail,non-preferred-brand,,copay-not-applicable,25,after-deductible,2026-10-01T09:00:00-05:00, -PLAN-DSNP,H6776-001-000,,Example Health D-SNP,active,mediadv,2027-01-01,2027-12-31,NY,9999999993,,NET-001,8885551002,https://example.org/plans/dsnp,https://example.org/plans/dsnp/benefits,https://example.org/plans/dsnp/formulary,FORM-2027-A,1-month-in-retail,specialty,,copay-not-applicable,33,charge,2026-10-01T09:00:00-05:00, -PLAN-DSNP,H6776-001-000,,Example Health D-SNP,active,mediadv,2027-01-01,2027-12-31,NY,9999999993,,NET-001,8885551002,https://example.org/plans/dsnp,https://example.org/plans/dsnp/benefits,https://example.org/plans/dsnp/formulary,FORM-2027-A,3-month-in-mail,preferred-generic,0.00,no-charge,,,2026-10-01T09:00:00-05:00, -PLAN-DSNP,H6776-001-000,,Example Health D-SNP,active,mediadv,2027-01-01,2027-12-31,NY,9999999993,,NET-001,8885551002,https://example.org/plans/dsnp,https://example.org/plans/dsnp/benefits,https://example.org/plans/dsnp/formulary,FORM-2027-A,3-month-in-mail,generic,10.00,charge,,,2026-10-01T09:00:00-05:00, -PLAN-DSNP,H6776-001-000,,Example Health D-SNP,active,mediadv,2027-01-01,2027-12-31,NY,9999999993,,NET-001,8885551002,https://example.org/plans/dsnp,https://example.org/plans/dsnp/benefits,https://example.org/plans/dsnp/formulary,FORM-2027-A,3-month-in-mail,preferred-brand,94.00,charge,,,2026-10-01T09:00:00-05:00, -PLAN-ISNP,H6776-002-000,,Example Health I-SNP,active,mediadvhmo,2027-01-01,2027-12-31,NY,9999999993,,NET-001,8885551003,https://example.org/plans/isnp,https://example.org/plans/isnp/benefits,https://example.org/plans/isnp/formulary,FORM-2027-B,1-month-in-retail,preferred-generic,0.00,no-charge,0,coinsurance-not-applicable,2026-10-01T09:00:00-05:00, -PLAN-ISNP,H6776-002-000,,Example Health I-SNP,active,mediadvhmo,2027-01-01,2027-12-31,NY,9999999993,,NET-001,8885551003,https://example.org/plans/isnp,https://example.org/plans/isnp/benefits,https://example.org/plans/isnp/formulary,FORM-2027-B,1-month-in-retail,preferred-brand,45.00,charge,,,2026-10-01T09:00:00-05:00, diff --git a/assets/data-integration/payer_plans.b83c1465.csv b/assets/data-integration/payer_plans.b83c1465.csv new file mode 100644 index 0000000..4a5303b --- /dev/null +++ b/assets/data-integration/payer_plans.b83c1465.csv @@ -0,0 +1,3 @@ +plan_id,plan_name,plan_aliases,status,plan_type,period_start,period_end,coverage_area_ids,owned_by_org_npi,administered_by_org_npi,network_ids,last_updated,is_deleted +PLAN-DSNP,Example Health D-SNP,,active,mediadv,2027-01-01,2027-12-31,AREA-NY,9999999993,,NET-001,2026-10-01T09:00:00-05:00, +PLAN-ISNP,Example Health I-SNP,,active,mediadvhmo,2027-01-01,2027-12-31,AREA-NY,9999999993,,NET-001,2026-10-01T09:00:00-05:00, diff --git a/assets/data-integration/plan_contacts.bcd881a6.csv b/assets/data-integration/plan_contacts.bcd881a6.csv new file mode 100644 index 0000000..1d31ef9 --- /dev/null +++ b/assets/data-integration/plan_contacts.bcd881a6.csv @@ -0,0 +1,7 @@ +contact_id,plan_id,contact_purpose,contact_name,phone,fax,email,url,address_line1,address_line2,city,state,zip,is_deleted +CT-DSNP-MEMBERS,PLAN-DSNP,PATINF,Member Services,8885551002;8885551099,,members@example.org,,123 Main St,,Anytown,NY,12345, +CT-DSNP-MARKETING,PLAN-DSNP,MARKETING,Example Health D-SNP plan page,,,,https://example.org/plans/dsnp,,,,,, +CT-DSNP-SUMMARY,PLAN-DSNP,SUMMARY,Summary of drug benefits,,,,https://example.org/plans/dsnp/benefits,,,,,, +CT-DSNP-FORMULARY,PLAN-DSNP,FORMULARY,2027 Part D formulary,,,,https://example.org/plans/dsnp/formulary,,,,,, +CT-ISNP-MEMBERS,PLAN-ISNP,PATINF,Member Services,8885551003,,,,,,,,, +CT-ISNP-FORMULARY,PLAN-ISNP,FORMULARY,2027 I-SNP formulary,,,,https://example.org/plans/isnp/formulary,,,,,, diff --git a/assets/data-integration/plan_drug_coverages.1d4b69ed.csv b/assets/data-integration/plan_drug_coverages.1d4b69ed.csv new file mode 100644 index 0000000..be4a5c9 --- /dev/null +++ b/assets/data-integration/plan_drug_coverages.1d4b69ed.csv @@ -0,0 +1,3 @@ +coverage_id,plan_id,formulary_ids,network_ids,is_deleted +COV-DSNP-RX,PLAN-DSNP,FORM-2027-A,NET-001, +COV-ISNP-RX,PLAN-ISNP,FORM-2027-B,NET-001, diff --git a/assets/data-integration/plan_identifiers.c61a2825.csv b/assets/data-integration/plan_identifiers.c61a2825.csv new file mode 100644 index 0000000..75f5c63 --- /dev/null +++ b/assets/data-integration/plan_identifiers.c61a2825.csv @@ -0,0 +1,3 @@ +plan_id,identifier_value,identifier_system,is_deleted +PLAN-DSNP,H6776-001-000,http://cms.gov/medicare/ma-plan-id, +PLAN-ISNP,H6776-002-000,http://cms.gov/medicare/ma-plan-id, diff --git a/docs/data-integration/README.md b/docs/data-integration/README.md index edb94a3..0b31752 100644 --- a/docs/data-integration/README.md +++ b/docs/data-integration/README.md @@ -36,4 +36,4 @@ graph LR | [USCDI v3.1 Data](uscdi/README.md) | US Core 6.1.0 | 24 | | [Provider Directory](provider-directory/README.md) | PDex Plan-Net STU 1.2.0 | 4 | | [Claims and Encounters](carin-bb/README.md) | CARIN Blue Button STU 2.1.0 | 10 | -| [Drug Formulary](drug-formulary/README.md) | PDex US Drug Formulary STU 2.1.0 | 4 | +| [Drug Formulary](drug-formulary/README.md) | PDex US Drug Formulary STU 2.1.0 | 16 | diff --git a/docs/data-integration/drug-formulary/README.md b/docs/data-integration/drug-formulary/README.md index f67e977..41c1a3f 100644 --- a/docs/data-integration/drug-formulary/README.md +++ b/docs/data-integration/drug-formulary/README.md @@ -8,16 +8,16 @@ description: >- ## Datasets -Built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). A formulary is the list of drugs a plan pays for, with the tier, cost sharing and coverage rules for each. The IG splits it into four resources, and the feed has one dataset per resource. +Built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). A formulary is the list of drugs a plan pays for, with the tier, cost sharing and coverage rules for each. The IG splits it into four resources plus the locations a plan is offered in; the feed has one dataset per resource, and the payer plan, whose profile nests several repeating structures, is a group of eleven datasets, one per repeating element. | Dataset | US Drug Formulary STU 2.1.0 target profile | |---|---| -| [`payer_plans`](payer-plans.md) | [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) (InsurancePlan), with its coverage area as [Insurance Plan Location](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-InsurancePlanLocation.html) | -| [`formularies`](formularies.md) | [Formulary](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-Formulary.html) (InsurancePlan) | +| [`payer_plans`](payer-plans/README.md) and its ten child datasets | [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) (InsurancePlan), with its coverage areas as [Insurance Plan Location](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-InsurancePlanLocation.html) (Location) | +| [`formularies`](formularies.md), [`formulary_identifiers`](formulary-identifiers.md), [`formulary_contacts`](formulary-contacts.md) | [Formulary](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-Formulary.html) (InsurancePlan) | | [`formulary_drugs`](formulary-drugs.md) | [Formulary Drug](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-FormularyDrug.html) (MedicationKnowledge) | | [`formulary_items`](formulary-items.md) | [Formulary Item](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-FormularyItem.html) (Basic) | -The four fit together this way. A payer plan states its drug benefit as a cost-sharing table, one cell per pharmacy benefit type and drug tier, and points at the formulary it uses. A formulary is a named list for a plan year. A formulary drug is one prescribable product, identified by RxNorm. A formulary item is the row of the list: this drug, on this formulary, in this tier, with these requirements. +They fit together this way. A payer plan states its drug benefit as a cost-sharing table, one cell per pharmacy benefit type and drug tier, points at the formulary it uses, and names its coverage areas and contacts. A formulary is a named list for a plan year. A formulary drug is one prescribable product, identified by RxNorm. A formulary item is the row of the list: this drug, on this formulary, in this tier, with these requirements. ## Data conventions @@ -27,7 +27,7 @@ The four fit together this way. A payer plan states its drug benefit as a cost-s | Delivery | Full snapshot each extract, not deltas. A drug removed during the plan year stays in the snapshot as `retired` with an `availability_end` until the plan year ends, so a member can still see it was covered; a plan or formulary that ended is likewise `retired`. Rows absent from a snapshot are removed. | | Keys | `plan_id`, `formulary_id` and `drug_id` are your identifiers and stay stable across snapshots. A plan that also appears in the [Provider Directory](../provider-directory/README.md#plans) uses the same `plan_id` there, and `*_org_npi` and `network_ids` are keys into that feed's `organizations` and `networks`. | | Codes | Send the code, not the description. Drugs are RxNorm; Payerbox derives every display from its terminology service. | -| Multiple values | `;`-separated, positionally aligned across companion columns. | +| Multiple values | `;`-separated, positionally aligned across companion columns. A repeating structure with fields of its own is a dataset instead, one row per occurrence, keyed to its parent. Free-text lists such as aliases must not contain `;` inside a value; a value that needs one goes in a single-value column or its own row. | | Amounts | Copays are decimal US dollars; coinsurance is a percentage, `0` to `100`, no `%` sign. | | Dates | `YYYY-MM-DD`. | | Not PHI | A formulary is public information and is also served unauthenticated. It carries no member data. | diff --git a/docs/data-integration/drug-formulary/formularies.md b/docs/data-integration/drug-formulary/formularies.md index e1a46e7..3f0eb63 100644 --- a/docs/data-integration/drug-formulary/formularies.md +++ b/docs/data-integration/drug-formulary/formularies.md @@ -13,18 +13,19 @@ Part of the [Drug Formulary](README.md) feed, built to [Da Vinci PDex US Drug Fo |---|---| | [`formularies`](#formularies) | [Formulary](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-Formulary.html) (InsurancePlan) | +The formulary's identifiers and contacts repeat, so they are the datasets [`formulary_identifiers`](formulary-identifiers.md) and [`formulary_contacts`](formulary-contacts.md). + ## formularies One row per formulary. A formulary is a plan-year list; a new plan year is a new row with a new `formulary_id`. -{% file src="../../assets/data-integration/formularies.e38cbf0b.csv" %} +{% file src="../../assets/data-integration/formularies.3b50688b.csv" %} formularies.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| | `formulary_id` | Yes | your stable key; `payer_plans` and `formulary_items` reference it | `FORM-2027-A` | -| `cms_formulary_id` | If Part D | the 8-digit CMS formulary id from your HPMS submission | `00027113` | | `formulary_name` | Recommended | text | `Example Health 2027 Part D Formulary` | | `formulary_aliases` | If renamed | earlier names, `;`-separated, so old searches still find it | | | `status` | Yes | `active`, `draft`, `retired`, `unknown` [publication-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/publication-status%7C4.0.1) | `active` | @@ -33,14 +34,14 @@ formularies.csv Data template with example rows | `owned_by_org_npi` | Recommended | 10 digits; the plan sponsor that issues the formulary; key from `organizations` | `9999999993` | | `administered_by_org_npi` | If different | 10 digits; the PBM or administrator that maintains it; key from `organizations` | `9999999994` | | `network_ids` | If available | pharmacy networks the formulary applies to, keys from Provider Directory `networks`, `;`-separated | `NET-001` | -| `coverage_area_states` | If available | 2-letter USPS states, `;`-separated; `US` for nationwide | `NY` | -| `formulary_url` | Recommended | printable formulary page for this list | `https://example.org/formularies/2027-a.pdf` | +| `coverage_area_ids` | If available | keys from [`coverage_areas`](payer-plans/coverage-areas.md), `;`-separated | `AREA-NY` | | `last_updated` | Yes | datetime the formulary last changed in your system | `2026-10-01T09:00:00-05:00` | | `is_deleted` | If retracting | `true` retracts this row | `true` | -- The profile requires at least one identifier. `formulary_id` becomes it, under the identifier namespace fixed for your engagement, so you do not send a system. `cms_formulary_id` becomes a second identifier for the CMS-assigned id, under the CMS formulary-id system fixed at scoping, since CMS publishes no URI for it. +- The profile requires at least one identifier. `formulary_id` becomes it, under the identifier namespace fixed for your engagement. Every other identifier, such as the CMS formulary id from your HPMS submission, is a row in [`formulary_identifiers`](formulary-identifiers.md) with its own namespace. - A formulary needs a name or an id; both are better. Payerbox sets its type to drug policy and its plan type to drug, which is what marks an InsurancePlan as a formulary rather than a payer plan. -- `owned_by_org_npi`, `administered_by_org_npi` and `network_ids` are the same keys the Provider Directory `plans` dataset uses, so a formulary and the plan that uses it name the same sponsor and networks. `coverage_area_states` follows the `payer_plans` rule: one Location per state, generated by Payerbox. -- `formulary_url` becomes the formulary contact. The IG expects the printed formulary to be reachable from the resource for rules the structured columns cannot carry. +- `owned_by_org_npi`, `administered_by_org_npi` and `network_ids` are the same keys the Provider Directory `plans` dataset uses, so a formulary and the plan that uses it name the same sponsor and networks. `coverage_area_ids` point at the same `coverage_areas` rows the plans use. +- Contacts, including the printable formulary the IG expects to be reachable from the resource, are rows in [`formulary_contacts`](formulary-contacts.md). +- Not collected: `endpoint`, and the Formulary's own `coverage` and `plan` structures. The IG uses the Formulary as an organizing construct; cost sharing lives on the payer plan. These resources are served by [Patient Access](../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/formulary-contacts.md b/docs/data-integration/drug-formulary/formulary-contacts.md new file mode 100644 index 0000000..37b0a8d --- /dev/null +++ b/docs/data-integration/drug-formulary/formulary-contacts.md @@ -0,0 +1,44 @@ +--- +description: >- + Columns for formulary contacts, mapped to the contact element of the US Drug Formulary STU 2.1.0 Formulary profile: one row per contact. +--- + +# Formulary Contacts + +## Datasets + +Part of the [Drug Formulary](README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target element | Cardinality | +|---|---|---| +| [`formulary_contacts`](#formulary_contacts) | `contact` of the [Formulary](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-Formulary.html) | 0..* | + +## formulary_contacts + +One row per contact a formulary publishes, most often the printable formulary document. The columns are the same as [`plan_contacts`](payer-plans/plan-contacts.md), keyed to a formulary instead of a plan. + +{% file src="../../assets/data-integration/formulary_contacts.b4214da9.csv" %} +formulary_contacts.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `contact_id` | Yes | your stable key for the contact | `CT-FORM-2027-A-PDF` | +| `formulary_id` | Yes | key from `formularies` | `FORM-2027-A` | +| `contact_purpose` | Yes | as in [plan contacts](payer-plans/plan-contacts.md#purposes); `FORMULARY` for the printable list | `FORMULARY` | +| `contact_name` | Recommended | text; the name of the office, site or document | `2027 Part D formulary` | +| `phone` | If available | 10 digits; several `;`-separated | | +| `fax` | If available | 10 digits; several `;`-separated | | +| `email` | If available | email addresses, `;`-separated | | +| `url` | If available | web addresses, `;`-separated | `https://example.org/formularies/form-2027-a.pdf` | +| `address_line1` | If available | text | | +| `address_line2` | If available | text | | +| `city` | If available | text | | +| `state` | If available | 2-letter USPS | | +| `zip` | If available | 5 digits, as a string | | +| `is_deleted` | If retracting | `true` retracts this row | `true` | + +- A row needs a `contact_name` or at least one telecom value; otherwise it is rejected. +- The IG expects the printed formulary to be reachable from the resource, for coverage rules the structured formulary items cannot express. Send it as a `FORMULARY` contact with a `url`. + +These resources are served by [Patient Access](../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/formulary-drugs.md b/docs/data-integration/drug-formulary/formulary-drugs.md index 9b1757d..32921b5 100644 --- a/docs/data-integration/drug-formulary/formulary-drugs.md +++ b/docs/data-integration/drug-formulary/formulary-drugs.md @@ -17,15 +17,15 @@ Part of the [Drug Formulary](README.md) feed, built to [Da Vinci PDex US Drug Fo One row per prescribable product on any of your formularies, identified by RxNorm at the strength-and-form level. -{% file src="../../assets/data-integration/formulary_drugs.47d248a8.csv" %} +{% file src="../../assets/data-integration/formulary_drugs.56874659.csv" %} formulary_drugs.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| | `drug_id` | Yes | your stable key for the drug; `formulary_items` reference it. The RxCUI itself is a good key when you list each product once | `RX-1049640` | -| `rxnorm_code` | Yes | RxCUI with term type SCD, SBD, GPCK or BPCK: the ingredient, strength and dose form, branded or not [SemanticDrugVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/SemanticDrugVS%7C2.1.0&server=https://tx.health-samurai.io/fhir) | `1049640` | -| `rxnorm_form_group_code` | Yes for SCD and SBD, blank for packs | RxCUI of the drug's form group, term type SCDG or SBDG: the ingredient and dose form without strength [SemanticDrugFormGroupVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/SemanticDrugFormGroupVS%7C2.1.0&server=https://tx.health-samurai.io/fhir) | `1185784` | +| `rxnorm_code` | Yes | RxCUI with term type SCD, SBD, GPCK or BPCK: the ingredient, strength and dose form, branded or not [SemanticDrugVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/SemanticDrugVS&server=https://tx.health-samurai.io/fhir) | `1049640` | +| `rxnorm_form_group_codes` | Yes for SCD and SBD, blank for packs | RxCUIs of the drug's form groups, term type SCDG or SBDG, `;`-separated: the ingredient and dose form without strength [SemanticDrugFormGroupVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/SemanticDrugFormGroupVS&server=https://tx.health-samurai.io/fhir) | `1185784` | | `rxnorm_display` | No | the RxNorm name; Payerbox derives it, send only to pin a spelling | | | `ndc_codes` | If a specific product | NDCs this row is limited to, `;`-separated, when one RxNorm code has products with different coverage | `00069-0197-30` | | `gpi_code` | If available | 14-digit Medi-Span Generic Product Identifier your formulary system uses for the drug | `21360019000320` | @@ -36,7 +36,8 @@ formulary_drugs.csv Data template with example rows | `is_deleted` | If retracting | `true` retracts this row | `true` | - `rxnorm_code` is the searchable identity of the drug: the IG requires the strength-and-form code (SCD or SBD) or the pack code (GPCK or BPCK), so a member's app can find the exact product prescribed. An ingredient-level RxCUI is rejected. -- `rxnorm_form_group_code` is mandatory whenever the IG's invariant applies: every SCD and SBD drug must also carry its SCDG or SBDG group, which lets a member search without knowing the strength. Packs have no group. Payerbox does not derive the group from the strength code, so send it. +- `rxnorm_form_group_codes` is mandatory whenever the IG's invariant applies: every SCD and SBD drug must also carry its SCDG or SBDG group, which lets a member search without knowing the strength. A branded drug may carry both its branded and its clinical group, hence the list. Packs have no group. Payerbox does not derive the group from the strength code, so send it. +- Not collected: `synonym`, `ingredient`, `productType`, `monograph`, `cost`, `administrationGuidelines`, `medicineClassification`, `regulatory`, `kinetics` and the other clinical elements of MedicationKnowledge. None is must-support in the profile; the formulary describes coverage, not the drug's pharmacology. - The IG lets one RxNorm code appear as several drug rows when products under it are covered differently. Give each its own `drug_id` and list the NDCs it applies to in `ndc_codes`; each becomes an additional coding on the resource. - A drug taken off every formulary is `inactive`, not deleted, for the rest of the plan year. - `dose_form_code` and `dose_form_text` are one FHIR element. Send the SNOMED CT code where your drug file has one; send the text where it has only a label such as `TABLET`, and Payerbox publishes the text. Both may be sent together. @@ -48,7 +49,7 @@ A formulary drug is one MedicationKnowledge whose `code` carries every identifie | Column | Code system published | Note | |---|---|---| | `rxnorm_code` | `http://www.nlm.nih.gov/research/umls/rxnorm` | mandatory; the strength-and-form or pack concept | -| `rxnorm_form_group_code` | `http://www.nlm.nih.gov/research/umls/rxnorm` | mandatory for SCD and SBD; the form-group concept | +| `rxnorm_form_group_codes` | `http://www.nlm.nih.gov/research/umls/rxnorm` | mandatory for SCD and SBD; one coding per form-group concept | | `ndc_codes` | `http://hl7.org/fhir/sid/ndc` | one coding per NDC. Send the NDC in any of its usual forms; Payerbox publishes it under the FHIR NDC system whatever URI your source uses for it | | `gpi_code` | the GPI code system URI agreed at scoping | GPI has no HL7-registered system URI, so the one Payerbox publishes is fixed per engagement and stays stable across snapshots | | `dose_form_code` | `http://snomed.info/sct` | `doseForm.coding`; `dose_form_text` becomes `doseForm.text` | diff --git a/docs/data-integration/drug-formulary/formulary-identifiers.md b/docs/data-integration/drug-formulary/formulary-identifiers.md new file mode 100644 index 0000000..99020df --- /dev/null +++ b/docs/data-integration/drug-formulary/formulary-identifiers.md @@ -0,0 +1,37 @@ +--- +description: >- + Columns for formulary identifiers, mapped to the identifier element of the US Drug Formulary STU 2.1.0 Formulary profile: one row per identifier. +--- + +# Formulary Identifiers + +## Datasets + +Part of the [Drug Formulary](README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target element | Cardinality | +|---|---|---| +| [`formulary_identifiers`](#formulary_identifiers) | `identifier` of the [Formulary](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-Formulary.html) | 1..* | + +The profile requires at least one identifier per formulary. `formulary_id` on the [`formularies`](formularies.md) row is always the first; this dataset carries every other identifier the formulary is known by, each with the namespace it belongs to. + +## formulary_identifiers + +One row per additional identifier of a formulary. + +{% file src="../../assets/data-integration/formulary_identifiers.3815ad2e.csv" %} +formulary_identifiers.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `formulary_id` | Yes | key from `formularies` | `FORM-2027-A` | +| `identifier_value` | Yes | the identifier as issued | `00027113` | +| `identifier_system` | Yes | URI of the namespace that issued it | `http://cms.gov/medicare/formulary-id` | +| `is_deleted` | If retracting | `true` retracts this row | `true` | + +- A row is identified by `formulary_id`, `identifier_system` and `identifier_value` together; there is no separate key. +- The 8-digit CMS formulary id from your HPMS submission is the identifier every Part D formulary should carry here. CMS publishes no URI for it; use one namespace consistently across formularies. +- `formulary_id` itself is not repeated here. It is published as the first identifier automatically. + +These resources are served by [Patient Access](../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/formulary-items.md b/docs/data-integration/drug-formulary/formulary-items.md index 5334645..d66b1e0 100644 --- a/docs/data-integration/drug-formulary/formulary-items.md +++ b/docs/data-integration/drug-formulary/formulary-items.md @@ -28,8 +28,8 @@ formulary_items.csv Data template with example rows | `availability_status` | Yes | `active` covered now, `retired` removed during the year, `draft` not yet effective [publication-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/publication-status%7C4.0.1) | `active` | | `availability_start` | Recommended | date coverage on this formulary began | `2027-01-01` | | `availability_end` | If retired | date coverage ended | `2027-06-30` | -| `pharmacy_benefit_types` | Yes | one or more [pharmacy benefit types](payer-plans.md#pharmacy-benefit-types) the drug is available through, `;`-separated | `1-month-in-retail;3-month-in-mail` | -| `drug_tier` | Yes | one [drug tier](payer-plans.md#drug-tiers) | `preferred-brand` | +| `pharmacy_benefit_types` | Yes | one or more [pharmacy benefit types](payer-plans/drug-plan-specific-costs.md#pharmacy-benefit-types) the drug is available through, `;`-separated | `1-month-in-retail;3-month-in-mail` | +| `drug_tier` | Yes | one [drug tier](payer-plans/drug-plan-tier-benefits.md#drug-tiers) | `preferred-brand` | | `prior_authorization` | Recommended | `true` or `false` | `true` | | `prior_authorization_new_starts_only` | If `prior_authorization` is `true` | `true` when only members starting the drug need authorization | `true` | | `step_therapy` | Recommended | `true` or `false`; another drug must be tried first | `false` | @@ -45,7 +45,7 @@ formulary_items.csv Data template with example rows | `last_updated` | Yes | datetime the item last changed in your system | `2026-10-01T09:00:00-05:00` | | `is_deleted` | If retracting | `true` retracts this row | `true` | -- `pharmacy_benefit_types` and `drug_tier` are mandatory on every item and must be values the drug's plan defines in `payer_plans`. Together with the plan's cost table they are how a member's app computes what a fill costs. +- `pharmacy_benefit_types` and `drug_tier` are mandatory on every item and must be values the drug's plan defines in `drug_plan_specific_costs` and `drug_plan_tier_benefits`. Together with the plan's cost table they are how a member's app computes what a fill costs. - The three requirement flags are must-support; send `false` rather than leaving them blank, so the resource states that no requirement applies. The two new-starts flags matter only when the parent flag is `true` and are dropped otherwise. - The quantity-limit detail columns are optional refinements of `quantity_limit`. Send the text always, and the numbers where your system holds them as data: a rolling limit is units per window, a daily maximum is units per day, a days-supply limit is one fill of at most that many days within the window. Payerbox writes them into the IG's quantity-limit detail extension. - `additional_coverage_information` is published as text a member reads. Do not put structured data there that the columns already carry. diff --git a/docs/data-integration/drug-formulary/payer-plans.md b/docs/data-integration/drug-formulary/payer-plans.md deleted file mode 100644 index 5167461..0000000 --- a/docs/data-integration/drug-formulary/payer-plans.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -description: >- - Columns for payer plans, mapped to the US Drug Formulary STU 2.1.0 Payer Insurance Plan profile: one row per plan, pharmacy benefit type and drug tier. ---- - -# Payer Plans - -## Datasets - -Part of the [Drug Formulary](README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. - -| Dataset | US Drug Formulary STU 2.1.0 target profile | -|---|---| -| [`payer_plans`](#payer_plans) | [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) (InsurancePlan), with its coverage area as [Insurance Plan Location](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-InsurancePlanLocation.html) | - -## payer_plans - -One row per plan, pharmacy benefit type and drug tier. A plan with eight benefit types and five tiers produces up to forty rows; the plan-level columns repeat on each and must agree. Payerbox builds one InsurancePlan per `plan_id` and one cost-sharing entry per row. - -{% file src="../../assets/data-integration/payer_plans.a2023674.csv" %} -payer_plans.csv Data template with example rows -{% endfile %} - -| Column | Required | Format / values | Example | -|---|---|---|---| -| `plan_id` | Yes | your stable key for the plan; the same value as in Provider Directory `plans` | `PLAN-DSNP` | -| `plan_identifier` | If MA | `H#####-###-###`, contract-plan-segment, as in Provider Directory `plans` | `H6776-001-000` | -| `drug_plan_id` | If different | identifier of the drug plan inside the product, used to link a member's Coverage; blank when it equals `plan_id` | | -| `plan_name` | Recommended | text | `Example Health D-SNP` | -| `status` | Yes | `active`, `draft`, `retired`, `unknown` [publication-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/publication-status%7C4.0.1) | `active` | -| `plan_type` | Yes | `mediadv` Medicare Advantage, `mediadvhmo` MA HMO [InsuranceProductTypeVS](https://hl7.org/fhir/us/davinci-pdex-plan-net/STU1.2/ValueSet-InsuranceProductTypeVS.html) | `mediadv` | -| `period_start` | Recommended | date the plan year begins | `2027-01-01` | -| `period_end` | Recommended | date the plan year ends | `2027-12-31` | -| `coverage_area_states` | Recommended | 2-letter USPS states where the plan is offered, `;`-separated; `US` for nationwide | `NY` | -| `owned_by_org_npi` | Recommended | 10 digits; the plan sponsor; key from `organizations` | `9999999993` | -| `administered_by_org_npi` | If different | 10 digits; the administrator or PBM; key from `organizations` | | -| `network_ids` | If available | pharmacy networks of the drug benefit, keys from Provider Directory `networks`, `;`-separated | `NET-001` | -| `member_phone` | Recommended | 10 digits; member services line | `8885551002` | -| `marketing_url` | Recommended | plan marketing page | `https://example.org/plans/dsnp` | -| `summary_url` | Recommended | summary of drug benefits page | `https://example.org/plans/dsnp/benefits` | -| `formulary_url` | Recommended | printable formulary page | `https://example.org/plans/dsnp/formulary` | -| `formulary_ids` | Yes | keys from `formularies`, `;`-separated; one in the usual case | `FORM-2027-A` | -| `pharmacy_benefit_type` | Yes | see [Pharmacy benefit types](#pharmacy-benefit-types) | `1-month-in-retail` | -| `drug_tier` | Yes | see [Drug tiers](#drug-tiers) | `generic` | -| `copay_amount` | Yes, unless `coinsurance_rate` is sent | decimal; flat amount per fill | `5.00` | -| `copay_option` | If `copay_amount` | `after-deductible`, `before-deductible`, `no-charge`, `no-charge-after-deductible`, `charge`, `copay-not-applicable`, `deductible-waived` [CopayOptionVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/CopayOptionVS%7C2.1.0&server=https://tx.health-samurai.io/fhir) | `charge` | -| `coinsurance_rate` | Yes, unless `copay_amount` is sent | percent, `0` to `100` | `25` | -| `coinsurance_option` | If `coinsurance_rate` | `after-deductible`, `no-charge`, `no-charge-after-deductible`, `charge`, `coinsurance-not-applicable`, `deductible-waived` [CoinsuranceOptionVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/CoinsuranceOptionVS%7C2.1.0&server=https://tx.health-samurai.io/fhir) | `after-deductible` | -| `last_updated` | Yes | datetime the plan last changed in your system | `2026-10-01T09:00:00-05:00` | -| `is_deleted` | If retracting | `true` retracts every row of this `plan_id` | `true` | - -- Each row must carry a copay, a coinsurance, or both. The option column says how the amount interacts with the deductible; `copay-not-applicable` and `coinsurance-not-applicable` are how a tier says it has no copay or no coinsurance while still stating the other. Send `0.00` with `no-charge` for a tier that is free. -- The pharmacy benefit types and tiers a plan uses in `payer_plans` are the vocabulary its formulary items may use. A `formulary_items` row whose `drug_tier` or `pharmacy_benefit_types` the plan's cost table does not define is reported. -- `coverage_area_states` is the one place Payerbox creates a resource without a key from you: one Location per state code, named after the state, with the state as its address. `US` yields a single nationwide Location. -- `member_phone` and the three URLs become the plan's contacts, typed member information, marketing, summary and formulary. The IG expects payers to point members at the printed formulary for rules the structured data cannot express. -- The profile requires at least one identifier. `plan_id` becomes it, under the identifier namespace fixed for your engagement. `plan_identifier` becomes a second identifier under the CMS Medicare Advantage plan-id namespace, the same way the Provider Directory publishes it. -- `owned_by_org_npi`, `administered_by_org_npi` and `network_ids` reuse the Provider Directory keys, so the same plan described in both feeds names one sponsor and one set of networks. -- `drug_plan_id` exists for the 2.1.0 link from a member's Coverage to the drug plan inside a product. Send it when your enrollment system identifies the Part D plan separately from the product; otherwise Payerbox uses `plan_id`. - -### Pharmacy benefit types - -`pharmacy_benefit_type` says through which channel and supply length a cost applies. The set is the IG's own [PharmacyBenefitTypeVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/PharmacyBenefitTypeVS%7C2.1.0&server=https://tx.health-samurai.io/fhir), extensible: a plan may add its own codes, and then defines them in a code system Payerbox registers per engagement. - -| Value | Meaning | -|---|---| -| `1-month-in-retail` | 1-month supply, in-network retail pharmacy | -| `1-month-out-retail` | 1-month supply, out-of-network retail pharmacy | -| `1-month-in-mail` | 1-month supply, in-network mail order | -| `1-month-out-mail` | 1-month supply, out-of-network mail order | -| `3-month-in-retail` | 3-month supply, in-network retail pharmacy | -| `3-month-out-retail` | 3-month supply, out-of-network retail pharmacy | -| `3-month-in-mail` | 3-month supply, in-network mail order | -| `3-month-out-mail` | 3-month supply, out-of-network mail order | - -### Drug tiers - -`drug_tier` is the plan's own tier for the drug. The IG ships an example set, [DrugTierVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/DrugTierVS%7C2.1.0&server=https://tx.health-samurai.io/fhir), and expects plans to use their own where these do not fit. Send the code your plan documents use; if it is not one of these, tell us during scoping so the tier is registered. - -| Value | Meaning | -|---|---| -| `preferred-generic` | commonly prescribed generic drugs | -| `generic` | generic drugs that cost more than preferred generics | -| `non-preferred-generic` | generic drugs that cost more than the generic tier | -| `preferred-brand` | brand-name drugs preferred by the plan | -| `brand` | brand-name drugs that cost more than preferred brands | -| `non-preferred-brand` | brand-name drugs that cost more than the brand tier | -| `preferred` | drugs preferred by the plan, where tiers are not split by generic and brand | -| `non-preferred` | drugs that cost more than the preferred tier | -| `specialty` | drugs for complex conditions, generic or brand, often with special handling | -| `zero-cost-share-preventative` | preventive drugs available at no cost | -| `medical-service` | drugs administered by a clinician or in a facility, covered under the medical benefit | - -These resources are served by [Patient Access](../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/payer-plans/README.md b/docs/data-integration/drug-formulary/payer-plans/README.md new file mode 100644 index 0000000..5dde4fd --- /dev/null +++ b/docs/data-integration/drug-formulary/payer-plans/README.md @@ -0,0 +1,80 @@ +--- +description: >- + The payer plan group of the drug formulary feed: one root dataset per InsurancePlan and one child dataset per repeating element of the US Drug Formulary STU 2.1.0 Payer Insurance Plan profile. +--- + +# Payer Plans + +## Datasets + +Part of the [Drug Formulary](../README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +A payer plan is one [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) (InsurancePlan). The profile nests several repeating structures, and every one that may repeat is its own dataset here: the root file carries what occurs once per plan, and each child file carries one repeating element, keyed back to its parent. This mirrors the profile's slices one to one. + +A repeating element is carried one of two ways. A structure with fields of its own is a child dataset, one row per occurrence. A repeating reference, code or short text with no fields of its own is a `;`-separated list column on its parent row. Free-text lists such as aliases must not contain `;` inside a value; a value that needs one goes in a single-value column or its own row. + +| Dataset | Element | Cardinality | Parent | +|---|---|---|---| +| [`payer_plans`](#payer_plans) | InsurancePlan | one per plan | | +| [`plan_identifiers`](plan-identifiers.md) | `identifier` | 1..* | `payer_plans` | +| [`plan_contacts`](plan-contacts.md) | `contact` | 0..*, must support | `payer_plans` | +| [`coverage_areas`](coverage-areas.md) | `coverageArea`, an Insurance Plan Location | 0..*, must support | `payer_plans`, `drug_plans`, `formularies` | +| [`plan_drug_coverages`](drug-coverages.md) | `coverage:drug-coverage` | 1..* | `payer_plans` | +| [`drug_coverage_benefits`](drug-coverage-benefits.md) | `coverage:drug-coverage.benefit:drug-plan` | 1..* | `plan_drug_coverages` | +| [`drug_plans`](drug-plans.md) | `plan:drug-plan` | 1..* | `payer_plans` | +| [`drug_plan_specific_costs`](drug-plan-specific-costs.md) | `plan:drug-plan.specificCost` | 1..* | `drug_plans` | +| [`drug_plan_tier_benefits`](drug-plan-tier-benefits.md) | `plan:drug-plan.specificCost.benefit` | 1..* | `drug_plan_specific_costs` | +| [`drug_plan_tier_costs`](drug-plan-tier-costs.md) | `plan:drug-plan.specificCost.benefit.cost` | 1..* | `drug_plan_tier_benefits` | + +Repeating references and codes that carry no fields of their own stay as `;`-separated lists on their parent row: `network_ids`, `coverage_area_ids`, `formulary_ids`, `plan_aliases`. + +## payer_plans + +One row per plan: the elements of the InsurancePlan that occur once. + +{% file src="../../../assets/data-integration/payer_plans.b83c1465.csv" %} +payer_plans.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `plan_id` | Yes | your stable key for the plan; every child dataset references it, and it is the same value as in Provider Directory `plans` | `PLAN-DSNP` | +| `plan_name` | Recommended | text | `Example Health D-SNP` | +| `plan_aliases` | If renamed | earlier names, `;`-separated | | +| `status` | Yes | `active`, `draft`, `retired`, `unknown` [publication-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/publication-status%7C4.0.1) | `active` | +| `plan_type` | Yes | `mediadv` Medicare Advantage, `mediadvhmo` MA HMO [InsuranceProductTypeVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-pdex-plan-net/ValueSet/InsuranceProductTypeVS%7C1.2.0) | `mediadv` | +| `period_start` | Recommended | date the plan year begins | `2027-01-01` | +| `period_end` | Recommended | date the plan year ends | `2027-12-31` | +| `coverage_area_ids` | Recommended | keys from [`coverage_areas`](coverage-areas.md), `;`-separated | `AREA-NY` | +| `owned_by_org_npi` | Recommended | 10 digits; the plan sponsor; key from `organizations` | `9999999993` | +| `administered_by_org_npi` | If different | 10 digits; the administrator or PBM; key from `organizations` | | +| `network_ids` | If available | networks of the product, keys from Provider Directory `networks`, `;`-separated | `NET-001` | +| `last_updated` | Yes | datetime the plan last changed in your system | `2026-10-01T09:00:00-05:00` | +| `is_deleted` | If retracting | `true` retracts the plan and every child row that references it | `true` | + +- `plan_id` becomes the plan's first identifier, under the identifier namespace fixed for your engagement. Further identifiers, such as the CMS contract-plan-segment, are rows in [`plan_identifiers`](plan-identifiers.md). +- A plan is complete only with its children. The profile requires at least one drug coverage and at least one drug plan with a cost table, so a `payer_plans` row with no `plan_drug_coverages` row or no `drug_plans` row is reported and not published. +- `owned_by_org_npi`, `administered_by_org_npi` and `network_ids` reuse the Provider Directory keys, so the same plan described in both feeds names one sponsor and one set of networks. +- `is_deleted` on the plan retracts the whole tree. Child rows have their own `is_deleted` for retracting one contact, one cost cell or one identifier. + +### How the datasets become the resource + +| Element | Cardinality | Filled from | +|---|---|---| +| `meta.lastUpdated` | 1..1 | `payer_plans.last_updated` | +| `identifier` | 1..* | `plan_id`, then one per `plan_identifiers` row | +| `status`, `type`, `name`, `alias`, `period` | | `payer_plans` columns | +| `ownedBy`, `administeredBy` | | `owned_by_org_npi`, `administered_by_org_npi` | +| `coverageArea` | 0..*, must support | one Insurance Plan Location per `coverage_area_ids` value, from `coverage_areas` | +| `contact` | 0..*, must support | one per `plan_contacts` row | +| `network` | | `network_ids` | +| `coverage:drug-coverage` | 1..* | one per `plan_drug_coverages` row; `type` fixed to drug policy; the formulary-reference extension holds each `formulary_ids` value | +| `coverage:drug-coverage.benefit:drug-plan` | 1..* | one per `drug_coverage_benefits` row; `type` fixed to `drug` | +| `plan:drug-plan` | 1..* | one per `drug_plans` row; `type` fixed to `drug`; `identifier` from `drug_plan_id` | +| `plan:drug-plan.specificCost` | 1..*, must support | one per `drug_plan_specific_costs` row; `category` is the pharmacy benefit type | +| `plan:drug-plan.specificCost.benefit` | 1..*, must support | one per `drug_plan_tier_benefits` row; `type` is the drug tier | +| `plan:drug-plan.specificCost.benefit.cost` | 1..* | one per `drug_plan_tier_costs` row, into the `copay` or `coinsurance` slice by `cost_type` | + +Elements the profile leaves optional and this feed does not collect: `endpoint` and `plan.generalCost` (premiums). + +These resources are served by [Patient Access](../../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/payer-plans/coverage-areas.md b/docs/data-integration/drug-formulary/payer-plans/coverage-areas.md new file mode 100644 index 0000000..d99f4f3 --- /dev/null +++ b/docs/data-integration/drug-formulary/payer-plans/coverage-areas.md @@ -0,0 +1,55 @@ +--- +description: >- + Columns for plan coverage areas, mapped to the US Drug Formulary STU 2.1.0 Insurance Plan Location profile: one row per area a plan or formulary is offered in. +--- + +# Coverage Areas + +## Datasets + +Part of the [Payer Plans](README.md) group of the [Drug Formulary](../README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target profile | +|---|---| +| [`coverage_areas`](#coverage_areas) | [Insurance Plan Location](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-InsurancePlanLocation.html) (Location) | + +## coverage_areas + +One row per geographic area a plan is offered in. A plan sold in one state has one area; a plan sold county by county has one per county. [`payer_plans`](README.md) and [`formularies`](../formularies.md) point at these rows through `coverage_area_ids`. + +{% file src="../../../assets/data-integration/coverage_areas.75383ebd.csv" %} +coverage_areas.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `coverage_area_id` | Yes | your stable key for the area; `payer_plans` and `formularies` reference it | `AREA-NY` | +| `name` | Yes | text; how the area is known | `New York State` | +| `aliases` | If renamed | earlier names, `;`-separated | | +| `status` | Recommended | `active`, `suspended`, `inactive` [location-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/location-status%7C4.0.1) | `active` | +| `type_codes` | If available | roles of the location, `;`-separated, from [ServiceDeliveryLocationRoleType](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://terminology.hl7.org/ValueSet/v3-ServiceDeliveryLocationRoleType) | | +| `phone` | If available | 10 digits; a number for the area, such as a regional member line; several `;`-separated | `8885551002` | +| `fax` | If available | 10 digits; several `;`-separated | | +| `email` | If available | email addresses, `;`-separated | | +| `url` | If available | web addresses, `;`-separated | `https://example.org/areas/ny` | +| `address_line1` | If available | text | | +| `address_line2` | If available | text | | +| `city` | If available | text | | +| `state` | Yes, unless `region_geojson` is sent | 2-letter USPS state the area lies in | `NY` | +| `zip` | If available | 5 digits, as a string | | +| `latitude` | If available | decimal, WGS84; a point inside the area | `42.9538` | +| `longitude` | If available | decimal, WGS84 | `-75.5268` | +| `region_geojson` | If a boundary | the area's boundary as a GeoJSON Feature or geometry, the whole document in one cell, quoted per RFC 4180 | `{"type":"Polygon","coordinates":[[[-74.3,40.5],[-73.7,40.5],[-73.7,40.9],[-74.3,40.9],[-74.3,40.5]]]}` | +| `managing_org_npi` | Recommended | 10 digits; the organization responsible for the area, usually the plan sponsor; key from `organizations` | `9999999993` | +| `last_updated` | Recommended | datetime the area last changed in your system | `2026-10-01T09:00:00-05:00` | +| `is_deleted` | If retracting | `true` retracts this row | `true` | + +- The profile requires an address or a boundary. A state-wide area needs only `state`; a nationwide area sends `state` blank and a boundary. A county or service area sends `region_geojson`, and the address columns describe where it lies. +- `name` is mandatory and is what a member's app shows. Name the area, not the plan: `New York State`, `Bronx County`, `United States`. +- `latitude` and `longitude` are one FHIR element: send both or neither. +- `type_codes` is must-support in the profile but describes the function of a physical site, which a coverage area rarely has. Leave it blank unless your source classifies areas. +- Not collected: `endpoint`, `hoursOfOperation`, `operationalStatus`, `partOf`, and further identifiers beyond `coverage_area_id`. +- `region_geojson` is the boundary itself, not a link to it. Payerbox encodes the cell and publishes it as the data of the boundary attachment the IG defines, typed `application/geo+json`, so the Location is self-contained for bulk export and offline clients. The cell must be valid JSON; a cell that does not parse is rejected. Because GeoJSON contains commas and double quotes, the cell has to be enclosed in double quotes with every inner quote doubled, which every CSV writer does when told to quote the field. +- Keep boundaries as simple as the use allows. A state or county outline of a few hundred points is fine; a parcel-level polygon of tens of thousands is not what a member's app needs and makes the file hard to handle. + +These resources are served by [Patient Access](../../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/payer-plans/drug-coverage-benefits.md b/docs/data-integration/drug-formulary/payer-plans/drug-coverage-benefits.md new file mode 100644 index 0000000..eb99e73 --- /dev/null +++ b/docs/data-integration/drug-formulary/payer-plans/drug-coverage-benefits.md @@ -0,0 +1,38 @@ +--- +description: >- + Columns for the benefits of a drug coverage, mapped to the drug-plan benefit slice of the US Drug Formulary STU 2.1.0 Payer Insurance Plan profile: one row per benefit. +--- + +# Drug Coverage Benefits + +## Datasets + +Part of the [Payer Plans](README.md) group of the [Drug Formulary](../README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target element | Cardinality | +|---|---|---| +| [`drug_coverage_benefits`](#drug_coverage_benefits) | `coverage:drug-coverage.benefit:drug-plan` of the [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) | 1..* | + +The benefit is the profile's statement that the coverage is a drug benefit. Its type is fixed; what you may add is a requirement and limits, the only data the element carries. +## drug_coverage_benefits + +One row per benefit of a drug coverage. Send a row only when you have a requirement or a limit to state; otherwise Payerbox adds the mandatory benefit itself. + +{% file src="../../../assets/data-integration/drug_coverage_benefits.a5ea5fb1.csv" %} +drug_coverage_benefits.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `benefit_id` | Yes | your stable key for the benefit | `BEN-DSNP-RX` | +| `coverage_id` | Yes | key from `plan_drug_coverages` | `COV-DSNP-RX` | +| `requirement` | If available | free text; referral or other requirement for the benefit | `Part D covered drugs only` | +| `limit_values` | If a limit | decimals, `;`-separated, aligned with `limit_units` and `limit_codes` | `90` | +| `limit_units` | If a limit | unit of each limit value, aligned | `days` | +| `limit_codes` | If a limit | what each limit is, aligned; your own code or label | `days-supply` | +| `is_deleted` | If retracting | `true` retracts this row | `true` | + +- `type` is fixed to `drug` and set by Payerbox. +- The three limit columns are one aligned list: position one of each describes the first limit. A limit needs at least a value. + +These resources are served by [Patient Access](../../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/payer-plans/drug-coverages.md b/docs/data-integration/drug-formulary/payer-plans/drug-coverages.md new file mode 100644 index 0000000..55b681b --- /dev/null +++ b/docs/data-integration/drug-formulary/payer-plans/drug-coverages.md @@ -0,0 +1,37 @@ +--- +description: >- + Columns for the drug coverage of a payer plan, mapped to the drug-coverage slice of the US Drug Formulary STU 2.1.0 Payer Insurance Plan profile: one row per coverage. +--- + +# Drug Coverages + +## Datasets + +Part of the [Payer Plans](README.md) group of the [Drug Formulary](../README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target element | Cardinality | +|---|---|---| +| [`plan_drug_coverages`](#plan_drug_coverages) | `coverage:drug-coverage` of the [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) | 1..* | + +A drug coverage is the statement that the plan covers drugs and which formulary lists them. Most plans have exactly one; a plan whose Part D benefit is split across formularies for different groups has one per formulary set. +## plan_drug_coverages + +One row per drug coverage of a plan. + +{% file src="../../../assets/data-integration/plan_drug_coverages.1d4b69ed.csv" %} +plan_drug_coverages.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `coverage_id` | Yes | your stable key for the coverage; `drug_coverage_benefits` references it | `COV-DSNP-RX` | +| `plan_id` | Yes | key from `payer_plans` | `PLAN-DSNP` | +| `formulary_ids` | Yes | keys from [`formularies`](../formularies.md), `;`-separated; one in the usual case | `FORM-2027-A` | +| `network_ids` | If available | pharmacy networks providing this coverage, keys from Provider Directory `networks`, `;`-separated | `NET-001` | +| `is_deleted` | If retracting | `true` retracts this row and its benefits | `true` | + +- `formulary_ids` fills the formulary-reference extension the profile requires on every drug coverage; the profile allows several, which is why it is a list. Each must exist in `formularies`. +- The coverage's `type` is fixed to drug policy and set by Payerbox. +- Every coverage needs at least one [benefit](drug-coverage-benefits.md). Where you send none, Payerbox adds the one bare `drug` benefit the profile demands. + +These resources are served by [Patient Access](../../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/payer-plans/drug-plan-general-costs.md b/docs/data-integration/drug-formulary/payer-plans/drug-plan-general-costs.md new file mode 100644 index 0000000..4500d8a --- /dev/null +++ b/docs/data-integration/drug-formulary/payer-plans/drug-plan-general-costs.md @@ -0,0 +1,39 @@ +--- +description: >- + Columns for the general costs of a drug plan, mapped to the generalCost element of the US Drug Formulary STU 2.1.0 Payer Insurance Plan profile: one row per cost, such as a premium. +--- + +# Drug Plan General Costs + +## Datasets + +Part of the [Payer Plans](README.md) group of the [Drug Formulary](../README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target element | Cardinality | +|---|---|---| +| [`drug_plan_general_costs`](#drug_plan_general_costs) | `plan:drug-plan.generalCost` of the [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) | 0..* | + +A general cost is a cost of the drug plan that is not tied to a drug tier: the premium, a deductible, an out-of-pocket maximum. The profile leaves it optional and unconstrained; it is here because the IG's plan-shopping use case is about comparing exactly these. + +## drug_plan_general_costs + +One row per general cost of a drug plan. + +{% file src="../../../assets/data-integration/drug_plan_general_costs.9c2ffe06.csv" %} +drug_plan_general_costs.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `drug_plan_id` | Yes | key from `drug_plans` | `DP-DSNP` | +| `cost_type` | Yes | your code for the kind of cost, with `cost_type_system`; the profile binds nothing here | `premium` | +| `cost_type_system` | If coded | code system URI of `cost_type`; blank publishes it as text | | +| `group_size` | If available | integer; number of enrollees the cost applies to, for family or group premiums | `1` | +| `amount` | Yes | decimal, US dollars | `0.00` | +| `comment` | If available | free text shown with the amount | `No monthly premium for members with full Medicaid` | +| `is_deleted` | If retracting | `true` retracts this row | `true` | + +- A row is identified by `drug_plan_id`, `cost_type` and `group_size` together. +- `cost_type` has no value set in the profile. Use one vocabulary consistently, such as `premium`, `deductible`, `out-of-pocket-maximum`, and tell us at scoping so it is registered as a code system; otherwise it is published as text. + +These resources are served by [Patient Access](../../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/payer-plans/drug-plan-specific-costs.md b/docs/data-integration/drug-formulary/payer-plans/drug-plan-specific-costs.md new file mode 100644 index 0000000..b7d826b --- /dev/null +++ b/docs/data-integration/drug-formulary/payer-plans/drug-plan-specific-costs.md @@ -0,0 +1,50 @@ +--- +description: >- + Columns for the pharmacy benefit types of a drug plan, mapped to the specificCost element of the US Drug Formulary STU 2.1.0 Payer Insurance Plan profile: one row per pharmacy benefit type. +--- + +# Drug Plan Specific Costs + +## Datasets + +Part of the [Payer Plans](README.md) group of the [Drug Formulary](../README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target element | Cardinality | +|---|---|---| +| [`drug_plan_specific_costs`](#drug_plan_specific_costs) | `plan:drug-plan.specificCost` of the [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) | 1..*, must support | + +A specific cost is one pharmacy benefit type of the drug plan: a channel and supply length, such as a one-month supply at an in-network retail pharmacy. The tiers and their amounts hang below it. +## drug_plan_specific_costs + +One row per pharmacy benefit type of a drug plan. + +{% file src="../../../assets/data-integration/drug_plan_specific_costs.336af84a.csv" %} +drug_plan_specific_costs.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `drug_plan_id` | Yes | key from `drug_plans` | `DP-DSNP` | +| `pharmacy_benefit_type` | Yes | see [Pharmacy benefit types](#pharmacy-benefit-types); becomes `category` | `1-month-in-retail` | +| `is_deleted` | If retracting | `true` retracts this row and the tiers under it | `true` | + +- A row is identified by `drug_plan_id` and `pharmacy_benefit_type` together. +- Every row needs at least one [tier benefit](drug-plan-tier-benefits.md) under it. +- The pharmacy benefit types a drug plan lists here are the ones its formulary items may name in `pharmacy_benefit_types`. + +### Pharmacy benefit types + +`pharmacy_benefit_type` says through which channel and supply length a cost applies. The set is the IG's own [PharmacyBenefitTypeVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/PharmacyBenefitTypeVS&server=https://tx.health-samurai.io/fhir), extensible: a plan may add its own codes, and then defines them in a code system Payerbox registers per engagement. + +| Value | Meaning | +|---|---| +| `1-month-in-retail` | 1-month supply, in-network retail pharmacy | +| `1-month-out-retail` | 1-month supply, out-of-network retail pharmacy | +| `1-month-in-mail` | 1-month supply, in-network mail order | +| `1-month-out-mail` | 1-month supply, out-of-network mail order | +| `3-month-in-retail` | 3-month supply, in-network retail pharmacy | +| `3-month-out-retail` | 3-month supply, out-of-network retail pharmacy | +| `3-month-in-mail` | 3-month supply, in-network mail order | +| `3-month-out-mail` | 3-month supply, out-of-network mail order | + +These resources are served by [Patient Access](../../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/payer-plans/drug-plan-tier-benefits.md b/docs/data-integration/drug-formulary/payer-plans/drug-plan-tier-benefits.md new file mode 100644 index 0000000..347724f --- /dev/null +++ b/docs/data-integration/drug-formulary/payer-plans/drug-plan-tier-benefits.md @@ -0,0 +1,54 @@ +--- +description: >- + Columns for the drug tiers under each pharmacy benefit type, mapped to the specificCost.benefit element of the US Drug Formulary STU 2.1.0 Payer Insurance Plan profile: one row per tier. +--- + +# Drug Plan Tier Benefits + +## Datasets + +Part of the [Payer Plans](README.md) group of the [Drug Formulary](../README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target element | Cardinality | +|---|---|---| +| [`drug_plan_tier_benefits`](#drug_plan_tier_benefits) | `plan:drug-plan.specificCost.benefit` of the [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) | 1..*, must support | + +A tier benefit is one drug tier within one pharmacy benefit type. It has no fields of its own beyond the tier; it exists to hang the copay and coinsurance on. +## drug_plan_tier_benefits + +One row per drug tier under a pharmacy benefit type. + +{% file src="../../../assets/data-integration/drug_plan_tier_benefits.71fa84e0.csv" %} +drug_plan_tier_benefits.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `drug_plan_id` | Yes | key from `drug_plans` | `DP-DSNP` | +| `pharmacy_benefit_type` | Yes | key from `drug_plan_specific_costs`, with `drug_plan_id` | `1-month-in-retail` | +| `drug_tier` | Yes | see [Drug tiers](#drug-tiers); becomes `type` | `generic` | +| `is_deleted` | If retracting | `true` retracts this row and its costs | `true` | + +- A row is identified by `drug_plan_id`, `pharmacy_benefit_type` and `drug_tier` together. +- Every row needs at least one [cost](drug-plan-tier-costs.md) under it. +- The tiers a drug plan lists here are the ones its formulary items may name in `drug_tier`. + +### Drug tiers + +`drug_tier` is the plan's own tier for the drug. The IG ships an example set, [DrugTierVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/DrugTierVS&server=https://tx.health-samurai.io/fhir), and expects plans to use their own where these do not fit. Send the code your plan documents use; if it is not one of these, tell us during scoping so the tier is registered. + +| Value | Meaning | +|---|---| +| `preferred-generic` | commonly prescribed generic drugs | +| `generic` | generic drugs that cost more than preferred generics | +| `non-preferred-generic` | generic drugs that cost more than the generic tier | +| `preferred-brand` | brand-name drugs preferred by the plan | +| `brand` | brand-name drugs that cost more than preferred brands | +| `non-preferred-brand` | brand-name drugs that cost more than the brand tier | +| `preferred` | drugs preferred by the plan, where tiers are not split by generic and brand | +| `non-preferred` | drugs that cost more than the preferred tier | +| `specialty` | drugs for complex conditions, generic or brand, often with special handling | +| `zero-cost-share-preventative` | preventive drugs available at no cost | +| `medical-service` | drugs administered by a clinician or in a facility, covered under the medical benefit | + +These resources are served by [Patient Access](../../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/payer-plans/drug-plan-tier-costs.md b/docs/data-integration/drug-formulary/payer-plans/drug-plan-tier-costs.md new file mode 100644 index 0000000..2630939 --- /dev/null +++ b/docs/data-integration/drug-formulary/payer-plans/drug-plan-tier-costs.md @@ -0,0 +1,41 @@ +--- +description: >- + Columns for the copay and coinsurance of each drug tier, mapped to the cost element of the US Drug Formulary STU 2.1.0 Payer Insurance Plan profile: one row per cost. +--- + +# Drug Plan Tier Costs + +## Datasets + +Part of the [Payer Plans](README.md) group of the [Drug Formulary](../README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target element | Cardinality | +|---|---|---| +| [`drug_plan_tier_costs`](#drug_plan_tier_costs) | `plan:drug-plan.specificCost.benefit.cost` of the [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html), slices `copay` and `coinsurance` | 1..*; each slice 0..1, must support | + +A cost is one amount a member pays for a tier: a flat copay or a coinsurance percentage. The profile slices `cost` into those two, each at most once per tier, so a tier has one or two rows here. +## drug_plan_tier_costs + +One row per cost of a tier. + +{% file src="../../../assets/data-integration/drug_plan_tier_costs.8119bc4b.csv" %} +drug_plan_tier_costs.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `drug_plan_id` | Yes | key from `drug_plans` | `DP-DSNP` | +| `pharmacy_benefit_type` | Yes | with `drug_plan_id` and `drug_tier`, the key of the tier in `drug_plan_tier_benefits` | `1-month-in-retail` | +| `drug_tier` | Yes | see above | `generic` | +| `cost_type` | Yes | `copay` or `coinsurance`; which slice the row fills | `copay` | +| `value` | Yes | decimal; US dollars for a copay, percent `0` to `100` for a coinsurance | `5.00` | +| `option` | Yes | for `copay`: `after-deductible`, `before-deductible`, `no-charge`, `no-charge-after-deductible`, `charge`, `copay-not-applicable`, `deductible-waived` [CopayOptionVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/CopayOptionVS&server=https://tx.health-samurai.io/fhir); for `coinsurance`: `after-deductible`, `no-charge`, `no-charge-after-deductible`, `charge`, `coinsurance-not-applicable`, `deductible-waived` [CoinsuranceOptionVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/CoinsuranceOptionVS&server=https://tx.health-samurai.io/fhir) | `charge` | +| `applicability` | If not implied | `in-network`, `out-of-network`, `other` [insuranceplan-applicability](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/insuranceplan-applicability%7C4.0.1); derived from the `-in-` or `-out-` in the pharmacy benefit type when blank | | +| `is_deleted` | If retracting | `true` retracts this row | `true` | + +- A row is identified by the tier's three keys plus `cost_type`. At most one `copay` and one `coinsurance` row per tier; a second of either is rejected. +- `value` is mandatory on both slices, so a tier with no copay says so with `0.00` and the option `copay-not-applicable`, not by leaving the copay row out; likewise `0` with `coinsurance-not-applicable`. A free tier is `0.00` with `no-charge`. +- `option` is the qualifier the profile requires on every cost: how the amount interacts with the deductible. The allowed values differ by `cost_type`, as listed. +- Payerbox writes the copay as a money quantity in USD and the coinsurance as a percentage, and sets the cost `type` from `cost_type`. + +These resources are served by [Patient Access](../../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/payer-plans/drug-plans.md b/docs/data-integration/drug-formulary/payer-plans/drug-plans.md new file mode 100644 index 0000000..008de2c --- /dev/null +++ b/docs/data-integration/drug-formulary/payer-plans/drug-plans.md @@ -0,0 +1,41 @@ +--- +description: >- + Columns for the drug plans of a payer plan, mapped to the drug-plan slice of the US Drug Formulary STU 2.1.0 Payer Insurance Plan profile: one row per drug plan. +--- + +# Drug Plans + +## Datasets + +Part of the [Payer Plans](README.md) group of the [Drug Formulary](../README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target element | Cardinality | +|---|---|---| +| [`drug_plans`](#drug_plans) | `plan:drug-plan` of the [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) | 1..* | + +A drug plan is the cost-sharing structure offered under a payer plan. A product usually has one; a product sold with several cost-sharing designs has one per design. Its cost table lives in the three datasets below it. +## drug_plans + +One row per drug plan. + +{% file src="../../../assets/data-integration/drug_plans.84771d8d.csv" %} +drug_plans.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `drug_plan_id` | Yes | your stable key for the drug plan; it becomes the drug plan's identifier and links a member's Coverage to it | `DP-DSNP` | +| `plan_id` | Yes | key from `payer_plans` | `PLAN-DSNP` | +| `identifier_values` | If available | further identifiers of the drug plan, `;`-separated, aligned with `identifier_systems` | `H6776-001-000` | +| `identifier_systems` | If `identifier_values` | namespace URI of each, aligned | `http://cms.gov/medicare/ma-plan-id` | +| `coverage_area_ids` | If different from the plan's | keys from [`coverage_areas`](coverage-areas.md), `;`-separated | | +| `network_ids` | If available | pharmacy networks of this drug plan, keys from Provider Directory `networks`, `;`-separated | `NET-001` | +| `is_deleted` | If retracting | `true` retracts the drug plan and its cost table | `true` | + +- `drug_plan_id` is published as the drug plan's identifier, which 2.1.0 made must-support so a member's Coverage can point at the drug plan inside a product. Keep it stable; enrollment data will reference it. +- `type` is fixed to `drug` and set by Payerbox. +- `identifier_values` and `identifier_systems` are one aligned list. They become further `identifier` entries after `drug_plan_id`; the profile marks the drug plan identifier must-support and repeatable. +- Not collected: `plan.generalCost` is its own dataset, [`drug_plan_general_costs`](drug-plan-general-costs.md); nothing else of the drug plan is left out. +- A drug plan needs at least one [specific cost](drug-plan-specific-costs.md); a `drug_plans` row with none is reported and not published. + +These resources are served by [Patient Access](../../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/payer-plans/plan-contacts.md b/docs/data-integration/drug-formulary/payer-plans/plan-contacts.md new file mode 100644 index 0000000..b0943ff --- /dev/null +++ b/docs/data-integration/drug-formulary/payer-plans/plan-contacts.md @@ -0,0 +1,62 @@ +--- +description: >- + Columns for payer plan contacts, mapped to the contact element of the US Drug Formulary STU 2.1.0 Payer Insurance Plan profile: one row per plan contact. +--- + +# Plan Contacts + +## Datasets + +Part of the [Payer Plans](README.md) group of the [Drug Formulary](../README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target element | +|---|---| +| [`plan_contacts`](#plan_contacts) | `InsurancePlan.contact` of the [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) | + +## plan_contacts + +One row per contact a plan publishes: the member services line, the marketing site, the benefit summary, the printable formulary, a billing or press office. A plan has several, so they are rows here rather than columns on [`payer_plans`](README.md). Each row becomes one `contact` entry on the plan's InsurancePlan. + +{% file src="../../../assets/data-integration/plan_contacts.bcd881a6.csv" %} +plan_contacts.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `contact_id` | Yes | your stable key for the contact | `CT-DSNP-MEMBERS` | +| `plan_id` | Yes | key from `payer_plans` | `PLAN-DSNP` | +| `contact_purpose` | Yes | see [Purposes](#purposes) | `PATINF` | +| `contact_name` | Recommended | text; the name of the office, site or document | `Member Services` | +| `phone` | If available | 10 digits; several `;`-separated | `8885551002;8885551099` | +| `fax` | If available | 10 digits; several `;`-separated | | +| `email` | If available | email addresses, `;`-separated | `members@example.org` | +| `url` | If available | web addresses, `;`-separated | `https://example.org/plans/dsnp` | +| `address_line1` | If available | text | `123 Main St` | +| `address_line2` | If available | text | | +| `city` | If available | text | `Anytown` | +| `state` | If available | 2-letter USPS | `NY` | +| `zip` | If available | 5 digits, as a string | `12345` | +| `is_deleted` | If retracting | `true` retracts this row | `true` | + +- A row needs a `contact_name` or at least one of `phone`, `fax`, `email`, `url`; otherwise it describes nothing and is rejected. `contact_name` becomes the contact's name text, each value in the telecom columns one telecom entry of its system, so a contact may list several numbers, and the address columns the contact's address. +- The IG expects three document contacts on every drug plan: the marketing page, the benefit summary and the printable formulary. Members' apps look for them by purpose, so send each as its own row with a `url`. +- Not collected: the contact's structured name parts (`family`, `given`, `prefix`, `suffix`); the profile marks only `name.text` must-support. +- Several rows may share a purpose, for instance two member lines. They all become contacts; the profile does not rank them. + +### Purposes + +`contact_purpose` is bound to [PlanContactTypeVS](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/davinci-drug-formulary/ValueSet/PlanContactTypeVS&server=https://tx.health-samurai.io/fhir), which joins the generic FHIR contact types with three the Formulary IG adds. + +| Value | Contact is | Defined by | +|---|---|---| +| `PATINF` | member information, the member services line | FHIR contact entity type | +| `MARKETING` | the plan's marketing information page | Formulary IG | +| `SUMMARY` | the plan's summary of drug benefits | Formulary IG | +| `FORMULARY` | the plan's printable formulary | Formulary IG | +| `BILL` | billing | FHIR contact entity type | +| `ADMIN` | administrative | FHIR contact entity type | +| `HR` | human resources | FHIR contact entity type | +| `PAYOR` | payor | FHIR contact entity type | +| `PRESS` | press | FHIR contact entity type | + +These resources are served by [Patient Access](../../../interop-apis/patient-access.md). diff --git a/docs/data-integration/drug-formulary/payer-plans/plan-identifiers.md b/docs/data-integration/drug-formulary/payer-plans/plan-identifiers.md new file mode 100644 index 0000000..9dd2823 --- /dev/null +++ b/docs/data-integration/drug-formulary/payer-plans/plan-identifiers.md @@ -0,0 +1,36 @@ +--- +description: >- + Columns for payer plan identifiers, mapped to the identifier element of the US Drug Formulary STU 2.1.0 Payer Insurance Plan profile: one row per identifier. +--- + +# Plan Identifiers + +## Datasets + +Part of the [Payer Plans](README.md) group of the [Drug Formulary](../README.md) feed, built to [Da Vinci PDex US Drug Formulary STU 2.1.0](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/). The feed's data conventions apply. + +| Dataset | US Drug Formulary STU 2.1.0 target element | Cardinality | +|---|---|---| +| [`plan_identifiers`](#plan_identifiers) | `identifier` of the [Payer Insurance Plan](https://hl7.org/fhir/us/davinci-drug-formulary/STU2.1/StructureDefinition-usdf-PayerInsurancePlan.html) | 1..* | + +The profile requires at least one identifier per plan. `plan_id` on the root row is always the first; this dataset carries every other identifier the plan is known by, each with the namespace it belongs to. +## plan_identifiers + +One row per additional identifier of a plan. + +{% file src="../../../assets/data-integration/plan_identifiers.c61a2825.csv" %} +plan_identifiers.csv Data template with example rows +{% endfile %} + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `plan_id` | Yes | key from `payer_plans` | `PLAN-DSNP` | +| `identifier_value` | Yes | the identifier as issued | `H6776-001-000` | +| `identifier_system` | Yes | URI of the namespace that issued it | `http://cms.gov/medicare/ma-plan-id` | +| `is_deleted` | If retracting | `true` retracts this row | `true` | + +- A row is identified by `plan_id`, `identifier_system` and `identifier_value` together; there is no separate key. +- The CMS contract-plan-segment (`H#####-###-###`) is the identifier every Medicare Advantage plan should carry here. Use one namespace URI for it consistently across plans and across the Provider Directory feed, so the two feeds' InsurancePlans match on it. +- `plan_id` itself is not repeated here. It is published as the first identifier automatically. + +These resources are served by [Patient Access](../../../interop-apis/patient-access.md). diff --git a/redirects.yaml b/redirects.yaml index 2344897..5d6b319 100644 --- a/redirects.yaml +++ b/redirects.yaml @@ -15,3 +15,5 @@ redirects: data-integration/clinical/care-team: data-integration/uscdi/care-team.md run-payerbox/provider-directory-pipeline/admin-ui: fhir-app-portal/mpf-publications.md run-payerbox/provider-directory-pipeline/provider-directory-pipeline: run-payerbox/provider-directory-pipeline.md + data-integration/drug-formulary/plan-contacts: data-integration/drug-formulary/payer-plans/plan-contacts.md + data-integration/drug-formulary/coverage-areas: data-integration/drug-formulary/payer-plans/coverage-areas.md