Technical Specification for Health Card Validation (HCV) Service via Electronic Business Services (EBS)

EBS-HCV SOAP Specifications


Date: August 2017

Version 4.3

See also: Version 4.2


Table of Contents



Glossary

Claim Submission Number (CSN) aka Billing Number
A unique identifier that is assigned to a Health Care Provider who is registered with Ministry of Health and Long-Term Care (MOHLTC ) for the purpose of submitting claims for insured services.

The identifier is alphanumeric and is between 5 and 6 characters long. Group billing numbers must begin with a leading zero and adhere to this format: 0[A-Z0-9]{4}.
Health Card Validation (HCV)
Service provided by MOHLTC that checks the status and validity of a health card version, presented to determine an individual's eligibility to health care coverage.
HCV Service Schedule
A Service Schedule to the Master Service agreement that forms part of the Agreement between the Service Requestor and MOHLTC and captures the roles and responsibilities that relate to the HCV via EBS.
Health Care Provider (HCP)
Individual, group or facility authorized to provide health care services to eligible residents of Ontario.
Health Information Custodian (HIC)
Health Information Custodian in or under Personal Health Information Privacy Act (PHIPA).
Health Number (HN)
Health number consists of a 10 digit personal health number. A version code identifies the specific health card of the card holder.
Identity Provider (IDP)
A party or organization that creates, maintains, and manages identity information for principals and performs principal authentication for other parties or organizations.
MOHLTC
The Ontario Ministry of Health and Long-Term Care
MOHLTC Electronic Business Services (EBS)e
The Electronic Business Service is a framework which provides an electronic business gateway that exposes MOHLTC services to the Broader Health Sector and provides a full featured IAM suite of provisioning, business enrolment, business and IT federation agreements, technical specifications and terms of acceptable use governance.
Master Services Agreement
The binding legal agreement through which MOHLTC accepts the identity of an end user at face value based on authenticating the end user's organization at the time of the service request.
Output (Response) Message Fields
Output (Response) Message fields are those fields which are returned by the Health Card Validation (HCV) web service.
Response Code
Code returned in an HCV response identifying the outcome of the transaction – either the eligibility status of the individual if applicable, or an explanatory failure code otherwise.
Service Provider (SP)
Throughout this document, Service Provider refers exclusively to MOHLTC, as the provider of the Health Card Validation service via EBS.
Output (Response) Message Fields
Output (Response) Message fields are those fields which are returned by the Medical Claims Electronic Data Transfer web service.
Simple Object Access Protocol (SOAP)
Simple Object Access Protocol: an Extensible Markup Language (XML)-based protocol for exchanging structured information between computer systems. For more information refer to refer to World Wide Web SOAP
Stakeholder Number (SN)
A unique identifier that is assigned to stakeholders of interest who are registered with the MOHLTC. The unique identifier is either 7 digits long or 8 digits long depending on the type of stakeholder to which it belongs.
UUID
A version 4 Universally Unique Identifier (UUID).
Web Services Description Language (WSDL)
Web Services Description Language: an XML-based language for describing web services and how to access them.
Web Services Security (WS-Security)
An XML based framework for ensuring secure transmission of electronic messages. It will be used for: identification; authentication; and authorization of parties using EBS as well as ensuring message integrity by means of a digital signature applied to each message. For more information refer to: OASIS Web Service Security.

Back to top


Notice to Reader

All possible measures are exerted to ensure the accuracy of the contents of this manual; however, the manual may contain typographical or printing or other errors. The reader is cautioned against complete reliance upon the contents of the manual without confirming the accuracy and currency of the information contained in it. The Crown in Right of Ontario, as represented by the Ministry of Health and Long-Term Care (MOHLTC), assumes no responsibility for errors or omissions in any of the information contained in this manual, or for any person's use of the material therein, or for any costs or damages associated with such use. In no event shall the Crown in Right of Ontario be liable for any errors or omissions, or for any damages including, without limitation, damages for direct, indirect, incidental, special, consequential or punitive damages arising out of or related to the use of information contained in this manual.

This technical specification is intended only to assist and guide the development of software to access the Health Card Validation (HCV) web service via the MOHLTC Electronic Business Services (EBS).

Revisions to the specification will be made as required. The ministry will make every effort to give as much advance noticed as possible of future revisions. It is essential that software developers keep current regarding any changes to this specification. The current version of the technical specification will be available for download.

For further details about HCV via EBS service including enrolment criteria please refer to the Health Card Validation Reference Manual.

Before use of HCV via EBS, please ensure that you conform to the ministry's technical specifications explained in this document and service eligibility criteria outlined in the Health Card Validation Reference Manual.

Please direct any questions to the Service Support Contact Centre at 1-800-262-6524 or SSContactCentre.MOH@ontario.ca

Back to top


Intended Audience for this Technical Specification Document

This document is intended for use by developers of applications and products that support communication with MOHLTC's HCV via EBS (web service interface), a service provided by the ministry to support health card validation. This service is built to the web services standards detailed in this document.

The ministry does not provide any support for automation of the public MCEDT web page.

This document is also intended to be read in the context of either a service agreement between the ministry and the Service Requestor or through an accepted IDP. The service agreement is defined by a Master Service Agreement (MSA) and a Health Card Validation Service Schedule between the ministry and the Service Requestor (SR).

This technical specification is also targeted to vendors of various software applications and products that have or plan to have modules that support HCV through a web service interface within the province of Ontario in Canada.

The document describes the web service, the SOAP message specification and aims to guide the users in the development of client application to integrate with this web service.

It is assumed that the reader has knowledge of web services and related protocols, SOAP and XML message formats/processing, WS-Security 1.1, relevant interoperability profiles and has read the ’MOHLTC EBS – Generic Security Specification‚ document.

Back to top


About this Document

The Ministry of Health and Long-Term Care Health Card Validation (HCV) service allows health care providers (HCP) to validate the eligibility of a health card holder and the status of his or her health card version.

This document is an extension of the “MOHLTC EBS – Generic Security Specification” document and is intended to provide the reader with sufficient information to implement service requestor software that can use the service. The HCV service supports both the Master Services Agreement (MSA) and Identity Provider (IDP) security models.

The introduction provides an overview of the HCV service and provides a glossary of the terminology used throughout the document. Additional functional information and overview of the HCV process is provided in the Health Card Validation Reference Manual.

The Simple Object Access Protocol (SOAP) Message Section provides the technical specifications of the SOAP message including:

  • Message Web Services Description Language;
  • Validation message schema including the request and the response; and
  • Data specifications for fields.

Appendices provide:

  • Response codes;
  • Time Limited Fee Service codes.

Back to top


Introduction

The Health Card Validation service adheres to the EBS security models and as such requires that the ministry unique identifier for Service Requestor (SR) be a Stakeholder Number (SN) and for Service User (SU) be either a SN or a Claim Submission Number (CSN).

Health Card Validation

Each eligible resident of the Province of Ontario that registers for the Ontario Health Insurance Plan (OHIP) is assigned a unique 10-digit health number. A health card is provided to the insured person for the purpose of obtaining insured health services in Ontario. The health card version is identified by a version code. Photo health cards are assigned a two-letter version code; standard “red and white” cards might have no version code, a single letter or a two letter version code. An insured person presents his/her health card at each visit to a health care provider.

Health Care Providers can and should validate this information at the time a health card is presented and prior to the health services being rendered. The health card must be valid and belong to the patient who is presenting it. The HCV service will not, however, guarantee payment of any claim submitted.

Web Service Interface for HCV Service

The Province of Ontario, via the Ministry of Health and Long-Term Care offers EBS to the HCV service for users through third party or client software.

HCV via EBS is being provided in addition to the existing HCV methods.

Back to top


Technical Interface

The Province of Ontario is responsible and accountable for the service provider component.

The service interface uses the SOAP protocol for communication and the WS-Security (WSS) protocol for transaction security. There are several implementations of the WSS protocol available and it is suggested that one of those be used where possible. The following sections assume appropriate headers are included as defined by the “EBS – Generic Security SOAP Specification”.

The results object of the response will be encrypted with the EBS private certificate with the AES128-CBC encryption algorithm and will need to be decrypted by the caller before using the returned data.

SOAP Message:

SOAP is an XML-based standard protocol that defines a message specification for transmitting XML documents via a network. Since this message specification does not depend on a particular programming language or operating system, data transfer can be conducted among and between systems that use different languages or operating systems.

The Message WSDL

A WSDL is a specification for coding web services-related information (access point and interface specifications, etc.) in XML. Note that while WSDL does not define a protocol when sending/receiving messages, the ministry is using SOAP via HTTPS as the protocol for message transmission.

WSDL Definitions Table

The WSDL includes the following standard elements:
Access HCV Web Service URL
Internet Access https://ws.ebs.health.gov.on.ca:1444/HCVService/HCValidationService
ENA Access https://intra.ws.ebs.health.gov.on.ca:1444/HCVService/HCValidationService

The complete EBS-HCV Message WSDL is available upon request.

Back to top


Validation Message Schema

The validation message schema includes definitions of both the request and the response elements. Schema elements are described below, the full schema is available upon request.

The locale parameter for the validate method must be one of empty, spaces, en or fr. If the field is empty or spaces then the English locale will be used for all returning text.

Up to 100 input requests can be submitted at the same time. Within each input request up to 5 fee service codes can be requested.

Data Specifications for Fields

The fields described in the message specification are necessarily generic in order to follow the XML data typing standards. However, in order to pass validation, some of the fields must be presented in the format expected by the ministry.

Input (Request) Message Fields

name="healthNumber" type="xs:string"pattern="[1-9]\d{9}"

The health number is sent to the ministry as a string. The health number is a ten-digit number that appears on the face of every health card.

name="versionCode" type="xs:string"pattern="[A-Z]{0,2}"

Version code is an alphabetic identifier that along with the health number uniquely identifies a health card version. This field appears on the face of all photo cards and some standard (“red and white”) cards. When present on the card, a version code is one letter or two letters.

Optional Fields

maxOccurs="5" minOccurs="0" name="feeServiceCodes" type="xs:string" pattern="[A-Z]\d{3}"

A list of the time limited fee service codes that are to be checked.

The list of supported time limited fee service codes can be found in the HCV reference manual.

Output (Response) Message Fields

The Output Messages identified below have been classed into Mandatory and Optional Response Fields – Category I, Category II and Category III. The output message fields that can be included in the interface you are developing are determined by the type of HCV service you are enrolled for. Please refer to the HCV Reference Manual for details.

Mandatory Fields

The following mandatory fields are returned for each validation request submitted.

name="auditUID" type="xs:string"
pattern="[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}"

The audit UID is an identifier created by the service for each SOAP message processed. The UID returned is a version 4 Universally Unique Identifier (UUID). A UUID is a 16-byte (128-bit) number. In its canonical form, a UUID consists of 32 hexadecimal digits, displayed in 5 groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 digits and 4 hyphens).

Name="responseCode" type="xs:string"

A two character representation of the validation response code for given health number and/or version code. (See ’Response Codes‚ in Appendix A for more details)

Name="responseID" type="xs:responseID"

A mnemonic representation of the validation response code for given health number and/or version code. (See ’Response Codes‚ in Appendix A for more details)

Optional Fields

The following are optional fields and can be returned for each validation request submitted.

Category I

Name="responseAction" type="xs:string"

The action required of the caller for the returned response code.

Name="responseDescription" type="xs:string"

A description for the validation response code for given health number and/or version code.

Category II

name="healthNumber" type="xs:string" pattern="[1-9]\d{9}"

The health number is sent to the ministry as a string. The health number is a ten-digit number that appears on the face of every health card.

name="versionCode" type="xs:string" pattern=" [A-Z]{0, 2}"

Version code is an alphabetic identifier that along with the health number uniquely identifies a health card version. This field appears on the face of all photo cards and some standard (“red and white”) cards. When present on the card, a version code is one letter or two letters.

name="firstName" type="xs:string"

MOHLTC stores this value as upper case characters. A maximum of 20 characters are kept on file. No accents or other diacritic marks are stored or returned.

Name="secondName" type="xs:string"

MOHLTC stores this value as upper case characters. A maximum of 20 characters are kept on file. No accents or other diacritic marks are stored or returned.

Name="lastName" type="xs:string"

MOHLTC stores this value as upper case characters. A maximum of 30 characters are kept on file. No accents or other diacritic marks are stored or returned.

Name="gender" type="xs:string"

The gender is returned as either an M or F, for male or female respectively.

Name="dateOfBirth" type="xs:dateTime"

The card holder's date of birth.

Name="expiryDate" type="xs:dateTime"

The date the card expires.

Category III

name="feeServiceCode" type="xs:string" pattern="[A-Z]\d{3}"

The time limited fee service code passed in to be queried.

name="feeServiceDate" type="xs:dateTime"

The last date the service was issued.

name="feeServiceResponseCode" type="xs:string"

The return code for the requested time limited fee service code. For more details on response codes refer to Appendix B.

name="feeServiceResponseDescription" type="xs:string"

The return code for the requested time limited fee service code.

Testing

Conformance testing must be completed for HCV. For more details please refer to the Testing section in the “MOHLTC EBS – Generic Security Specification” document.

Samples of the Message Request and Message Response are available upon request.

Back to top


Appendix A: Response Codes

Character based response codes are returned as well as character constants for Response IDs to provide more information to developers what codes and data has been returned. All response codes are two characters.

The following is an overview of valid response codes:

  • between 00 and 49 indicates the health card is invalid; cardholder not eligible
  • between 50 and 59 indicates a valid health card; cardholder is eligible
  • between 60 and 89 indicates health card is invalid; cardholder is eligible

The following are the constants that will be returned and their mapping to character based response codes and comments about their use.

Response Code Response ID Descriptive Text Comments
05 NOT_10_DIGITS The Health Number submitted is not 10 numeric digits Response Code is returned but no Personal Characteristics are available.
10 FAILED_MOD10 The Health Number submitted does not exist on the ministry's system. Response Code is returned but no Personal Characteristics are available.
15 IS_IN_DISTRIBUTED_STATUS Pre-assigned newborn Health Number. Response Code is returned but no Personal Characteristics are available.
20 IS_NOT_ELIGIBLE Eligibility does not exist for this Health Number.  
20 IS_NOT_ELIGIBLE_ND Eligibility does not exist for this Health Number. Response Code is returned but no Personal Characteristics are available.
20 IS_NOT_ELIGIBLE_ND Eligibility does not exist for this Health Number. Response Code is returned but no Personal Characteristics are available.
50 NOT_ON_ACTIVE_ROSTER Health card passed validation.  
50 NOT_ON_ACTIVE_ROSTER_ND Health card passed validation. Response Code is returned but no Personal Characteristics are available.
51 IS_ON_ACTIVE_ROSTER Health card passed validation.  
51 IS_ON_ACTIVE_ROSTER_ND Health card passed validation. Response Code is returned but no Personal Characteristics are available.
52 HAS_NOTICE Health card passed validation.  
52 HAS_NOTICE_ND Health card passed validation. Response Code is returned but no Personal Characteristics are available.
53 IS_RQ_HAS_EXPIRED Health card passed validation; card is expired.  
53 IS_RQ_HAS_EXPIRED_ND Health card passed validation card is expired. Response Code is returned but no Personal Characteristics are available.
53 IS_THC Health card passed validation; card is expired.  
53 IS_THC_ND Health card passed validation; card is expired. Response Code is returned but no Personal Characteristics are available.
54 IS_RQ_FUTURE_ISSUE Health card passed validation; card is future dated.  
54 IS_RQ_FUTURE_ISSUE_ND Health card passed validation; card is future dated. Response Code is returned but no Personal Characteristics are available
55 RETURNED_MAIL Health card passed validation; cardholder required to update address with ministry.  
55 RETURNED_MAIL_ND Health card passed validation; cardholder required to update address with ministry. Response Code is returned but no Personal Characteristics are available.
65 INVALID_VERSION_CODE Invalid version code  
65 INVALID_VERSION_CODE_ND Invalid version code Response Code is returned but no Personal Characteristics are available.
70 IS_STOLEN Health card reported stolen.  
70 IS_STOLEN_ND Health card reported stolen. Response Code is returned but no Personal Characteristics are available.
75 IS_CANCELLED_OR_VOIDED Health card cancelled or voided.  
75 IS_CANCELLED_OR_VOIDED_ND Health card cancelled or voided. Response Code is returned but no Personal Characteristics are available.
75 IS_VOID_NEVER_ISS Health card cancelled or voided.  
75 IS_VOID_NEVER_ISS_ND Health card cancelled or voided. Response Code is returned but no Personal Characteristics are available.
80 DAMAGED_STATE Health card reported damaged.  
80 DAMAGED_STATE_ND Health card reported damaged. Response Code is returned but no Personal Characteristics are available.
83 LOST_STATE Health card reported lost.  
83 LOST_STATE_ND Health card reported lost. Response Code is returned but no Personal Characteristics are available.
90 INFO_NOT_AVAIL Information is not available.  

Back to top


Appendix B: Time Limited Fee Service Code – Return Codes

Code Description
101 No information available
102 Invalid Fee Service Code
201 Oculo-visual assessment or major eye exam performed
202 Bone mineral density measurement performed
203 Sleep study performed
99 System unavailable

Refer to the HCV Reference Manual for more details.

Appendix C: Error Codes

Character based error codes are returned as well as textual descriptions of the error.

All ministry specific error codes are 9 characters.

EBS Fault Codes Error Comments
SMIDL0100 System not initialized correctly; contact your technical support or software vendor.
SMIDL0203 Service is not available; contact your technical support or software vendor.
SMIDL0204 General System Error; contact your technical support or software vendor.

Back to top


Image:Pdf icon.gif To view PDF format files, you need to have Adobe Acrobat® Reader installed on your computer.
You can download this free software from the Adobe Web site.

For More Information

Call the Service Support Contact Centre (SSCC) at: 1-800 262-6524
Hours of operation: 8:00 a.m. – 5:00 p.m. Monday – Friday, except holidays
E-mail: SSContactCentre.MOH@ontario.ca