PROVIDER SEARCH

Interface Control Document/UI Example

2/1/2024

© Availity, LLC, all rights reserved. | Confidential and proprietary | Page 1 of 11

Overview
This document is written as companion guide to the Provider Search API.
Availity recommends that both the business and technical resources on the trading partner’s
team read this document prior to reviewing any additional reference documents from Availity.

Objective and Benefits of Provider Search

The objective of Provider search is to return a list of eligible providers based on as few provider
parameters as possible, including the NPI.

Provider Search Request Structure

Object Path Type Description Sample

"StandardProviderSearchParameters":
Standard Provider Search Parameters {
providerType String 1P = Provider "providerType":"1P",
(required) FA = Facility
NPI String NPI of the provider "npi":"325123514",
(required)
taxId String taxId of the provider "taxId":"213262314",
(optional)

memberID String ID of the Member the "memberID":"XYZ262314",

(optional) request is for
firstName String First Name of the provider "firstName":"Test",
(optional)

lastName String Last Name of the provider "lastName":"Doctor",

(optional)
city String City of the Provider "city":"Testville",
(optional)
stateCode String State abbreviation of the "stateCode":"IL",
(optional) provider
zipCode String Zip code of the provider "zipCode":"61554",
(optional)
specialityCode String Specialty code of the "specialityCode":"14",
(optional) provider

Additional Parameters
userMessage String Allows passing of custom "userMessage":"",
(optional) information
createdDate DateTime Date request was created "createdDate":"01/01/2023T12:00:00"
(Required) ,
searchToken String Contains a Unique ID to "searchToken":"12edaS-a3214f-
(required) assist in troubleshooting
a32faw3",

© Availity, LLC, all rights reserved. | Confidential and proprietary | Page 2 of 11

Example Provider Search Request Structure
{
"StandardProviderSearchParameters": {
"providerType":"1P",
"npi":"325123514",
"taxId":"213262314",
"memberID":"XYZ262314",
"firstName":"Test",
"lastName":"Doctor",
"city":"Testville",
"stateCode":"IL",
"zipCode":"61554",
"specialityCode":"208D0000X"
},
"userMessage":"",
"createdDate":"01/01/2023T12:00:00",
"searchToken":"12edaS-a3214f-a32faw3"
}

Provider Search Response Structure

Object Path Type Description Sample
userMessage String Free text field to pass "userMessage":"",
(optional) custom values in

createdDate DateTime Date/Time response was "createdDate":"01/01/2023T12:00:30"

(required) created
,
count Int Number of providers "count": 10,
(required) returned

providers Arrray Array Containing all "providers":[{}]

(required) providers

providers.lastName String Provider Last Name "lastName":"Doctor",

(required)

providers.firstName String Provider First Name. "firstName":"Test",

(conditional) Required only if provider
is NOT a facility
providers.middleName String Provider Middle Name "middleName":"J",
(optional)
providers.npi String Provider’s NPI number "npi":"325123514",
(required)

providers.taxId String Provider’s Tax ID "taxId":"2562345345",

(optional)

© Availity, LLC, all rights reserved. | Confidential and proprietary | Page 3 of 11

 Object Path Type Description Sample
providers.specialityCodes String Array of provider’s "specialtyCodes": [{}]
(required) Specialty Codes

providers.specialtyCodes. String Specialty code as "specialtyCode":"208D0000X",

specialtyCode (required) provider Taxonomy Code
(HPTC)
providers.specialtyCodes. String Text description of "specialty":"General Practice (8)",
speciality (required) provider’s specialty

providers.specialityCodes. Boolean True/False value that "primary":true

primary (required) states if a provider is a
PCP
providers.address String Address of provider "address":"123 abc st.",
(required)

providers.city String City of the provider "city":"Testville",

(optional)

Providers.state String Full name of the state of "state":"Illinois",

(conditional) the provider. Required if
StateCode not used
stateCode String State abbreviation of the "stateCode":"IL",
(conditional) provider. Required if
Providers.state not used
zipCode String Zip code of the provider. "zipCode":"61554",
(optional)

providerType String Provider Type 1P = "providerType":"1P",

(required) Provider. FA = Facility

inNetwork Boolean True/False value "inNetwork":true,

(optional) indicating if provider is in
network or not
customParams String Field to allow custom data "customParams":""
(optional) to be passed on a per-
provider basis. Any
population of this field is
considered custom work.

© Availity, LLC, all rights reserved. | Confidential and proprietary | Page 4 of 11

Provider Search Response Example
{
"userMessage":"",
"createdDate":"01/01/2023T12:00:30",
"count": 1,
"searchToken":"12edaS-a3214f-a32faw3",
"providers":[{
"lastName":"Doctor",
"firstName":"Test",
"middleName":"J",
"npi":"325123514",
"taxId":"2562345345",
"specialtyCodes": [
{"specialtyCode":"208D0000X",
"specialty":"General Practice (8)",
"primary":true
},
{"specialtyCode":"20860000X",
"specialty":"Surgery (23)",
"primary":false}
],
"address":"123 abc st.",
"city":"Testville",
"state":"Illinois",
"stateCode":"IL",
"zipCode":"61554",
"providerType":"1P",
"inNetwork":true,
"customParams":""

}]
}

© Availity, LLC, all rights reserved. | Confidential and proprietary | Page 5 of 11

Error Handling
Common HTTP Status codes for API Responses

Status Code Meaning Description

200 OK Returned for Successful operations

400 BAD_REQUEST Indicates an improperly formatted or invalid request

429 TOO_MANY_REQUES Used when the request limit is exceeded

TS

500 INTERNAL_SERVER_E Signifies a server-side error.

RROR

504 GATEWAY_TIMEOUT Timeout

Example Error Response

Object Path Type Description Sample
status Int (required) Int value containing the status code "status":200

error String Plain text value of the http error "error":"",

(optional)

apiToken String Token to assist in troubleshooting. Must be "searchToken":"123awf-

returned in response and must be identical to
(required)
token in request.
wf8w98-ave184",

dateCreated DateTime Date and time the response was generated "dateCreated":"01-01-
(required) 2024 00:00:01",

message String Required if there is an error. This segment is "message":"Request

(conditional) meant to contain information that helps
explain why an error may have occurred.
Successful",

Example Error Response

{
"status":200,
"error":"",
"apiToken":"231few-4789f8-ewf8es",
"dateCreated":"01-01-2024 00:00:01",
"message":"Request Successful"
}

© Availity, LLC, all rights reserved. | Confidential and proprietary | Page 6 of 11

Payer-Specific Details
Connection Details
(Authentication is done via OAuth)

Dev (Send credentials separately)

Authentication Endpoint
API Endpoint

QA (Send credentials separately)

Authentication Endpoint
API Endpoint

PROD (Send credentials separately)

Authentication Endpoint
API Endpoint

Payer-Specific Details
Requirement Value/Notes
Timeout Setting (30 sec Default)
Support Contact Regular Hours
Support Contact After-Hours
Primary Technical Contact
Primary Business Contact
Allow search on First/Last Name
and City/State/Zip?
Allow search on TIN?
Require MemberID?
Returning inNetwork value?
Any additional field’s req’d for
network status?
Any custom values in
userMessage segment on
request? Specify if yes.
Any custom values in
userMessage segment on
response? Specify if yes.
Any custom values in
customParams? Specify if yes.

© Availity, LLC, all rights reserved. | Confidential and proprietary | Page 7 of 11

© Availity, LLC, all rights reserved. | Confidential and proprietary | Page 8 of 11
UI Example

© Availity, LLC, all rights reserved. | Confidential and proprietary | Page 9 of 11

© Availity, LLC, all rights reserved. | Confidential and proprietary | Page 10 of 11
© Availity, LLC, all rights reserved. | Confidential and proprietary | Page 11 of 11