Interoperability APIs

Below are examples of basic requests, a full description of which can be found in the RESTful API section of the specification.

Find additional information about Aidbox and its implementation of the standard by visiting:

• http://hl7.org/fhir/http.html
• https://docs.aidbox.app/

Read

To read data you should use GET HTTP request with the following basic structure:

GET [base url]/[resource name]

Where

[base url] - the base url (see above)

[resource name] - is the name of a resource you want to read.

The list below shows the main resources that were used by the FHIR Adapter.

Provider Directory

• Organization
• Practitioner
• Location
• Healthcare Service 
• Organization Affiliation
• Practitioner Role
• Insurance Plan

Claims

• Coverage 
• Explanation Of Benefit

Drug formulary

• Medication Knowledge 

Clinical Data

• Goal
• Medication 
• Care Plan
• Allergy Intolerance 
• Condition 
• Patient 
• Related Person 
• Procedure 
• User

For example, to get a list of practitioners, you need to run the following query:

GET [base url]/Practitioner

You can get, for example, the following results:

{
    "resourceType": "Bundle",
    "type": "searchset",
    "meta": {
        "versionId": "14929925"
    },
    "entry": [
        {
            "resource": {
                "meta": {
                    "lastUpdated": "2021-06-11T19:38:39.686496Z",
                    "createdAt": "2021-06-11T19:38:39.686496Z",
                    "versionId": "11293018"
                },
                "name": [
                    {
                        "use": "official",
                        "given": [
                            "Sample",
                            "A"
                        ],
                        "family": "Practitioner"
                    }
                ],
                "birthDate": "1984-12-08"
                "resourceType": "Practitioner",
                "active": true,
                "id": "4ec99942-c667-4d54-af23-f89f0792e4ed",
                "identifier": [
                    {
                        "use": "secondary",
                        "type": {
                            "coding": [
                                {
                                    "code": "externalId",
                                    "display": "externalId",
                                    "userSelected": false
                                }
                            ]
                        },
                        "value": "89687",
                        "system": "http://hl7.org/fhir/sid/external-id"
                    },
                    {
                        "use": "official",
                        "type": {
                            "coding": [
                                {
                                    "code": "NPI",
                                    "display": "NPI",
                                    "userSelected": false
                                }
                            ]
                        },
                        "value": "1111111111",
                        "system": "http://hl7.org/fhir/sid/us-npi"
                    }
                ],
                "gender": "male"
            },
            "fullUrl": "https://portal.aidbox.my-staging.paramounthealthcare.com/Practitioner/4ec99942-c667-4d54-af23-f89f0792e4ed",
            "link": [
                {
                    "relation": "self",
                    "url": "https://portal.aidbox.my-staging.paramounthealthcare.com/Practitioner/4ec99942-c667-4d54-af23-f89f0792e4ed"
                }
            ]
        }
    ]
}
 

To get a list of patients, you can run the following query:

GET [base url]/Patient

To read a particular record use the following request:

GET [base url]/[resource name]/[id]

Where

[base url] - the base url (see above)

[resource name] - is the name of a resource you want to read

[id] - is a FHIR identifier

For example, to get data for a particular Practitioner you can run:

GET [base url]/Practitioner/4ec99942-c667-4d54-af23-f89f0792e4ed

You can get, for example, the following result:

{
    "meta": {
        "lastUpdated": "2021-06-11T19:38:39.686496Z",
        "createdAt": "2021-06-11T19:38:39.686496Z",
        "versionId": "11293018"
    },
    "name": [
        {
            "use": "official",
            "given": [
                "Sample",
                "A"
            ],
            "family": "Practitioner"
        }
    ],
    "birthDate": "1984-12-08"
    "resourceType": "Practitioner",
    "active": true,
    "id": "4ec99942-c667-4d54-af23-f89f0792e4ed",
    "identifier": [
        {
            "use": "secondary",
            "type": {
                "coding": [
                    {
                        "code": "externalId",
                        "display": "externalId",
                        "userSelected": false
                    }
                ]
            },
            "value": "89687",
            "system": "http://hl7.org/fhir/sid/external-id"
        },
        {
            "use": "official",
            "type": {
                "coding": [
                    {
                        "code": "NPI",
                        "display": "NPI",
                        "userSelected": false
                    }
                ]
            },
            "value": "1111111111",
            "system": "http://hl7.org/fhir/sid/us-npi"
        }
    ],
    "gender": "male"
}
More samples and additional information can be found here:

https://docs.aidbox.app/api-1/api/crud-1/read

Aidbox provides a Search API for all resources. Aidbox Search API is a superset of the FHIR Search API.  

Learn more about Aidbox Search API. 

The following request can be used to find records: 

GET [base url]/[resource name]?[search parameter1]=value1&[search parameter2]=value2 

Where 

 [base url] - the base url (see above) 

[resource name] - is the name of a resource you want to read 

[search parameter] - see below 

Search parameters can be one of the search parameters defined for a particular resource in the standard. For example, find the list of search parameters for the practitioner resource or for the organization resource. 

For example, to find the practitioner by name you can use the following request: 

GET [base url]/Practitioner?name=John 

Or to find the practitioner by it's identifier (for example NPI) use the following request: 

GET [base url]/Practitioner?identifier=1111111111 

For example, to use full text search to find a practitioner, use the following query: 

The FHIR standard provides a set of resources and its attributes, but in most cases it does not impose strict restrictions on the required attributes and their values. In turn, implementation guides impose additional, more stringent restrictions. The following 4 IGs are used to comply with CMS Rule. 

Provider Directory API –  

http://hl7.org/fhir/us/davinci-pdex-plan-net/index.html 

Drug Formulary –  

http://hl7.org/fhir/us/davinci-drug-formulary/ 

Clinical Data –  

http://hl7.org/fhir/us/core/history.html 

Claims and Encounter Data –  

http://hl7.org/fhir/us/carin-bb/index.html 

Provider and pharmacy directories are publicly available information and do not require any additional security measures. Members' claims and clinical data are considered Protected Health Information (PHI) and need to be secured. Members authorize applications they want to use to access their PHI. The process of app registration and authorization by members is standardized in the SMART on FHIR specification. 

SMART App Launch Framework (hl7.org) 

Developer Guidelines 

Below are guidelines you should follow to be successful in your Paramount interoperability API integration. 

Your Privacy Policy 

You will be asked to provide a URL to your privacy policy when registering your organization and your application in the Paramount Interoperability App Portal. These links should be easy to access and understand by a member using your app. 

Member Revokes Access 

A member may revoke access to your application via their member portal. When you encounter an invalid token indicating a member has revoked access, you should make a reasonable attempt to handle that case making it easy for the member to understand what is happening with their data.