Universal API Implementation Guide
1.1.20 - ci-build

Universal API Implementation Guide - Local Development build (v1.1.20) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Copay Mapping

A Copay enrollment request FHIR bundle consists of information requested by Copay administrators and also includes data elements required by FHIR.

  • Use the mapping tables below and the sample request payload when creating a Copay request bundle.
  • Italicized items are information that are not required by Copay administrators but are required by FHIR.

MAPPING - COPAY ENROLLMENT REQUEST

Required Data Elements for FHIR Bundle

Data Element Required? FHIR Resource-Data Element Format /
Accepted Values
Source Required MessageHeader.source.name Vendor_Annexus
Vendor_PXT
Vendor_TailorMed
Vendor_GNEBrandsite
Vendor_GNEPACT
Vendor_GNEMPS
Enroll by ID Required Task.input.valueCodeableConcept.coding.code(enroll-by-id)

Task.input.type.valueCodeableConcept.coding.display
 Refer to UAPI Code System: Copay Who Is Applying
BrandId Required Task.input.valueCodeableConcept.coding.code(brandId) Refer to UAPI Code System: Copay Brand ID


Patient Information

Copay Administrator Field Name Value Required? Resource-ElementID Business Rules/
Field Length Max		 Format /
Accepted Values
Patient identifier Optional Patient.identifier.value
where Patient.type.coding.code = 'PI'		    
First name Required Patient.name.given string, < = 100 characters  
Last name Required Patient.name.family string, <= 100 characters  
Birth date Required Patient.birthDate YYYY-MM-DD
Date of Birth must be later than January 1, 1900		 Date
Gender Optional Patient.gender case sensitive
string		 male
female
other
Address Required Patient.address.line <= 200 characters  
Address2 Optional Patient.address.line <= 200 characters  
City Required Patient.address.city <= 200 characters  
State Required Patient.address.state Standard 2 character State abbreviation  
Zip code Required Patient.address.postalcode 5 characters  
Phone number Required Patient.telecom.value(system = phone) XXXXXXXXXX, = 10 characters Phone Number
Phone type Required Patient.telecom.use(system = phone)   home
mobile
Email address Optional Patient.telecom.value(system = email) <= 100 characters Standard email validations. Something@domain.com
*Email type FHIR requirement Patient.telecom.use(system = email) FHIR requirement *Email type is only required if an email is provided
Preferred language Required by FHIR Patient.communication.language.coding.code
Patient.communication.language.coding.code.display		 FHIR requirement Default to
Patient.communication.language.coding.code= en
Patient.communication.language.coding.code.display = English


Legally Authorized Person (LAP) Information

*List of relationship codes can be found HERE

Copay Administrator Field Name Value Required? Resource-ElementID Business Rules/
Field Length Max		 Format /
Accepted Values		  
*Relationship to Patient Required if LAP is provided RelatedPerson.relationship.coding This value is not passed to CRX, but required in FHIR bundle Default to
RelatedPerson.relationship.coding.code= SIGOTHR
RelatedPerson.relationship.coding.display=significant other
OR
RelatedPerson.relationship.coding.code= FAMMEMB
RelatedPerson.relationship.coding.display=family member		  
First name Required if LAP is provided RelatedPerson.name.given < = 100 characters    
Last name Required if LAP is provided RelatedPerson.name.family < = 100 characters    
Address Required if LAP is provided RelatedPerson.address.line <= 200 characters    
Address2 Optional Patient.address.line <= 200 characters>    
City Required if LAP is provided RelatedPerson.address.city <= 200 characters    
State Required if LAP is provided RelatedPerson.address.state Standard 2 character State abbreviation    
Zip code Required if LAP is provided RelatedPerson.address.postalCode 5 characters    
Phone number Required if LAP is provided RelatedPerson.telecom.value(system = phone) XXXXXXXXXX, = 10 characters Phone Number  
Phone type Required if LAP is provided RelatedPerson.telecom.use(system = phone)   Home
Mobile		  


Prescriber

Copay Administrator Field Name Value Required? FHIR Resource-Data Element Business Rules/
Field Length Max		 Format /
Accepted Values
First name Required Practitioner.name.given < = 100 characters  
Last name Required Practitioner.name.family < = 100 characters  
Address Required Practitioner.address.line < = 200 characters  
Address 2 Optional Practitioner.address.line < = 200 characters  
City Required Practitioner.address.city < = 200 characters  
State Required Practitioner.address.state Standard 2 character State abbreviation  
Zip code Required Practitioner.address.postalCode = 5 characters  
Phone number Required Practitioner.telecom.value(system = phone) XXXXXXXXXX, = 10 characters Phone number
National Provider Identifier (NPI) Optional Practitioner.identifier.value (type.coding.code= NPI) = 10 characters  


Practice (Site of Care)

Copay Administrator Field Name Value Required? FHIR Resource-Data Element Business Rules/
Field Length Max		 Format /
Accepted Values
Practice Name Required if Practice is selected Organization.name
Organization.identifier.assigner.display		 < = 100 characters  
Address Required if Practice is provided Organization.address.line < = 200 characters  
Address 2 Optional Organization.address.line < = 200 characters  
City Required if Practice is provided Organization.address.city < = 200 characters  
State Required if Practice is provided Organization.address.state Standard 2 character State abbreviation  
Zip code Required if Practice is provided Organization.address.postalCode = 5 characters  
Phone number Required by FHIR Organization.telecom.value(system = phone) FHIR requirement Required if practice is provided
National Provider Identifier (NPI) Optional Organization.identifier.value (type.coding.code=NPI) = 10 characters  


Commercial Medical Insurance Information (where Coverage.type.coding.code = 'HIP')

Copay Administrator Field Name Value Required? FHIR Resource-Data Element Business Rules/
Field Length Max		 Format /
Accepted Values		  
Insurance company name Required Organization.name < = 250 characters    
Insurance plan type Required Coverage.class.value(type.code = plan) < = 100 characters    
Insurance group number Required Coverage.class.value(type.code = group) 10-20 characters    
Insurance member number Required Coverage.subscriberId 9-12 characters    
Insurance effective date Required Coverage.period.start YYYY-MM-DD Date  
BIN Optional Coverage.class.value(type.code = rxbin) < = 6 characters    
PCN Optional Coverage.class.value(type.code = rxpcn) < = 10 characters    
Subscriber Required by FHIR Coverage.subscriber.reference
Coverage.subscriber.type		 Describes the subscriber to the policy (the Patient or RelatedPerson) reference: the uuid of the subscriber (patient uuid or relatedperson uuid)
type: the patient or related person		  
Beneficiary Required by FHIR Coverage.beneficiary.reference
Coverage.beneficiary.type		 Beneficiary will always be Patient reference: patient uuid
type: patient		  


Commercial Pharmacy Insurance Information (where Coverage.type.coding.code = 'DRUGPOL')

If a patient has pharmacy (prescription) insurance and the insurance company name is provided, then BIN and PCN are required. Otherwise, the entire pharmacy insurance section should be excluded from the enrollment bundle.

Copay Administrator Field Name Value Required? FHIR Resource-Data Element Business Rules/
Field Length Max		 Format /
Accepted Values		  
Insurance company name Required Organization.name < = 250 characters    
Insurance effective date Required Coverage.period.start YYYY-MM-DD Date  
BIN Required Coverage.class.value(type.code = rxbin) < = 6 characters    
PCN Required Coverage.class.value(type.code = rxpcn) < = 10 characters    
Subscriber Required by FHIR Coverage.subscriber.reference
Coverage.subscriber.type		 Describes the subscriber to the policy (the Patient or RelatedPerson) reference: the uuid of the subscriber (patient uuid or relatedperson uuid)
type: the patient or related person		  
Beneficiary Required by FHIR Coverage.beneficiary.reference
Coverage.beneficiary.type		 Beneficiary will always be Patient reference: patient uuid
type: patient		  


MAPPING - COPAY ENROLLMENT RESPONSE

A Copay enrollment response FHIR bundle consists of the enrollment results from the Copay administrators and also includes data elements required by FHIR. The mapping tables below should be used in interpreting the Copay administrator response.


Copay Administrator Field Name FHIR Resource-Data Element Comments
Status ExplanationOfBenefit.status This value refers to patient eligibility.
If status = active, then enrollment is accepted
If status = cancelled, then enrollment is rejected
Request ID Bundle.identifier.system(http://connectiverx.com/requestId)  
Trace ID MessageHeader.response.identifier  
Confirmation ID Patient.identifier This identifier operates at the portfolio level.

For example: If a patient enrolls in Vabysmo and Lucentis on different dates, the Confirmation# will be the same in each response bundle since these products are in the same portfolio. Conversely, if the same patient enrolls in a BioOncology Copay program, a new Confirmation# will be issued for that patient.
MemberID Coverage.subscriberId  
Group Number Coverage.class.value where type.coding.code = group  
RX BIN Coverage.class.value where type.coding.code = rxbin  
RX PCN Coverage.class.value where type.coding.code = rxpcn  
Brand Coverage.class.value where type.coding.code = plan Indicates the brand. If enrollment was for a brand that has both drug & admin copay, then each program would be listed seperately.
Example:
'Vabysmo-Drug'
'Ophthalmology-Admin'
Program Coverage.class.name where type.coding.code = plan  
Enrollment Date ExplanationOfBenefit.created Date of enrollment
Eligibility Start Date Coverage.period.start Date set to 180 days preceding enrollment date
Expiration Date Coverage.period.end Date when membership expires. This is an arbitrary future date provided by Copay Administrators.
Issued Date Coverage.extension.valueDate Date when membership is issued


Copay Response when Multiple Brand Ids are Included in Copay Request

  • If the enrollment request is for a single drug with both drug and admin copay programs, the FHIR response will list each program under separate Coverage resourceTypes, each with its own membership information.

Example Response Bundle: Enrollment Response for Single Product with Multiple Brand Ids


| Product/Program| Plan Name
(in bundle) | Info Included Under Coverage resourceType for Each Plan | | :— | :— | :— | | Vabysmo Drug | Vabysmo-Drug | MemberId
Group#
BIN
PCN
Coverage Start & End Date | | Vabysmo Admin | Ophthalmology-Admin | MemberId
Group#
BIN
PCN
Coverage Start & End Date |


  • If the enrollment request is for 2 or more drugs (combo therapy), the FHIR response will list each drug under separate Coverage resourceTypes, each with its own membership information.
Product/Program Plan Name Info Included Under Coverage resourceType for Each Plan  
Gazyva Gazyva drug copay MemberId
Group#
BIN
PCN
Coverage Start & End Dates		  
Venclexta Venclexta drug copay MemberId
Group#
BIN
PCN
Coverage Start & End Dates


What Happens When an Enrollment is Rejected

When a Copay enrollment is denied, the Copay Response will include ExpanationOfBenefit.status = 'cancelled'.

Several things will occur:

  1. A Confirmation ID will still be provided.
  2. Membership information, ie MemberId, Group#, BIN, PCN Eligibiltiy Start/End Dates will not be provided.
  3. OperationOutcome resourceType displaying an error message will be contained under the ExplanationOfBenefit resource.
  4. When a Copay enrollment is denied, an OperationOutcome with one of these 2 messages will be displayed.

If the enrollment fails the Copay administrator's validations, the following messages will be displayed based on the specific issue:

  • identification-check: This message will be displayed if the Copay administrator is unable to validate that the patient is a real person. The message will be: "Provided patient information does not meet minimum criteria for verification."
  • patient-coverage: This message will be displayed if the Copay administrator determines that the patient has Medicare/Medicaid. The message will be: "MEDICARE, MEDICAID AND OTHER FED GOVT INSURED PATIENTS ARE NOT ELIGIBLE FOR THIS OFFER. CALL [phone number will be provided based on drug], MON-FRI 8am-8pm ET TO CONFIRM AND PROVIDE ADDITIONAL COMMERCIAL COVERAGE DETAILS."

Example of OperationOutcome message for Copay enrollment being denied due to failing patient validation:

    "resource": {
              "resourceType": "ExplanationOfBenefit",
              "id": "e344813d-eb60-466e-806b-ebd35c988293",
              "contained": [
                {
                  "resourceType": "OperationOutcome",
                  "id": "5ce061a8-302e-4135-a300-f68c73f31100",
                  "issue": [
                    {
                      "severity": "error",
                      "code": "processing",
                      "details": {
                        "coding": [
                          {
                            "system": "https://fhir.developer.gene.com/CodeSystem/uapi-copay-enrollment-error",
                            "code": "identification-check",
                            "display": "Identification Check"
                          }
                        ],
                        "text": "Provided patient information does not meet minimum criteria for verification."
                      }