Connect & FHIR APIs: Troubleshooting & FAQs

This article collates some of the most frequently asked questions and troubleshooting solutions for the MediRecords Connect & FHIR APIs.

If you are not currently using the MediRecords Connect product, you can read more about API integration in the MediRecords Connect: Getting Started with REST & FHIR APIs article.

Contents:

1. API Documentation
2. Implementing & Maintaining an API Integration
3. Obtaining API Tokens
4. Giving an API Token to a Third-Party
5. Recommended API Thresholds
6. Do I need to use OAuth to access the MediRecords APIs?
7. What data formats does MediRecords support?
8. Is FHIR® STU3 supported?
9. Are FHIR® extensions supported?
10. Does MediRecords support Smart-on-FHIR?
11. How does MediRecords handle error conditions?
12. I can't ePrescribe to a patient created via the API
13.  A patient created via the API has come through with a null first name
14.  I get "Invalid token does not contain resource id" when calling the API

API Documentation

For Connect API Resources, please visit the Connect API Document for Developers.

For FHIR API Resources, you can reference the MediRecords FHIR website for developers.

Implementing & Maintaining an API Integration

If you purchase the Connect product, it is the responsibility of the purchaser to implement, develop, and maintain their own API integration.

MediRecords provides the API Access and documentation required, and can assist with guidance on which APIs are best to use for different scenarios, but do not offer consultation or development services.

We have collated some of our frequently asked questions and common troubleshooting scenarios to help support API integration customers in this article.

If you find any bugs, these may be raised with our Support team on support@medirecords.com.

Obtaining API Tokens

MediRecords issues three separate token types: Connect, FHIR, and Appointment Widget. These are not interchangeable, each token only works for the product it was issued for.

As a Connect or FHIR customer, you can request as many API Tokens as you need, and each token generated is unique to the user. If you need another API Token or another copy of your existing token, reach out to your Customer Success Manager. If you are not sure who your Customer Success Manager is, you can reach out to the team on success@medirecords.com.

Setting up the Appointment Widget instead? The request process is the same, see Appointment Widget Configuration for the Widget-specific prerequisites.

Giving an API Token to a Third-Party

You may give your API Token to a third party for assistance in implementing your Connect connection, however you will be responsible for ensuring that the third-party acts within the Terms of Service for the Connect Product. Only APIs listed on the following two resources are available for public use:

Connect API Resources

FHIR Resources

Recommended API Thresholds

Standard usage Poll at a steady rate of around 1 request per second per client. Short bursts of up to 5 rapid requests are fine for brief scenarios like a quick refresh, but avoid sustained high-frequency polling (more than 2 requests per second), as this can affect system performance.

On success Continue polling at your normal rate (1 request per second).

On temporary failure (timeouts or server errors) Rather than retrying immediately, wait progressively longer between each attempt: 1 second → 2 seconds → 4 seconds → 8 seconds (up to a maximum of 30 seconds)

To prevent many clients retrying at exactly the same time, introduce a small random delay to each interval.

When idle or inactive If no changes have been detected for a period of time, reduce your polling frequency — for example, dropping to once every 2–5 seconds. Resume your normal polling rate as soon as user activity or a state change is detected.

After repeated failures If requests continue to fail after 4–5 attempts, pause polling entirely for 30–60 seconds before trying again. Where possible, display a fallback state in the UI during this time rather than continuing to retry in the background.

Bulk operations If you're doing a large bulk creation of sessions, please run this outside standard business hours, to avoid affecting system performance for other users.

Frequently Asked Questions

Do I need to use OAuth to access the MediRecords APIs?

Yes, MediRecords APIs are protected with OAuth 2.0.

What data formats does MediRecords support?

JSON only.

Is FHIR® STU3 supported?

MediRecords only supports FHIR® Release 4 (4.0.1).

Are FHIR® extensions supported?

Yes, MediRecords supports extensions on different resources as defined in MediRecords profiles. Unknown extensions and data elements are not supported by the server.

Does MediRecords support Smart-on-FHIR?

MediRecords is actively working on enabling Smart-on-FHIR for the existing APIs. Once enabled, MediRecords will publish a .well-known/smart-configuration and a CapabilityStatement relative to the FHIR® Server Base URL. Implementers can refer to the REST API specification for details on supported APIs, and updates will be posted on the MediRecords FHIR website for developers.

How does MediRecords handle error conditions?

MediRecords returns appropriate HTTP codes and an OperationOutcome resource when an error condition occurs. Refer to the REST API specification for details.

Troubleshooting

I can't ePrescribe to a patient created via the API

Cause: To ePrescribe to a patient, their record needs an IHI Number and the ePrescribing tick-box needs to be enabled in Patient Settings. If a patient was created via the API without both of these, ePrescribing won't be available for them.

Resolution: If you want patients to be ePrescribable on import, make sure each imported record includes an IHI number and a true flag for ePrescribing, for example:

"ihiNo": "8000000000000000",
"ihiNoStatusCode": null,
"ihiRecordStatusCode": null,
"ePrescribing": true

A patient created via the API has come through with a null first name

Cause: This happens when the request payload includes oneNameOnly set to true. This is expected behaviour for that payload option, not an error, MediRecords treats the patient as having only one name.

Resolution: If the patient does have a first and last name, set oneNameOnly to false in the request payload:

"oneNameOnly": false,

I get "Invalid token does not contain resource id" when calling the API

Cause: This means the wrong type of token is being used for the API being called, a Connect token against the FHIR API, or vice versa.

Resolution: Confirm you're using a FHIR token for FHIR API calls, and a Connect token for Connect API calls.

If this doesn't resolve it: contact MediRecords Support.