REST API - Open Care Data
The inbound REST interface for Open Care Data allows for the searching of transparency in coverage related data that is licensed thru the Open Care Data product. The Web service as provided will have a static DNSsite address and will support HTTP verbs (GET, PUT) as needed.
To utilize this feature you must have an active Open Care Data (www.OpenCareData.com) and have an API Key You can get your API Key by contacting sales@OpenCareData.Com or Sales@GoRev.com.
1: Searching the Data
HTTPS GET: https://ocd.gorev.com/api/[PAYER]/search
The path element PAYER will be the specific insurance carrier that is available on www.OpenCareData.com that you intend to run the search API against.
For example, you can see in the below a search against Kaiser Permanente with the associated parameters. There are a variety of free and paid REST client options available for test environment purposes.
The below screenshot is from the Insomnia REST client which is available here: https://insomnia.rest/.
2: Parameters
There are a variety of parameters that can be sent to the API. These parameters can be included in the URL or alternatively included in the header or body of the REST request.
This next section will describe the purpose of each parameters
Name | Required | Description |
ApiKey | Yes | Your API licensing key. You will receive an error message if this field is not provided or is invalid. |
BillingCode | Yes | The Healthcare associated billing code for the relevant BillingCodeType |
BillingCodeType | No | The Healthcare billing code standard type. A list of the Allowed values can be found at the below URL as defined by CMS: Note: BillingCodeType will default to CPT if no value is provided. 11/28/2023 - Currently, the following billing code types are unavailable: LOCAL, EAPG, HIPPS, CSTM-ALL, ICD, APC |
BillingClass | No | The type of provider associated the the rates. Allowed values are: Institutional Professional Both Note: BillingClass will default to Institutional if no value is provided. |
Geozips / Msas | Yes | Either parameter "geozips" or "msas" must be provided. A Geozip is the first three digits of a postal zip code. A Micropolitan/Metropolitan Statistical Area (MSA) is defined by the US Census Bureau which provides a listing file of these values here: Alternatively, we provide a tool to lookup a specific MSA based on a Zip Code which can be utilized here: https://opencaredata.com/MSALookup.aspx Multiple MSA or Geozips can be sent in a request by seperating each with a comma. For example: "16980,16740" provided as the msas parameter would search both the regions. |
Taxonomies | No | This optional parameter allows you to filter search results so they only contain NPIs with a specified list of taxonomy codes. These codes are a healthcare standard defined and maintained by NUCC. See the below URL for more details: You can specify multiple taxonomy codes in the taxonomies parameter by seperating each with a comma. |
ExcludeTaxonomies | No | This optional parameter allows you to filter search results so they do not contain results associated with specific taxonomy codes. |
NegotiationTypes | Yes | This optional parameter allows you to filter search results so they contain specific types of Rate negotiations. The full listing of allowed values and their specific purposes is defined by CMS and can be found at the below URL: You can specify multiple negotiation types by seperating each with a comma in the parameter. |
ArrangementTypes | No | This optional parameter allows you to filter search results so they only contains rates associated with the below: FFS - Fee For Service Bundle - Bundled Services Capitation - Capitated Services You can specify multiple arrangement types by seperating each with a comma in the parameter. |
Modifiers | No | This optional parameter allows you to perform searches against specific modifiers. For example, "26" will search for all rates with a 26 modifier associated with it. When no modifier is entered then the search request will only return rates where there is no associated modifier. The default value is set to "" |
SkipPlans | No | This optional parameter allows you to skip plan related filtering where rates that are not associated to a healthcare plan are trimmed from the data. The default value is set to False. |
TrimZeroRates | No | This optional parameters allows you to trim any zero dollar rates. The default value is set to True. |
Deduplicate | No | This optional parameters removes any duplicate rates where the dollar amount, region, BillingClass, NegotiationType, and associated plan are identical. The default value is set to True. |
IncludeNPIRecords | No | This optional parameter determines whether NPPES NPI registry associated information is returned with the results. The default value is set to False. |
IncludeHIOSRecords | No | This optional parameter determines whether Health Information Oversight System (HIOS) associated information is returned with the results. The default value is set to False. |
GroupByNPI | No | This optional parameter determines how the results are returned from the request. When GroupByNPI is set to True then the data is grouped by NPI, Arrangement, BillingClass, BillingCode, Modifiers, and NegotiationType with only the unique rates being returned and calculated into the summaries. This default value is set to True. |
3: Error Messages
This section goes over the various error messages you may receive when using the API and their purpose
Message | Purpose | Resolution |
The server is starting up and is currently pending loading of the NpiMasterIndex. Please try again later. | This occurs after a server reset when key indexes required for the search process are loading. | Typically will automatically resolve in 10-15 minutes. |
No Shard Name was specified in the URL | The URL did not contain the [PAYER] element as described in section 1. | include the Payer Element |
No API Key was specified in the request | Missing Required Field | See Section 2 |
The provided API key could not be located | The API Key you provided is not valid. | Check for entry errors and if this persists contact support. |
The provided API key is current disabled. Please contact support for more details | Your API has been disabled | Contact Support |
You have reached the maximum number of API calls for your license today. Please try again tomorrow. | You have reach the maximum allowed API calls for your license. | This will automatically resolve at the next calendar day. |
No BillingCode was provided in the request | Missing Required Field | See Section 2 |
Invalid billing code type: [BillingCodeType] | Invalid Required Field | See Section 2 |
Invalid billing class type: [BillingClass] | Invalid Required Field | See Section 2 |
No Values Found | The server failed to respond to the request. | Try again or contact support if this persists. |
Generic Error (StackTrace field will be present) | Typically a server related error that requires support intervention | Contact Support |
3: Payloads
This section will cover an example of a payload along with some relationship elements between the provided data
There are two result formats that are distinguished by the GroupByNPI parameter. The ungrouped format (GroupByNPI = false) will return raw rate data that is not grouped. When GroupByNPI is set to True then the data is grouped by NPI, Arrangement, BillingClass, BillingCode, Modifiers, and NegotiationType with only the unique rates being returned and calculated into the summaries.
Optimization Tip: Excluding unnecessary parts of the payload response does improve overall API response time and can help complete larger API request batches significantly faster. Use optional parameters from Section 2 of this guide to accomplish this.
Hierarchy | Purpose | Relationships |
Rates / NPIGroupedRates | List of all negotiated rates returned by the search | Rates.srcid = SourceFiles.src_id This relationship links the Rates to the relevant sources that the Rates were located in. Rates.LinkedNPIs = NpiRecords.NPI This relationship links the Rate's specific NPI to the NPPES CMS registry that allows you to pull additional demographic information relating to a particular NPI |
_Summary | Lists summary level data based on the Rates returned in the search. This is where you can locate the Median, Average, and 5th thru 95th percentiles. This summary can be provided in insurance product type (based upon HIOS) when available. You will see these delineated (e.x Other_Summary) as EPO, PPO, HMO, POS, Dental, Indemnity, with Other being any unclassified rates | |
SourceFiles | Contains a list of source files that includes the original payer URL along with other related information. | |
SearchLog | Contains a detailed lists of steps that can be used to explain a specific search result. | |
Hashes / HashCountLinks | Relates to internal processes and will typically report as null for an API request. | |
NpiRecords | Contains data relating to the NPPES registry that National Provider Identifiers are derived. Can be enabled by setting IncludeNPiRecords = true | |
HiosRecords | Contains data relating to the Health Information Oversight System (HIOS) that contains information relating to a health insurance plan Can be enabled by setting IncludeHIOSRecords = true |
GoRev Support Team
If you have any questions, concerns, or problems regarding this Tutorial, please contact the Support Team by submitting an IT Support Ticket, by phone at 1-(317)-794-3900, and/or by email at ask@gorev.com.
Note: If possible, always submit an IT Support Ticket detailing any problem that you are experiencing within GoRev. This will give GoRev Support Agents access to additional information that will help expedite the resolution of your issue. If you are unsure how to submit an IT Support Ticket in GoRev, please see theIT Support Ticket Creation for assistance.