Universal API Implementation Guide
1.1.19 - ci-build
Universal API Implementation Guide - Local Development build (v1.1.19). See the Directory of published versions
A Copay enrollment request FHIR bundle consists of information requested by Copay administrators and also includes data elements required by FHIR.
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 |
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 |
*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 |
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 |
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 |
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 |
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 |
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.
Response when Multiple Brand Ids are Included in Request
Examples: Example of Enrollment Request with Multiple Brand Ids
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 | |
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 | |
Expiration Date | Coverage.period.end | Date when membership expires |
Issued Date | Coverage.extension.valueDate | Date when membership is issued |
When an enrollment is rejected, ExpanationOfBenefit.status = ‘cancel’.
Several things will occur:
There are 2 types of failure outcomes that can occur:
"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."
}