First Medical Interoperability API Developer Portal
The First Medical Interoperability API Developer Portal provides third-party app developers with access to documentation, registration services, Developer Sandbox services, and other developer services related to application programming interfaces (“APIs”) provided by First Medical. First Medical and Innovation Health, pursuant to the Centres for Medicare & Medicaid Services (“CMS”) Interoperability and Patient Access Final Rule (CMS-9115-F).
- The Patient Access API will allow developers to retrieve, with the approval and at the direction of an applicable First Medical enrollee or the enrollee’s personal representative, certain data, as applicable, concerning adjudicated claims, encounter data from capitated providers, formulary data, and certain clinical data, if First Medical maintains any such data.
- The Provider Directory API will allow developers to retrieve, as applicable, certain First Medical provider and pharmacy directory information.
- The Developer Sandbox will allow developers to test their application’s connection to the APIs without establishing production access to the APIs.
Registering as a developer for First Medical APIs
How to create an account to use First Medical’s Interoperability API Developer Portal if you are a DEVELOPER:
- Click here to Register
- Enter your Mobile Number OR Email Id
- Enter your Password and confirm your Password by re-entering it
- Enter your First Name, Last Name and Second Last Name.
- Agree to the Terms and Conditions and click on Register.
- First Medical will send a code to the entered Email Id.
- Check your email (Code will be valid for 5 mins.) and enter the code and click on Confirm Code.
- Once clicked on Confirm Code you can register an application.
- Once registered, the Admin will approve it and once approved you can access our Production APIs.
Subscribing to First Medical APIs
- Click on App Registration, now enter all the information in App Information.
- Enter Application Name and Call-back URL and Submit.
- The system will generate a Client Id and Secret key. It is important that you save the Client Id and the Secret key to be used further in the process. It will only be shown to you once.
- Click on Your Apps and you can see your new application in the list.
- Within the application, you can view your Client Id, Subscriptions, Update App and API Products.
- Updating the Application allows users to change the Callback URL, Delete the App, Reset the Secret key (in case you forgot to write it down) and verify the Client Id and Secret key. Verifying the Client Id and Secret key can be helpful if you have created multiple Apps and have confused which Client Id and Secret key applies to which app.
Try the API
Prerequisite:- Developer Registration is mandatory.
- After Developer registration, Developer can register their application.
- Click on “Application Registration” to register your application and get a Client Id and Client Secret Key.
- Make sure you save Client Secret Key, which is required to generate a Response code or token.
There are two ways to integrate the Authentication with First Medical platform to fetch the logged-in patient data.
This is more secured and recommended flow because the Client Id and Client Secret Key is validated while generating a token.
- To use this flow your application should be registered with Client Type set to Confidential and Grant Type set to Authorization-code.
- Following steps are executed to authenticate the User:-
Request authorization from the application URL:-
- client_Id:- Will generate when the Developer will register the Application.
- redirect_uri:- Developer need to save during application registration.
- response_type:- code (To achieve this flow this need to be set as “code”)
- state:- Any random character’s alphabet (Optional) (Length = 15 and Format = Alphanumeric)
Once application navigate to above URL with required information, then response code would be attached to redirect URL as per below format:
your_application_redirect_URL ?code= code your_application_redirect_URL:- this is your registered application redirect URLYour application can now exchange the “code” provided with the redirected URL for a token.
code:- Will be generated and sent from the First Medical platform.
- Send a POST request to the First Medical platform token endpoint providing the responseCode, clientSecret, redirectUri and the grantType.
Please find below URL and format to generate the token:-
Pass the following data in the headers:-
- responseCode:- Authentication flow will generate the response code
- grantType:- Authorization_code
- clientSecret:- Will be generated while the Developer is registering the application
- redirectUri:- Registered application Redirect URI
Scope Scope Names Patient patient/Patient.read Explanation of Benefit patient/ExplanationOfBenefit.read Coverage patient/Coverage.read Profile profile
- Response:- ("token" : generated JWT token) First Medical platform will validate the above information. On successful validations, JWT token will be generated for subsequent usage.
To use this flow your application should be registered with Client Type set to Public and Grant Type set to Implicit.
Request authorization from user URL:-
- client_Id:- It will generate when the Developer will register the Application
- redirect_uri:- Developer need to save during application registration
- response_type:- Token
- state:- Any random 10 characters alphabet (Optional) (Length = 15 and Format = Alphanumeric)
When the application navigates to the above URL with the required information, all the details will be validated by the first medical platform and it will generate a JWT token to the redirect URL.
your_application_redirect_URL:- this is your registered application Redirect URL.
- Token:- it will be generated and sent with the Redirect URL in the below format:-
Want to use the Sandbox environment?
Follow the below steps:
- Click the link in API and Swagger Files and use the credentials mentioned for Login.
- Once entered the Username and Password click on Login and it will generate your Sandbox Token.
- Copy the token and use it to try sample data and click on Try it.
- Once clicked on Try it, you will be able to access the sample data.
- Select the API for example Patient.
- Click on Try it out, and type the Bearer Token.
- Use 'Bearer' before pasting the token and click on Execute.
- Check the Responses.
Call the API
- Try this out in your API:- After generating the JWT token, navigate to API Library and click on More Details column, then it will open the First Medical swagger URL. Here, you can access any nodes, you will get the sample data related to your profiles.