MCE FMNB API
All FMNB web services will be implemented using REST and returning a JSON response.
Note with the nature of JSON the order of the elements being returned cannot be guaranteed
and should not affect the processing of the response.
The FMNB Web Services accept four HTTP headers. Some are required. These are:
- Content-Type: Required (content negotiation). No assumptions are made in the content type of the request. Accepted formats: application/json
- Accept: Optional (content negotiation). Acceptable content types for the response. Accepted formats: application/json. JSON is the default response format
- emr_id: Required. The EMR/ORG ID of the vendor. If not provided an authorization error response is returned
- token: Required. A security token provided to the vendor
The registerRosterEvent WS enables the EMR to send a roster status update request, or a “roster event”, for a specific patient and provider and receive a response as to whether the Roster Registry accepted the roster status update request. This could affect the roster relationship between the patient and provider, and changes are subject to the current roster status of the patient with the provider prior to the request.
Unique identifier for this request. Duplicate requests for the same GUID value will be ignored.
Type: String (GUID)
Required: Yes
The date and time the request was sent to Medicare for processing. This value must come from a single source for all requests (e.g. based on the local time the request was queued). All date time values must be supplied in AST.
Type: yyyyMMdd HHmmssSSS formatted String (0000 – 2359)
Required: Yes
The new patient roster status.
Type: Enum
Required: Yes
Valid Values: For a list of roster status codes for submission refer to api/OpenDataGateway?name=FMNB_ROSTER_STATUS
Reason for request to roster exception.
Type: Enum
Required if the rosterStatusCode is EXCEPTION (Roster Exception).
Valid Values: For a list of reason codes for submission refer to api/OpenDataGateway?name= FMNB_ROSTER_EXCEPTION_REASON
The service provider id for the event.
Type: Long
Required: Yes
The Medicare Number of the patient to roster.
Type: Long
Required: Yes
The GUID of the processed request.
Type: String (GUID)
The status of the request.
Type: String
Valid Values: PROCESSED|REJECTED|ERROR
N number of message elements.
Type: List<Message>
See Service Messages.
Container of Resident (patient) demographic and roster information.
Type: Resident
POST https://dhmedapsb1.gnb.ca:8443/NBDHWeb/rest/DE-ID/FMNB/registerRosterEvent
{
"eventId": "DD952221-0173-4E82-8CF1-D2031DBA35CE",
"eventDateTime": "20231212 20151021574",
"rosterStatusCode": "ROSTERED",
"serviceProviderId": "40001",
"medicareNumber": "111133363"
}
{
"serviceProviderId": 40001,
"resident": {
"dob": "20190101",
"medicareNumber": 111133363,
"gender": "M",
"rosterEntries": [
{
"effectiveDate": "20190320",
"rosterStatus": "ROSTERED",
"terminationDate": "20190531",
"reasonCode": ""
},
{
"effectiveDate": "20190531",
"rosterStatus": "DEROSTERED",
"terminationDate": "20190814",
"reasonCode": ""
},
{
"effectiveDate": "20190821",
"rosterStatus": "ROSTERED",
"terminationDate": "20190829",
"reasonCode": ""
},
{
"effectiveDate": "20190829",
"rosterStatus": "REFUSED",
"terminationDate": "20190905",
"reasonCode": ""
},
{
"effectiveDate": "20190905",
"rosterStatus": "ROSTERED",
"terminationDate": "20190905",
"reasonCode": ""
},
{
"effectiveDate": "20190905",
"rosterStatus": "DEROSTERED",
"terminationDate": "20191011",
"reasonCode": ""
},
{
"effectiveDate": "20191114",
"rosterStatus": "EXCEPTION",
"terminationDate": "20200207",
"reasonCode": "2"
},
{
"effectiveDate": "20200207",
"rosterStatus": "ROSTERED",
"terminationDate": "20200210",
"reasonCode": ""
},
{
"effectiveDate": "20200210",
"rosterStatus": "DEROSTERED",
"terminationDate": "20200330",
"reasonCode": ""
},
{
"effectiveDate": "20231212",
"rosterStatus": "ROSTERED",
"terminationDate": "99991231",
"reasonCode": ""
}
],
"rosterMessages": [
{
"code": 18,
"enDescription": "STATUS UPDATE REQUESTED ON 20190905 FROM REFUSE TO ROSTER TO DE-ROSTERED IS INVALID.",
"frDescription": "MISE À JOUR DU STATUT NÉCESSAIRE POUR LE 20190905 DE REFUS D'INSCRIRE SUR LA LISTE À DÉSINSCRIT EST INCORRECTE."
},
{
"code": 18,
"enDescription": "STATUS UPDATE REQUESTED ON 20200203 FROM ROSTER EXCEPTION TO UNDECIDED IS INVALID.",
"frDescription": "MISE À JOUR DU STATUT NÉCESSAIRE POUR LE 20200203 DE EXCEPTION DE LISTE À NON DÉCIDÉ EST INCORRECTE."
}
]
},
"status": "PROCESSED",
"messages": [],
"eventId": "DD952221-0173-4E82-8CF1-D2031DBA35CE"
}
The getRosterability WS enables the EMR to send a roster eligibility request for a specific patient and provider and receive a response containing whether the patient is eligible to be rostered to that provider. This response needs to be displayed to the EMR User immediately.
Unique identifier for this request. Duplicate requests for the same GUID value will be ignored.
Type: String (GUID)
Required: Yes
The service provider id for the event.
Type: Long
Required: Yes
The Medicare Number of the patient for the check.
Type: Long
Required: Yes
The GUID of the processed request.
Type: String (GUID)
The status of the request.
Type: String
Valid Values: PROCESSED|REJECTED|ERROR
The service provider id of the request.
Type: Long
N number of message elements.
Type: List<Message>
See Service Messages.
True if the patient can be rostered to this provider, false otherwise.
Type: Boolean
GET https://dhmedapsb1.gnb.ca:8443/NBDHWeb/rest/DE-ID/FMNB/getRosterability?eventId=52313642-95FE-4031-A612-86DE14AAF0B3&eventDateTime=20231023 20151021574&serviceProviderId=40001&medicareNumber=200000610
{
"serviceProviderId": 40001,
"rosterableToProvider": true,
"status": "PROCESSED",
"messages": [],
"eventId": "52313642-95FE-4031-A612-86DE14AAF0B3"
}
The syncRoster WS enables the EMR to send a roster synchronization request for a specific provider to the Roster Registry. The web service will report changes in the Roster Registry for the provider. It will send a response containing any new roster data for each patient on their roster that has been updated in the Roster Registry since the passed-in date, which can be an EMR User-specified date or the last successful synchronization date.
Unique identifier for this request. Duplicate requests for the same GUID value will be ignored.
Type: String (GUID)
Required: Yes
The date and time to start looking for updated patients. All date time values must be supplied in AST.
Type: yyyyMMdd HHmmssSSS formatted String (0000 – 2359)
Required: Yes
The service provider id for the event.
Type: Long
Required: Yes
The GUID of the processed request.
Type: String (GUID)
The status of the request.
Type: String
Valid Values: PROCESSED|REJECTED|ERROR
The service provider id of the request.
Type: Long
N roster message elements.
Type: List<Message>
See Roster Messages
N number of Resident (patient) objects. Holds the patient demographic and roster information.
Type: List<Resident>
GET https://dhmedapsb1.gnb.ca:8443/NBDHWeb/rest/DE-ID/FMNB/syncRoster?eventId=2349D660-2EB1-4763-9C17-96EBA24F5AA4&changesSinceDateTime=20230101 20151021574&serviceProviderId=40001
{
"serviceProviderId": 40001,
"residents": [
{
"dob": "19960705",
"medicareNumber": 200000610,
"gender": "M",
"rosterEntries": [
{
"effectiveDate": "20231023",
"rosterStatus": "ROSTERED",
"terminationDate": "99991231",
"reasonCode": null
}
],
"rosterMessages": [
{
"code": 17,
"enDescription": "THE RESIDENT IS ALREADY IN STATUS ROSTERED, EVENT FOR 20231023 IS IGNORED.",
"frDescription": "RÉSIDANT A DÉJÀ LE STATUT INSCRIT SUR LA LISTE, ÉVÉNEMENT LE 20231023 EST IGNORÉ."
}
]
},
{
"dob": "19940824",
"medicareNumber": 200001014,
"gender": "F",
"rosterEntries": [
{
"effectiveDate": "20220704",
"rosterStatus": "UNDECIDED",
"terminationDate": "20220707",
"reasonCode": null
},
{
"effectiveDate": "20220802",
"rosterStatus": "ROSTERED",
"terminationDate": "20230207",
"reasonCode": null
},
{
"effectiveDate": "20230207",
"rosterStatus": "EXCEPTION",
"terminationDate": "20230207",
"reasonCode": "4"
},
{
"effectiveDate": "20230207",
"rosterStatus": "ROSTERED",
"terminationDate": "20230303",
"reasonCode": null
}
],
"rosterMessages": []
},
{
"dob": "19800418",
"medicareNumber": 200001055,
"gender": "F",
"rosterEntries": [
{
"effectiveDate": "20220530",
"rosterStatus": "TEMP",
"terminationDate": "20220601",
"reasonCode": null
},
{
"effectiveDate": "20220601",
"rosterStatus": "ROSTERED",
"terminationDate": "20220602",
"reasonCode": null
},
{
"effectiveDate": "20220602",
"rosterStatus": "EXCEPTION",
"terminationDate": "20220606",
"reasonCode": "1"
},
{
"effectiveDate": "20220606",
"rosterStatus": "ROSTERED",
"terminationDate": "20220704",
"reasonCode": null
},
{
"effectiveDate": "20220704",
"rosterStatus": "EXCEPTION",
"terminationDate": "20230227",
"reasonCode": "4"
},
{
"effectiveDate": "20230227",
"rosterStatus": "ROSTERED",
"terminationDate": "20230303",
"reasonCode": null
},
{
"effectiveDate": "20230303",
"rosterStatus": "EXCEPTION",
"terminationDate": "20230310",
"reasonCode": "1"
},
{
"effectiveDate": "20230310",
"rosterStatus": "ROSTERED",
"terminationDate": "20230623",
"reasonCode": null
},
{
"effectiveDate": "20230623",
"rosterStatus": "EXCEPTION",
"terminationDate": "20230720",
"reasonCode": "1"
},
{
"effectiveDate": "20230720",
"rosterStatus": "ROSTERED",
"terminationDate": "20230816",
"reasonCode": null
},
{
"effectiveDate": "20230816",
"rosterStatus": "DEROSTERED",
"terminationDate": "20230927",
"reasonCode": null
},
{
"effectiveDate": "20230927",
"rosterStatus": "REFUSED",
"terminationDate": "20230927",
"reasonCode": null
},
{
"effectiveDate": "20230927",
"rosterStatus": "ROSTERED",
"terminationDate": "20231016",
"reasonCode": null
},
{
"effectiveDate": "20231016",
"rosterStatus": "EXCEPTION",
"terminationDate": "20231027",
"reasonCode": "4"
},
{
"effectiveDate": "20231027",
"rosterStatus": "ROSTERED",
"terminationDate": "99991231",
"reasonCode": null
}
],
"rosterMessages": []
},
{
"dob": "19800718",
"medicareNumber": 200001063,
"gender": "F",
"rosterEntries": [
{
"effectiveDate": "20220530",
"rosterStatus": "TEMP",
"terminationDate": "20220704",
"reasonCode": null
},
{
"effectiveDate": "20220704",
"rosterStatus": "ROSTERED",
"terminationDate": "20220704",
"reasonCode": null
},
{
"effectiveDate": "20220704",
"rosterStatus": "DEROSTERED",
"terminationDate": "20220705",
"reasonCode": null
}
],
"rosterMessages": []
}
],
"status": "PROCESSED",
"messages": [],
"eventId": "2349D660-2EB1-4763-9C17-96EBA24F5AA4"
}
The syncResident WS enables the EMR to send a synchronization request for a specific patient and provider and receive a response containing the most current roster data from the Roster Registry for the passed-in patient as it pertains to that provider. The EMR will take the synchronization data and replace the patient’s roster data and history.
Unique identifier for this request. Duplicate requests for the same GUID value will be ignored.
Type: String (GUID)
Required: Yes
The service provider id for the event.
Type: Long
Required: Yes
The Medicare Number of the patient for the check.
Type: Long
Required: Yes
The GUID of the processed request.
Type: String (GUID)
The status of the request.
Type: String
Valid Values: PROCESSED|REJECTED|ERROR
The service provider id of the request.
Type: Long
N roster message elements.
Type: List<Message>
See Roster Messages
Container of Resident (patient) demographic and roster information.
Type: Resident
GET https://dhmedapsb1.gnb.ca:8443/NBDHWeb/rest/DE-ID/FMNB/syncResident?eventId=4C369C1D-4064-413D-A1FC-4A8040D43F71&serviceProviderId=40001&medicareNumber=200000610
{
"serviceProviderId": 40001,
"resident": {
"dob": "19960705",
"medicareNumber": 200000610,
"gender": "M",
"rosterEntries": [
{
"effectiveDate": "20231023",
"rosterStatus": "ROSTERED",
"terminationDate": "99991231",
"reasonCode": ""
}
],
"rosterMessages": [
{
"code": 17,
"enDescription": "THE RESIDENT IS ALREADY IN STATUS ROSTERED, EVENT FOR 20231023 IS IGNORED.",
"frDescription": "RÉSIDANT A DÉJÀ LE STATUT INSCRIT SUR LA LISTE, ÉVÉNEMENT LE 20231023 EST IGNORÉ."
}
]
},
"status": "PROCESSED",
"messages": [],
"eventId": "4C369C1D-4064-413D-A1FC-4A8040D43F71"
}
The getGroupProviderConfig WS enables the EMR to retrieve the FMNB Configuration information for all providers in all FMNB Groups in the EMR Instance (Org ID).
Unique identifier for this request. Duplicate requests for the same GUID value will be ignored.
Type: String (GUID)
Required: Yes
Returns only configurations for the passed in Service Provider ID.
Type: Long
Required: No
Returns only the members that have or had membership in the passed in FMNB Group ID.
Type: Integer
Required: No
The GUID of the processed request.
Type: String (GUID)
The status of the request.
Type: String
Valid Values: PROCESSED|REJECTED|ERROR
N number of members elements.
Type: List<members>
GET https://dhmedapst1.gnb.ca:8443/NBDHWeb/rest/FMNB/getGroupProviderConfig?eventId=4C369C1D-4064-413D-A1FC-4A8040D43F90
{
"groupProviderConfig": {
"members": [
{
"reductionOverrides": [],
"memberships": [
{
"effectiveDate": "2023-10-19",
"terminationDate": "9999-12-31",
"fmnbgroupId": 75,
"fmnbgroupName": "X FAMILY PRACTICE"
}
],
"emrId": 1016,
"serviceProviderId": 12345
},
{
"reductionOverrides": [
{
"effectiveDate": "2018-06-25",
"terminationDate": "2018-06-29"
"paymentPercent": 84
},
],
"memberships": [
{
"effectiveDate": "2023-10-19",
"terminationDate": "9999-12-31",
"fmnbgroupId": 75,
"fmnbgroupName": "HILLSIDE FAMILY PRACTICE"
}
],
"emrId": 1016,
"serviceProviderId": 12346
},
{
"reductionOverrides": [],
"memberships": [
{
"effectiveDate": "2023-10-19",
"terminationDate": "9999-12-31",
"fmnbgroupId": 75,
"fmnbgroupName": "HILLSIDE FAMILY PRACTICE"
}
],
"emrId": 1016,
"serviceProviderId": 12347
},
{
"reductionOverrides": [],
"memberships": [
{
"effectiveDate": "2023-10-19",
"terminationDate": "9999-12-31",
"fmnbgroupId": 75,
"fmnbgroupName": "HILLSIDE FAMILY PRACTICE"
}
],
"emrId": 1016,
"serviceProviderId": 12348
},
{
"reductionOverrides": [],
"memberships": [
{
"effectiveDate": "2023-10-19",
"terminationDate": "9999-12-31",
"fmnbgroupId": 75,
"fmnbgroupName": "HILLSIDE FAMILY PRACTICE"
}
],
"emrId": 1016,
"serviceProviderId": 12349
}
]
},
"status": "PROCESSED",
"messages": [],
"eventId": "4C369C1D-4064-413D-A1FC-4A8040D43F90"
}
CUSTOM DATA TYPES
Code of the message attached.
Type: Enum
See Service Messages
English description of the message.
Type: String
French description of the message.
Type: String
Medicare Number of the patient.
Type: Long
The patient’s date of birth.
Type: Enum
French description of the message.
Type: String
Valid Values: M|F
N roster entry elements for the service provider and patient.
Type: List<RosterEntry>
N roster message elements.
Type: List<Message>
See Roster Messages
The roster status for this entry.
Type: String
Valid Values: For a list of valid roster statuses eligible for submission refer to api/OpenDataGateway?name=FMNB_ROSTER_STATUS
The date the status became active.
Type: yyyyMMdd formatted String
The date the status was or will terminate.
Type: yyyyMMdd formatted String
Reason for roster exception.
Type: Enum
Valid Values: For a list of valid roster exception reason codes for submission refer to api/OpenDataGateway?name= FMNB_ROSTER_EXCEPTION_REASON
The effective date(s) and termination date(s) of any period of time where the provider's claimed units is not reduced.
The payment percent specifies the percentage of units the claim is paid at.
Type: List of yyyyMMdd formatted strings (effectiveDate and terminationDate)
Type: Integer (paymentPercent)
The effective date(s), termination date(s), group Id and group Name that the FMNB provider belongs to.
Type: List of yyyyMMdd formatted strings (effectiveDate and terminationDate)
Type: Integer (fmnbGroupId)
Type: String (fmnbGroupName)
The EMR/ORG ID of the FMNB group.
Type: Integer
The service provider ID of the FMNB provider.
Type: Long
Service Messages
| Code | English Message | French Message | ||
|---|---|---|---|---|
| Description | ||||
| 1 | INVALID %s DATE | DATE INCORRECTE | ||
| Added in the following web services when the noted date or date/time parameter is null or improperly formatted. • registerRosterEvent – eventDateTime • syncRoster - changesSinceDateTime | ||||
| 2 | INVALID ROSTER STATUS | ÉTAT DE LISTE INCORRECT | ||
| Added in registerRosterEvent when the rosterStatusCode parameter is NULL or not in the list of valid values | ||||
| 3 | INVALID MEDICARE NUMBER | NUMÉRO D'ASSURANCE-MALADIE INVALIDE | ||
| Added in registerRosterEvent, getRosterability, syncResident when the medicareNumber parameter is NULL or does not exist in the Medicare system | ||||
| 4 | INVALID SERVICE PROVIDER | FOURNISSEUR DE SERVICES INVALIDE | ||
| Added in all services when the serviceProviderId is NULL or does not exist in the Medicare system | ||||
| 5 | PROVIDER IS NOT ACTIVE IN THE FMNB PROGRAM ON %s | FOURNISSEUR INACTIF DANS LE PROGRAMME MFNB POUR LES %s | ||
| Added in all services if the service provider is not active in the FMNB program on the event date. For registerRosterEvent this is the eventDateTime for all other services it is the current date and time | ||||
| 6 | ROSTER EXCEPTION REASON CODE REQUIRED | CODE DE RAISON D'EXCEPTION DE LISTE NÉCESSAIRE | ||
| Added in registerRosterEvent when the rosterStatusCode=EXCEPTION and reasonCode is NULL | ||||
| 7 | RESIDENT NOT ACTIVE ON %s | RÉSIDANT INACTIF POUR LES %s | ||
|
Added in getRosterability if the resident is not currently active Added in registerRosterEvent if the resident is not active on the eventDateTime |
||||
| 8 | INVALID ROSTER EXCEPTION REASON CODE | CODE DE RAISON D'EXCEPTION DE LA LISTE INCORRECT | ||
|
Added in registerRosterEvent if the reasonCode is entered for a rosterStatus that is not EXCEPTION Added in registerRosterEvent if the reasonCode is not a valid value. |
||||
| 9 | EVENT ID NOT UNIQUE | ID D'ÉVÉNEMENT NON UNIQUE | ||
| Added in all services if the eventId parameter has been used before | ||||
| 10 | INVALID EVENT ID | ID D'ÉVÉNEMENT INCORRECTE | ||
| Added in all services if the eventId parameter is NULL | ||||
| 12 | MEDICARE NUMBER IS NOT CURRENT | NO D'ASSURANCE-MALADIE INEXACT | ||
| Added in registerRosterEvent and getRosterability if the passed in Medicare number is no longer the resident’s active Medicare number | ||||
| 13 | RESIDENT WAS DEROSTERED ON: %s | RÉSIDANT DÉSINSCRIT POUR LES %s. | ||
| Added in registerRosterEvent and getRosterability if the resident is in an active DEROSTERED status for the service provider | ||||
| 14 | RESIDENT CURRENTLY ROSTERED TO ANOTHER PROVIDER | RÉSIDANT ACTUELLEMENT INSCRIT AUPRÈS D'UN AUTRE FOURNISSEUR | ||
| Added in registerRosterEvent and getRosterability if the resident is currently on another service provider’s roster | ||||
| 15 | SERVICE PROVIDER IS NOT ASSOCIATED TO THE PASSED IN EMR ID | FOURNISSEUR DE SERVICES NON ASSOCIÉ AU PASSÉ DANS L'ID DU DME | ||
| Added in all services if the passed in service provider is not currently associated to the EMR associated with the service request | ||||
Roster Messages
| Code | English Message | French Message | ||
|---|---|---|---|---|
| Description | ||||
| 7 | RESIDENT NOT ACTIVE ON %s | RÉSIDANT INACTIF POUR LES %s | ||
| Added if the resident was retroactively set to inactive by Medicare and previously a valid event can no longer be re-processed | ||||
| 17 | THE RESIDENT IS ALREADY IN STATUS %s, EVENT FOR %s IS IGNORED | RÉSIDANT A DÉJÀ LE STATUT %s, ÉVÉNEMENT LE %s EST IGNORÉ | ||
| Added if two events for a resident have matching service providers and roster status values. The duplicate event is ignored during processing | ||||
| 18 | STATUS UPDATE REQUESTED ON %s FROM %s TO %s IS INVALID | MISE À JOUR DU STATUT NÉCESSAIRE POUR LE %s DE %s À %s EST INCORRECTE | ||
| Added if the transitioning from one status to another is not valid (ex. Cannot transition from ROSTERED to UNDECIDED) | ||||
| 19 | RESIDENT SET TO INACTIVE BY MEDICARE ON %s | RÉSIDANT RÉGLÉ À INACTIF PAR L'ASSURANCE-MALADIE POUR LES %s | ||
| Added if the resident is set to inactive by Medicare | ||||
| 20 | %s CANNOT BE THE INITIAL ROSTER STATUS | %s NE PEUVENT PAS ÊTRE L'ÉTAT DE LA LISTE INITIALE | ||
| Added if the resident was not currently on the provider’s roster and was added for the first time in a status that is not allowed. | ||||
| 22 | INVALID DATE | DATE INCORRECTE | ||
| Added to all services where a date parameter is invalid or null | ||||
| 23 | INVALID STATUS: STATUS CAN ONLY BE USED ONCE PER FMNB PROVIDER | STATUT INVALIDE : LE STATUT PEUT ÊTRE UTILISÉ UNIQUEMENT UNE FOIS POUR CHAQUE FOURNISSEUR DE MFNB. | ||
| Added if resident is not allowed to be moved to the specified roster status (ex. UNDECIDED status can only be used once) | ||||
RESPONSE STATUS
Every web service returns a "status" message in the response which describes the result of the web service request:
- PROCESSED- The web service request processed with no issues.
- REJECTED - The web service request is not processed due do a reason (reason returned). E.G. Medicare number no longer current.
- ERROR - An error occurred in Medicare and the web service request was not processed, even if it was valid.