Retrieve Contracted Providers Integration Point (HTTP)
Claims stores pricing configuration to administer claims. This configuration essentially represents a link between healthcare providers and healthcare services. Using this information, this integration point answers the question: given a specific healthcare service, which providers are contracted to perform it?
Request
This integration point is available via the following path:
http://[hostName]:[portNumber]/[api-context-root]/contractedproviders
This integration point exposes a POST method. The payload for this request contains the selection criteria for the contracted providers. A small number of selection criteria are embedded in the request: (1) a combination of procedure codes and (2) the service date. The service date is required as well as at least one procedure code.
In addition to these required criteria, the request payload can include any number of user specified selection criteria. These additional user defined criteria can be specified within the context of the following entities:
-
provider
-
provider pricing clause
-
procedure group
For each of the listed resources, the payload can hold one or more conditions that act as filters. These conditions are specified following the syntax of the Query API. Consider the following example request:
{ "contractedProcedure": [{ "code":"12345", "flexCodeDefinitionCode":"ICD9"}] , "contractedProcedure2": { "code":"67890", "flexCodeDefinitionCode":"ICD9"} , "serviceDate": "2020-01-01" , "procedureGroup": ["pricingGroup.eq("Y")"] , "individualProvider": [ "renderingAddressList.serviceAddress.postalCode.eq("90210")" , "excludeProvider.eq("N")" ] , "organizationProvider": [ "excludeProvider.eq("N")" ] , "providerPricingClause": [ "ageFrom.gte("18").or.ageFrom.eq(null)" , "productCategory.productCategoryDimensionList(+).product(+).code.eq("GOLD")" ] , "orderBy": "code:desc" }
These conditions can be built around both native and dynamic fields. For dynamic fields these conditions are restricted to searchable single-value non-time-valid fields. Conditions on dynamic records are not supported.
This example request asks for all providers that are contracted to perform ICD9 procedure 12345 in combination with procedure code 67890 on January 1st, 2020 that meet the following conditions:
-
The contracted procedure codes are included in a procedure group that has dynamic field pricingGroup set to yes
-
The individual provider has at least one rendering address with postal code 90210 AND the provider dynamic field excludeProvider is set to no
-
The organization provider has a dynamic field excludeProvider that is set to no
-
The provider pricing clause applies to members of age 18 and older and with the GOLD product
Each condition in the example demonstrates behavior specific to this operation:
-
Condition (1) only applies if the provider is linked to a provider pricing clause or to a reimbursement method that is linked to the contracted procedure via a procedure group. For example, if the procedure is specified on a fee schedule line then condition (1) is ignored since there is no procedure group to apply it to.
-
Condition (2) is composed of two query statements. For a condition to be satisfied, all statements need to be true. Note that in this example its possible to combine both statements into one, using an and operator.
-
Condition (4) shows a typical pattern where a field (ageFrom) has to meet a certain condition only if it has a value.
The orderBy parameter is applied to the provider resource and controls the sequence of providers in the response. This parameter only takes non-time-valid single-value fields on the provider entity and is specified using the same syntax as the Query API.
Contracted Procedure Codes in the Request
The example request above lists two procedure codes where the first is the parameter value for contracedProcedure
and the second is the parameter value for contracedProcedure2
.
This prompts the system to look for providers linked to a provider pricing clause that refers to both procedure 12345 and procedure 67890.
{ "contractedProcedure": [{ "code":"12345", "flexCodeDefinitionCode":"ICD9"}] , "contractedProcedure2": { "code":"67890", "flexCodeDefinitionCode":"ICD9"} ...
Alternatively, the request can list both procedures under the same parameter. Consider the following example:
{ "contractedProcedure": [{ "code":"12345", "flexCodeDefinitionCode":"ICD9"} ,{ "code":"67890", "flexCodeDefinitionCode":"ICD9"}] ...
This request prompts the system to look for a provider pricing clause that has a link to either procedure 12345 or procedure 67890. It is the equivalent of sending two separate requests for these procedure codes.
Only the first procedure
parameter takes a list; procedure2
(optionally) specifies a single code.
Consider the following example:
{ "contractedProcedure": [{ "code":"A", "flexCodeDefinitionCode":"ICD9"} ,{ "code":"B", "flexCodeDefinitionCode":"ICD9"} ,{ "code":"C", "flexCodeDefinitionCode":"ICD9"}] , "contractedProcedure2": { "code":"D", "flexCodeDefinitionCode":"ICD9"} ...
This request retrieves providers that are contracted to perform
-
or A in combination with D
-
or B in combination with D
-
or C in combination with D
Consider that a provider pricing clause has multiple procedure groups called:
-
procedure group
-
procedure group 2
-
procedure group 3
The codes listed in input parameters contractedProcedure
and contractedProcedure2
are checked against any and all of these groups, i.e., contracedProcedure2
is not checked only against procedure group 2 but against the other groups as well.
Response
For a given procedure code on a given service date, this operation considers a provider to be eligible (to be included in the response) if the system holds one or more provider pricing clauses that are linked to both the procedure code and the provider on the provided service date.
Note that there are multiple ways a provider can be linked to a provider pricing clause:
-
Provider pricing clause → Provider
-
Provider pricing clause → Provider Group → Provider
Within the context of the procedure, only the procedure group on the provider pricing clause is evaluated:
-
Provider pricing clause → Procedure Group → Procedure
Provider Pricing Clause Configuration
Note that the configured provider pricing clauses can various configured conditions that represent the circumstances under which the clause applies. Required modifiers, required location types and dynamic logic conditions are examples. All configured conditions are ignored by this service; any and all provider pricing clauses that can be linked to the specified procedure are used to determine the list of eligible providers.
Note that procedure conditions also not evaluated. Provider pricing clauses that are only linked to a procedure via procedure condition are treated as non-specific provider pricing clauses.
Non-Specific Provider Pricing Clauses
Some provider pricing clauses are not linked to a provider - directly or indirectly - at all. These clauses typically represent catch-all rules that apply when the system can’t find a more apt clause. These clauses are not considered for deriving eligible providers.
The same applies to the contracted procedures; if neither the clause nor the reimbursement method mention a procedure or procedure group, then that clause is not considered for deriving eligible providers.
Fixed Criteria
The following criteria are always applied and can not be overridden by user defined criteria:
-
Only provider pricing clauses that refer to a reimbursement method are used to derive eligible providers
-
Only provider pricing clauses that have a procedure group are considered
-
Only provider pricing clauses that have either a provider or a provider group are considered
-
Only enabled configuration is considered
Response Payload
The response is a list of eligible providers for each requested contracted procedure code (combination).
These codes match the codes provided in input parameter contractedProcedure
.
The response does not include the procedure code specified under contractedProcedure2
as it is implicitly required for every provider entry in the response
For each provider, the response holds a list of links to the provider pricing clauses through which the provider’s eligibility was established. Consider the following example:
{
"items": [
{
"procedure": {
"code": "<code>",
"flexCodeDefinitionCode": "<flex code system code>"
},
"providerList": [
{ //standard representation of the provider resource as in IP
"code": "",
....
,
"providerPricingClauseList": {
"links": [
{
"href": "http://[hostName]:[portNumber]/[api-context-root]/generic/providerpricingclauses/<ppc_id>",
"rel": "oi:ppc"
}
]
}
}
.....
],
"hasMore": false
}
....
]
}
The response is restricted to a maximum of 150 providers.
When more than 150 providers meet the query’s criteria then, the hasMore
flag in the response is set to true and the first 150 providers are returned using the orderBy
clause specified in the query request.
In case orderBy
is not specified in the request, the list of providers is sorted by the provider id by default.
The orderBy
clause is only applicable to the direct attributes of the provider or single-valued non-time valid searchable dynamic fields.