Introduction - Healthcare APIs
Availity web service APIs are designed using a RESTful approach. Our REST API offers predictable, resource-oriented URLs and uses HTTP response codes to indicate API success and failure conditions. Availity REST APIs all return JSON and XML representations, including errors. Some API's have the ability to return CSV, PDF, PNG, and XLS representations.
We offer a trial package that allows you to begin exploring our APIs without completing a formal application process. Using demo data (without PHI information), you'll get up-to-speed quickly, and at no cost to you.
cURL SAMPLES
We use cURL for all samples in this guide so that you can try them. You can download cURL software if needed. Be sure to include your API key and specific IDs for calls.
Important: The sample requests in this guide are examples only and not runnable as is. Substitute all call-specific parameters (such as API Keys, access tokens, and IDs) with your own values.
Get an API Key
All requests to the Availity REST APIs must be authenticated with an Client ID (API Key) including demo endpoints.
GET AN ACCOUNT
- Sign up at Register. Enter the required information and click Create New Account at the bottom of the page.
- Logon to the Availity Developer Portal, using the email address and password from the previous step.
REGISTER AN APPLICATION
- Once logged in successfully, click Apps in the top menu.
- You will need to create separate applications for the Demo plan, and the Standard rate plan. You will select your plan under the "Select a Plan" below.
- Take note of your Client Secret right away. You will not see it again.
SELECT A PLAN
- See API Products in top menu.
- Drill down to view specific details about API Product.
- Select Demo Rate Plan for Mock data response and Standard Rate plan for Live data response.
- Click Subscribe to the plan you are interested in and select the appropriate application which you registered previously.
APPROVALS
Demo plans subscribed to an application will automatically be approved for use right away. All other plans will require verification, contracting and approval. A notification will automatically be sent to Availity API Support to process.
Cross-Site Scripting Prevention
One of the most commonly exploited web security vulnerabilities is called Cross Site Scripting (XSS). Simply put, this type of attack tricks a company into serving malicious JavaScript to users' browsers. This is possible because browsers do not distinguish between text to show the user and scripts to execute.
There are three main categories of XSS attacks:
- Reflected XSS - When an XSS attack is "reflected" off of the web service and returned back to an end user, this is a Reflected XSS Attack. A common form of this is an error message. For example, if an attacker enters into a zip code URL parameter:
&zipcode=20879<script>alert('Gotcha')</script>
the web service code may check that it's a valid zip code, yet not output encode and sanitize it. The web service may respond with an error message saying:20878<script>alert('Gotcha')</script> is not a valid Zip Code
If this happens the attacker will now have full access control to that user's browser. - Stored XSS - If the XSS is stored "permanently" on a target server this is a Stored XSS Attack. Classic examples of this would be comments in WordPress, forum posts, and contact forms.
- DOM XSS - This is the newest form of XSS and is when the "attacker's payload" is injected directly into the browser DOM creating a DOM XSS Attack. An example would be if such JavaScript code exists:
var message = document.cookie; document.errorDiv.innerHTML = message
This would expose the cookie value to an HTML section of the current page.
To learn more about Cross-Site Scripting visit the Open Web Application Security Project (OWASP) website, which has listed XSS Attacks as the #3 most critical security flaw that can exist in applications today. OWASP Top 10 2013-A3 Cross Site Scripting (XSS)
How Availity APIS help you prevent XSS Attacks
Availity continually works to keep your data and our data as secure as possible. We support two parts that will to help prevent XSS attacks:
- Input validation and sanitization.
- Encode resources specifically for their intended use context.
Input Validation and Sanitization
We have implemented whitelist rules for data validation that have been carefully designed to provide protection even against future vulnerabilities introduced by browser changes. What this means for you as a developer is, if you send a request to an API that contains characters which we've determined to not be safe, an HTTP 400
response is returned with an inbound injection
error message. You are required to fix the data and re-submit your request. The best way for you to avoid receiving this error is to ensure that you use proper input validation and sanitization on your side before calling an API.
Response Resource Encoding
Encoding is a complicated process because there are different encoders for each given context. An HTML Body string encode isn't the same as a JavaScript string encode. This is where problems can arise as the attacks also vary from context to context. If encoding isn't done properly for the context you're displaying the data in, an attack can slip through.
By default, we do not provide response resource encoding for an API. If you wish to take advantage of encoding you must opt-in to it by sending an X-Response-Encoding-Context
request header with one of the following values:
- HTML - Performs encoding of data for use in HTML entities.
- HTML_ATTRIBUTE - Performs encoding of data for use in HTML attributes values.
- CSS - Performs encoding of data for use in stylesheets and style tags.
- URL - Performs encoding of data for use in a URL.
- JAVA_SCRIPT - Performs encoding of data for use in JavaScript data values.
- XML - Performs encoding of data for use in XML entities.
- XML_ATTRIBUTE - Performs encoding of data for use in XML attribute values.
We highly recommend that you use the appropriate response encoding context when using our API if you will be displaying API resources directly in your application.
Encoding Examples
Below is an example request to the Configurations service showing a partial resource that was returned using the HTML encoding context.
Notice the providerNpi.errorMessage object, the message contents that contained ()
characters is escaped for use in HTML.
curl -X "GET" "https://api.availity.com/availity/v1/configurations?type=270&payerId=700" -H "Authorization: Bearer abc12345" -H "X-Response-Encoding-Context : HTML"
configurations[0].providerNpi.errorMessage = "Enter a valid National Provider Identifier (NPI)
containing 10 numeric digits and beginning with a 1, 2, 3, or 4."
Authentication
All Availity REST API's support OAuth2 over HTTPS for authentication including requests to Demo resources.
You may have multiple Client IDs active at one time. Your Client ID carry many privileges, so be sure to keep them secret. If you want to make a REST API request to Availity we will assume that you have already:
- Signed up for an account on the Availity developer portal.
- Obtained an Client ID for your application.
OAuth2
The Availity REST API supports the Application-only authentication method, which is based on the Client Credentials Grant flow of the OAuth 2.0 spec.
There are 2 steps required to make an initial API request. The following is an example for obtaining an access token and making a request to the Coverages resource:
1. Get an OAuth2 Access Token
This will return a response that contains an access token, token type, and expiration time. The access token is only valid for 5 minutes.
curl -i -X "POST" "https://api.availity.com/availity/v1/token" \
-d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&scope=hipaa"
->
HTTP/1.1 200 OK
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: application/json
Cache-Control: private, no-store, no-cache, must-revalidate
Pragma: no-cache
{ "token_type":"bearer", "access_token":"AAEkZGI1ZjRhYzgtYWViNy00NmRmLWE0YjYtND5NTliZDI0NTc2kPwma8ezU6mkghUoomSLMUbB8LMPc4NJFNkEyrrmFMZabZ67DHXL3gaCr01_mln8-qLDQWne-8stwXOpb2dObXP3SAt8yn1LDQehlNw_KTcZf1H1-FyAFyM5Nh4g0zNs9ATtj2l-H98FzXl9MoBA", "expires_in":300, "scope":"hipaa" }
The request body parameters are case sensitive. Make sure
grant_type=client_credentials
matches exactly how it is shown.
2. Call REST API with OAuth2 Access Token
We use the access token from step #1 and make requests to the Availity REST API's. The example below shows making a request to the Coverages API. This includes the Availity demo endpoints as well.
curl -i -H "Authorization: Bearer $ACCESS_TOKEN" -X "GET" "https://api.availity.com/availity/v1/coverages?payerId=BCBSF" \
Making Your First Call
With your applications Client ID available, you're now ready to make a request to a REST resource. Below is an example of a request to retrieve a collection of coverages.
The API Key is case sensitive.
curl -i -H "Authorization: Bearer $ACCESS_TOKEN" -X GET "https://api.availity.com/availity/v1/coverages"
->
{
"totalCount": 5,
"count": 5,
"offset": 0,
"limit": 50,
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/coverages"
}
},
"coverages": [
{
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/coverages/0001234821666577173234942038175340242587013739108497709963594997"
}
},
"id": "0001234821666577173234942038175340242587013739108497709963594997",
"customerId": "4321",
"controlNumber": "9876543",
"status": "Complete",
"statusCode": "4",
"createdDate": "2017-06-15T16:31:07.000+0000",
"updatedDate": "2017-06-15T16:31:07.000+0000",
"expirationDate": "2017-06-16T16:31:07.000+0000",
"asOfDate": "2017-06-15T04:00:00.000+0000",
"requestedServiceType": [
{
"code": "30",
"value": "Health Benefit Plan Coverage"
}
],
"subscriber": {
"firstName": "ZENA",
"lastName": "MARDIN",
"memberId": "H87654321",
"gender": "Female",
"genderCode": "F",
"birthDate": "1942-09-15T04:00:00.000+0000"
},
"patient": {
"firstName": "ZENA",
"lastName": "MARDIN",
"subscriberRelationship": "Self",
"subscriberRelationshipCode": "18",
"gender": "Female",
"genderCode": "F",
"birthDate": "1942-09-15T04:00:00.000+0000"
},
"payer": {
"name": "HUMANA",
"payerId": "HUMANA"
},
"requestingProvider": {
"npi": "1234567893",
"taxId": "123123123"
},
"plans": [
{
"status": "Active Coverage",
"statusCode": "1",
"groupNumber": "P1234567"
}
]
}
]
}
Demo Endpoints
Availity has created demo (mock response) versions of each endpoint that you can explore. Each has a number of demo responses available. You can choose which demo response you want by sending a header with your request. The name of the header is X-Api-Mock-Scenario-ID and the value is the id of the response scenario you want. For demo response confirmation, inspect response header for X-Api-Mock-Response: true. You can find supported response scenarios in the documentation of each endpoint.
$ curl -i -H "Authorization: Bearer $ACCESS_TOKEN" " -H "X-Api-Mock-Scenario-ID: Demo-Example1" -X GET "https://api.availity.com/availity/v1/coverages"
->
HTTP/1.1 200 OK
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: application/json
Date: Mon, 10 Jul 2017 13:56:47 GMT
X-Global-Transaction-ID: 2032325519
Cache-Control: private,no-store,max-age=0,must-revalidate
x-api-id: 1599f0e1-36a3-43de-a937-d2770beb6625
X-Api-Mock-Response: true
X-Session-ID: 1599f0e1-36a3-43de-a937-d2770beb6625
X-planid: healthcare-hipaa-transactions:1.0.0:demo
X-planname: demo
{
"message": "This is an example."
}
HTTP Status Codes
CODE | STATUS | VERB | DESCRIPTION |
---|---|---|---|
200 | OK | GET, PUT | Successfully retrieved or updated an existing resource. |
200 | OK | GET by ID | Operation was successful and returns 0 or more resources. The metadata count property in the response body contains the number of resources returned. |
200 | OK | PATCH | Successfully updated field(s) in an existing resource. |
201 | Created | POST | Successfully created a new resource |
202 | Accepted | GET, POST, PUT, DELETE, PATCH | The request has been accepted for processing, but the processing has not been completed. The Location header contains the URI to monitor for status updates. |
204 | No Content | DELETE | The service fulfilled the request, which may have removed a resource from server cache, server DB or external resource. The API client can consider the resource no longer available. |
303 | See Other | GET | The response to the request can be found under a different URI provided in the Location header and should be retrieved using a GET method on the URI. |
400 | Bad Request | GET by ID | The request could not be understood by the service due to malformed query parameters. |
400 | Bad Request | POST | The request could not be understood by the service due to malformed syntax. |
400 | Bad Request | PUT | The request could not be understood by the service due to malformed syntax. |
401 | Unauthorized | GET, POST, PUT, DELETE, PATCH | The API client is not authorized to make this request. The request requires user authentication. |
403 | Forbidden | GET, POST, PUT, DELETE, PATCH | The server understood the request, but is refusing to fulfill it. This may be temporary or permanent, depending on the use case. |
404 | Not Found | GET, PUT, DELETE, PATCH | The service has not found anything matching the Request URI. No indication is given whether the condition is temporary or permanent. |
405 | Method Not Found | GET, POST, PUT, PATCH, DELETE | The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. |
406 | Not Acceptable | GET, POST, PUT, DELETE, PATCH | The resource identified by the request is only capable of generating response entities that have content characteristics not acceptable according to the Accept headers sent in the request. |
409 | Conflict | POST, PUT, PATCH, DELETE | The service could not complete the request due to a conflict with the current state of the resource. |
410 | Gone | GET, PUT, DELETE, PATCH | The requested resource is no longer available and there is no forwarding URI known, this condition is permanent and you should not request the resource again in the future. |
415 | Unsupported Media Type | GET, POST, PUT, DELETE, PATCH | The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. |
422 | Unprocessable Entity | POST, PUT, PATCH, DELETE | The JSON/XML request entity is properly formed and the media type is a supported media type for the resource; but validation has failed or the request entity is a different type or version than the service supports |
500 | Internal Server Error | GET, POST, PUT, DELETE, PATCH | The service encountered an unexpected condition that prevented it from fulfilling the request. |
Collections
A Collection Resource
is a resource containing other resources. It is known as a Collection Resource
because it is itself a first class resource, it has its own attributes similar to any other resource in addition to the instances it contains.
If you want to interact with multiple resources, you must do so with a Collection Resource
. They support additional behavior specific to collections, such as pagination
, sorting
, and searching
.
Collection Resource Attributes
ATTRIBUTE | DESCRIPTION | MIN | MAX | DEFAULT | TYPE |
---|---|---|---|---|---|
links |
Set of resource URI's | - | - | - | Object |
offset |
The zero-based starting index in the collection of the first item to return | 0 | - | 0 | Integer |
limit |
The maximum number of collection items to return for a single request | 1 | 50 | 50 | Integer |
count |
The number of items returned | 0 | - | - | Integer |
totalCount |
The total number of items available that match the parameters specified | 0 | - | - | Integer |
resources |
An array containing the current page of resources, the attribute name will be the plural name of the resource type, such as coverages . The size of the array can be less than the requested limit . For example, if the limit requested is greater than the maximum allowed or if the response returned less than the limit amount. |
0 | - | - | Array |
Pagination
If a Collection Resource contains a large number of resource instances, it will not include all of them in a single response. Instead, pagination is used to break up the results into one or more pages of data. You can request additional pages as separate requests.
Example Collection Resource Partial Response
{
"totalCount": 19,
"count": 5,
"offset": 0,
"limit": 5,
"links": {
"last": {
"href": "https://api.availity.com/availity/v1/coverages?limit=5&offset=14"
},
"next": {
"href": "https://api.availity.com/availity/v1/coverages?limit=5&offset=5"
},
"self": {
"href": "https://api.availity.com/availity/v1/coverages?limit=5"
}
},
"coverages": [
{
"customerId": "1194",
"batchId": "14029438773180168889579000001660",
"controlNumber": "1-1020",
"status": "Communication Error",
"statusCode": "14",
"createdDate": "2017-07-16T18:38:12.000+0000",
"updatedDate": "2017-07-16T18:38:12.000+0000",
"expirationDate": "2017-07-16T19:07:23.000+0000",
"asOfDate": "2017-02-03T05:00:00.000+0000"
},
{
...
}
]
}
Query Parameters
The Availity API utilizes cursor-based pagination using two optional query parameters, if they aren't specified the default values are used:
offset
The zero-based starting index in the collection of the first item to return. Default is 0
.
limit
The maximum number of collection items to return for a single request. Minimum value is 1
, Maximum value is 50
.
Link Relations
The links attribute will contain Link Relations
depending on which page and the number of resources returned. If a Link Relation
is not available you will receive a null
value when trying to access it.
LINK RELATION | PURPOSE | HREF |
---|---|---|
self |
The URL used to retrieve the Collection Resources | "https://api.availity.com/availity/v1/coverages?offset=50&limit=50" |
first |
The URL to retrieve the first page of resources | "https://api.availity.com/availity/v1/coverages?offset=0&limit=50" |
last |
The URL to retrieve the last page of resources | "https://api.availity.com/availity/v1/coverages?offset=251&limit=50" |
next |
The URL to retrieve the next page of resources | "https://api.availity.com/availity/v1/coverages?offset=100&limit=50" |
prev |
The URL to retrieve the previous page of resources | "https://api.availity.com/availity/v1/coverages?offset=0&limit=50 |
Date Time Format
All date and time values used in the Availity API use the ISO 8601 format.
Example
"createdDate": "2014-06-16T18:38:12.000+0000"
Errors
REST API responses indicating an error or warning will return a response body with extended error information. Conventional HTTP status codes are used to indicate success or failure of an API request. In general, codes in the 2xx
range indicate success; codes in the 4xx
range could indicate missing required parameters or authentication/authorization failures; and codes in the 5xx
range indicate an error within Availity's or downstream servers.
Example Error Response
{
"statusCode": 404,
"userMessage": "The coverage you specified cannot be found.",
"developerMessage": "The specified coverage cannot be found.
If you accessed this url via a stale href reference,
it's possible the coverage object has expired in our
system, you should acquire the members Coverage Collection
Resource again to obtain the current list of coverages.",
"url": "https://api.availity.com/availity/v1/documentation/coverages",
"errors": [
{
"code": 545,
"errorMessage": "Some other extended error occurred"
},
{
"code": 615,
"errorMessage": "Some other extended error occurred"
}
]
}
Error Response Attributes
Attribute | Description | Type |
---|---|---|
statusCode | The HTTP status code | Integer |
reasonCode | Internal error code (currently not used) | Integer |
userMessage | Error message appropriate for display to end user | String |
developerMessage | A more detailed error message appropriate for a developer | String |
url | URL where more information can be found on the error | String |
errors | A collection of extended error messages if available | Array |
errors.code | Service-specific error code | Integer |
errors.errorMessage | Service-specific error message for error code | String |
Coverages
This resource allows you to find and manage a member's coverage information.
Working with the DEMO endpoints
Availity allows you to specify the type of response you want when interacting with our Coverages demonstration service by sending a header (X-Api-Mock-Scenario-ID) with the appropriate response scenario id. The supported response scenarios are listed below.
Response Scenario ID | Status Code | Description |
---|---|---|
Coverages-Complete-i | 200 | Availity has successfully retrieved the member's coverage information from the health plan. |
Coverages-PayerError1-i | 200 | The health plan has indicated that the provider is ineligible for inquiries. |
Coverages-PayerError2-i | 200 | The health plan has indicated that the subscriber name is invalid. |
Coverages-InProgress-i | 202 | Availity is in the process of retrieving the member's coverage information from the health plan. |
Coverages-Retrying-i | 202 | The health plan did not respond so Availity is retrying the request. |
Coverages-RequestError1-i | 400 | Your request failed Availity's input validation rules. |
Coverages-RequestError2-i | 400 | Your request failed Availity's input validation rules. |
Payer can return the following errors:
Code | Description |
---|---|
04 | Authorized Quantity Exceeded |
15 | Required Application Data Missing |
33 | Input Errors |
35 | Out of Network |
41 | Authorization/Access Restrictions |
42 | Unable to Respond at Current Time |
43 | Invalid/Missing Provider Identification |
44 | Invalid/Missing Provider Name |
45 | Invalid/Missing Provider Specialty |
46 | Invalid/Missing Provider Phone Number |
47 | Invalid/Missing Provider State |
48 | Invalid/Missing Referring Provider Identification Number |
49 | Provider is Not Primary Care Physician |
50 | Provider Ineligible for Inquiries |
51 | Provider Not on File |
52 | Service Dates Not Within Provider Plan Enrollment |
53 | Inquired Benefit Inconsistent with Provider Type |
54 | Inappropriate Product/Service ID Qualifier |
55 | Inappropriate Product/Service ID |
56 | Inappropriate Date |
57 | Invalid/Missing Date(s) of Service |
58 | Invalid/Missing Date-of-Birth |
60 | Date of Birth Follows Date(s) of Service |
61 | Date of Death Precedes Date(s) of Service |
62 | Date of Service Not Within Allowable Inquiry Period |
63 | Date of Service in Future |
64 | Invalid/Missing Patient ID |
65 | Invalid/Missing Patient Name |
66 | Invalid/Missing Patient Gender Code |
67 | Patient Not Found |
68 | Duplicate Patient ID Number |
69 | Inconsistent with Patient's Age |
70 | Inconsistent with Patient's Gender |
71 | Patient Birth Date Does Not Match That for the Patient on the Database |
72 | Invalid/Missing Subscriber/Insured ID |
73 | Invalid/Missing Subscriber/Insured Name |
74 | Invalid/Missing Subscriber/Insured Gender Code |
75 | Subscriber/Insured Not Found |
76 | Duplicate Subscriber/Insured ID Number |
77 | Subscriber Found, Patient Not Found |
78 | Subscriber/Insured Not in Group/Plan Identified |
79 | Invalid Participant Identification |
80 | No Response received - Transaction Terminated |
97 | Invalid or Missing Provider Address |
98 | Experimental service or procedure |
AA | Authorization number not found |
AE | Requires primary care physician authorization |
AF | Invalid/missing diagnosis code(s) |
AG | Invalid/missing procedure code(s) |
AO | Additional patient coordination information required |
CI | Certification information does not match patient |
E8 | Requires medical review |
IA | Invalid authorization number format |
MA | Missing authorization number |
T4 | Payer Name or Identifier Missing |
GET /V1/COVERAGES
You can retrieve a snapshot of a member's health plan coverage by querying the coverages resource with the following parameters:
Parameter | Required | Type | Description |
---|---|---|---|
payerId | No | String | This is the Availity id of the health plan that the member has coverage with. You can view the list of payer id's by selecting the Coverage Resource from the Supported Health Plans link on the contents menu on the left side of this page. |
providerType | No | String | Certain health plans require that the submitter specify whether or not they are a professional or institutional provider. You can specify that using this optional field. |
providerNpi | No | String | Most health plans require that you send the provider's National Provider Identifier number to identify who is requesting to see a member's coverage information. Specify this value using this parameter. |
providerTaxId | No | String | Some health plans require that you send the provider's tax id. Please use this parameter to specify the requesting provider's tax id. |
payerAssignedProviderId | No | String | A few health plans allow you to specify a payer-assigned identifier for the requesting provider. If the requesting provider has been assigned a payer-assigned provider id, send it using this parameter. |
providerSSN | No | String | A few health plans allow you to specify a provider's SSN. |
providerFirstName | No | String | The provider's first name. |
providerLastName | No | String | The provider's last name. |
providerCity | No | String | Certain health plans require that you specify the city that the provider is located in. You can send that information using this parameter. |
providerState | No | String | Certain health plans require that you specify the state that the provider is located in. You can send that information using this parameter. |
providerZipCode | No | String | Certain health plans require that you specify the ZIP code that the provider is located in. You can send that information using this parameter. |
providerSpecialty | No | String | Certain health plans allow you to specify the provider's specialty using a taxonomy code. |
placeOfService | No | String | Certain health plans require that you identify the place of service. |
submitterId | No | String | Some health plans require that you identify yourself using a payer-assigned submitter identifier. Please send that information for health plans that require it using this parameter. |
asOfDate | No | Date | You can indicate the date of service or point in time you want to check coverage information for using this parameter. |
toDate | No | Date | Some health plans require that you provide an end date for your coverage information search period. If checking coverage for such a health plan, please use this parameter. |
serviceType | No | String | You can specify the type or types of service using this parameter. |
memberId | No | String | The patient's health plan member id. |
medicaidId | No | String | The Medicaid id of the patient or subscriber. |
patientSSN | No | String | The patient's SSN. |
patientLastName | No | String | The patient's last name. |
patientFirstName | No | String | The patient's first name. |
patientMiddleName | No | String | The patient's middle name. |
patientGender | No | String | The patient's gender. |
patientBirthDate | No | Date | The patient's birth date. |
patientSuffix | No | String | The patient's suffix. |
patientState | No | String | The subscriber's patient of residence. |
groupNumber | No | String | The patient's group number. |
subscriberRelationship | No | String | If the patient is not the subscriber, you can specify their relationship to the subscriber using this parameter. |
externalTraceId | No | String | If you would like to assign a trace id to one or more coverages, specify an externalTraceId. You will be able to filter your requests by this id when searching. |
externalControlNumber | No | String | If you would like to assign a unique identifier to a particular coverage, specify an externalControlNumber. You will be able to filter your requests by this id when searching. |
providerOfficeId | No | String | If you would like to tag one or more coverages with your own system's customer id, you can do so by sending this parameter. |
providerUserId | No | String | If you would like to tag a coverage with your own system's user id, you can do so by sending this parameter. |
Sample Requests
When you make a valid request, the resource will return a status code of 200
and a coverage summary.
Note: The response has been truncated to conserve space.
$ curl -X GET "https://api.availity.com/availity/v1/coverages""
->
{
"totalCount": 5,
"count": 5,
"offset": 0,
"limit": 50,
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/coverages"
}
},
"coverages": [
{
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/coverages/0001234821666577173234942038175340242587013739108497709963594997"
}
},
"id": "0001234821666577173234942038175340242587013739108497709963594997",
"customerId": "4321",
"controlNumber": "9876543",
"status": "Complete",
"statusCode": "4",
"createdDate": "2014-10-15T16:31:07.000+0000",
"updatedDate": "2014-10-15T16:31:07.000+0000",
"expirationDate": "2014-10-16T16:31:07.000+0000",
"asOfDate": "2014-10-15T04:00:00.000+0000",
"requestedServiceType": [
{
"code": "30",
"value": "Health Benefit Plan Coverage"
}
],
"subscriber": {
"firstName": "ZENA",
"lastName": "MARDIN",
"memberId": "H87654321",
"gender": "Female",
"genderCode": "F",
"birthDate": "1942-09-15T04:00:00.000+0000"
},
"patient": {
"firstName": "ZENA",
"lastName": "MARDIN",
"subscriberRelationship": "Self",
"subscriberRelationshipCode": "18",
"gender": "Female",
"genderCode": "F",
"birthDate": "1942-09-15T04:00:00.000+0000"
},
"payer": {
"name": "HUMANA",
"payerId": "HUMANA"
},
"requestingProvider": {
"npi": "1234567893",
"taxId": "123123123"
},
"plans": [
{
"status": "Active Coverage",
"statusCode": "1",
"groupNumber": "P1234567"
}
]
}
]
}
This coverage summary contains high level information about the coverage.
Availity stores short-lived, local copies of each coverage (until the time specified by the expirationDate
property). If we do not have a recent local copy of a particular coverage, we will request it from the health plan. This is an asynchronous process. You can track the current status using the status
and statusCode
properties of the coverage.
To search your recently requested coverages, in addition to the parameters above, you can also use the following parameters:
Parameter | Required | Type | Description |
---|---|---|---|
status | No | String | Search for coverages with a status of "In Progress", "Request Error", "Communication Error", or "Complete". |
planStatus | No | String | Search for coverages with a plan status of "Active" or "Inactive" |
q | Yes | String | Search for coverages that match free form search terms. |
sortBy | No | String | Sort the results by "lastUpdateDate", "asOfdate", or "patientLastName". The default is "lastUpdateDate". |
sortDirection | No | String | Sort the results in "asc" or "desc" order. The default is "desc". |
Important: When performing a search query, you must specify the
q
parameter. If you do not require a free-form matching of terms you may leave it empty,q=
If you send invalid parameters, the resource will return a status code of 400
and an error response:
$ curl -X GET "https://api.availity.com/availity/v1/coverages?payerId=BCBSF"
->
{
"userMessage": "This client system has made an invalid request.",
"developerMessage": "Your request is not formed properly. Please check your request and the API documentation.",
"documentation": "https://api.availity.com/availity/v1/documentation/coverages",
"reasonCode": 0,
"statusCode": 400,
"errors": [
{
"field": "submitterId",
"errorMessage": "Please enter a valid Submitter ID."
},
{
"field": "serviceType",
"errorMessage": "This field is required."
},
{
"field": "patientBirthDate",
"errorMessage": "Enter a valid date that is not in the future."
},
{
"field": "memberId",
"errorMessage": "Enter a patient ID containing letters, numbers, spaces, and any of the following special characters: ,;'-.?!&/\\#+=()"
},
{
"field": "providerNpi",
"errorMessage": "Enter a valid National Provider Identifier (NPI) containing 10 numeric digits and beginning with a 1, 2, 3, or 4."
},
{
"field": "patientLastName",
"errorMessage": "Enter a name containing letters, numbers, spaces, and any of the following special characters: ,;'-.?!&/\\#+=()"
}
]
}
Hint: In general, sending as many fields as you can is a good approach. The rules vary according to the health plan and some have specific requirements. These rules are documented as a feature of our configurations resource.
If a coverage reports its statusCode
and status
properties as "0" and "In Progress" respectively, Availity is in the process of retrieving the coverage from the health plan. You should poll by either repeating your request or making a GET by id request periodically for the coverage until the statusCode
and status
properties change. "In Progress" coverages will include an etaDate
property reporting the time we anticipate the refresh will be complete. The status
property will change to one of several values:
Status Code | Status | Description |
---|---|---|
19 | Request Error | Indicates that the health plan has returned one or more validationMessages. |
R1 | Communication Error, Retrying | Indicates that the health plan did not respond and we are retrying the request. |
7 | Communication Error | Indicates that the health plan did not respond. |
13 | Communication Error | Indicates that the health plan's response was invalid. |
14 | Communication Error | The health plan did not respond. |
15 | Communication Error | The health plan has indicated that they are down maintenance. |
4 | Complete | Indicates that the refresh was completed successfully. |
3 | Complete (Invalid Response) | Indicates that the refresh was completed successfully, but the health plan's response was partially invalid. Availity will still return all available information from the response, but some values may be missing. |
When you make a search request, the resource will return a status code of 200
and the first page of matching coverage summaries:
$ curl -X "GET" "https://api.availity.com/availity/v1/coverages?payerId=BCBSF&providerNpi=1234567893&memberId=PBHR123456&patientLastName=Parker&patientFirstName=Peter&serviceType=98&patientBirthDate=1990-01-01&providerTaxId=123456789"
->
{
"totalCount": 1,
"count": 1,
"offset": 0,
"limit": 50,
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/coverages?payerId=BCBSF&providerNpi=1234567893&memberId=PBHR123456&patientLastName=Parker&patientFirstName=Peter&serviceType=98&patientBirthDate=1990-01-01&providerTaxId=123456789"
}
},
"coverages": [
{
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/coverages/0001234457589486807542108543870042194372034683103803500071606998"
}
},
"id": "0001234457589486807542108543870042194372034683103803500071606998",
"customerId": "1234",
"status": "In Progress",
"statusCode": "0",
"createdDate": "2014-10-15T15:33:29.000+0000",
"updatedDate": "2014-10-15T15:33:29.000+0000",
"expirationDate": "2014-10-16T15:33:28.000+0000",
"etaDate": "2014-10-15T15:33:29.000+0000",
"asOfDate": "2014-10-15T04:00:00.000+0000",
"requestedServiceType": [
{
"code": "30",
"value": "Health Benefit Plan Coverage"
}
],
"subscriber": {
"memberId": "111222333"
},
"patient": {
"subscriberRelationship": "Self",
"subscriberRelationshipCode": "18",
"birthDate": "2001-01-10T05:00:00.000+0000"
},
"payer": {
"name": "HUMANA",
"payerId": "HUMANA"
},
"requestingProvider": {
"taxId": "123123123"
}
}
]
}
When you request one or more summaries by id
, the resource will return a status code of 200
and any requested unexpired coverage summaries:
$ curl -X GET "https://api.availity.com/availity/v1/coverages?id=0001194499098175762045868562105833796329766732695450956940743265&id=00011944990981757620458685621358337963297667326954509569407491523"
->
{
"coverages" : [
{
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/coverages/0001194499098175762045868562105833796329766732695450956940743265"
}
},
"customerId": "1234",
"requestedServiceType": [...],
"subscriber": {...},
"patient": {...},
"payer": {...},
"requestingProvider": {...},
"plans": [...]
},
{
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/coverages/00011944990981757620458685621358337963297667326954509569407491523"
}
},
"customerId": "1234",
"requestedServiceType": [...],
"subscriber": {...},
"patient": {...},
"payer": {...},
"requestingProvider": {...},
"plans": [...]
}
]
}
The coverage summary also contains demographics about the member, their overall plan status, and other information to help identify the coverage.
Availity will return the first 50 coverages that match your search. If there are more than 50 matching coverages, links to subsequent pages will be returned. For more information on paging of data, see pagination.
GET /V1/COVERAGES/:ID
You can retrieve the details about a member's coverage by requesting an individual coverage.
When you make a valid request, the resource will return a status code of
200
and a coverage:
$ curl -X GET "https://api.availity.com/availity/v1/coverages/0001194499098175762045868562105833796329766732695450956940743265"
->
{
"id": "0001194499098175762045868562105833796329766732695450956940743265",
"customerId": "1234",
"batchId": "14121823232660172516451000001173",
"controlNumber": "23337",
"externalTraceId" : "12314",
"externalControlNumber": "1",
"providerOfficeId": "Office246810",
"providerUserId": "UserOffice246810",
"status": "Complete",
"statusCode": "4",
"createdDate": "2017-10-01T16:52:06.000+0000",
"updatedDate": "2017-10-01T16:52:06.000+0000",
"expirationDate": "2017-10-31T16:52:05.000+0000",
"etaDate" : "2017-10-01T16:52:06.000+0000",
"asOfDate": "2017-09-30T04:00:00.000+0000",
"toDate": "2017-09-30T04:00:00.000+0000",
"requestedServiceType": [...],
"validationMessages": [...],
"subscriber": {...},
"patient": {...},
"payer": {...},
"requestingProvider": {...},
"plans": [...],
"supplementalInformation": {...},
"reminders" : {...},
"links": {...}
}
The subscriber
object contains demographics about the health plan subscriber.
"subscriber" : {
"firstName" : "JAMES",
"middleName" : "T",
"lastName" : "KIRK",
"suffix" : "SR",
"memberId" : "ASDF12345",
"gender" : "Male",
"genderCode" : "M",
"ssn" : "123591122",
"birthDate" : "1982-04-28T00:00:00.000+0000",
"address" : {
"line1" : "123 MAIN ST",
"line2" : "SUITE 1",
"city" : "JACKSONVILLE",
"state" : "Florida",
"stateCode" : "FL",
"zipCode" : "23211"
}
}
The patient
object contains demographics about the patient. The patient might be the subscriber or a dependent. This is indicated by the subscriberRelationship
and subscriberRelationshipCode
properties. The updateYourRecords
property indicates whether the demographics you sent to the health plan are out of date and should be updated with the demographics presented here.
"patient" : {
"firstName" : "JANE",
"middleName" : "C",
"lastName" : "KIRK",
"suffix" : "PMP",
"patientAccountNumber" : "1232141-12",
"memberId" : "ASDF12345",
"familyUnitNumber" : "1",
"subscriberRelationship" : "Spouse",
"subscriberRelationshipCode" : "01",
"gender" : "Female",
"genderCode" : "F",
"ssn" : "213329991",
"birthDate" : "1983-04-28T00:00:00.000+0000",
"deathDate" : "2017-05-01T00:00:00.000+0000",
"address" : {
"line1" : "123 MAIN ST",
"line2" : "SUITE 1",
"city" : "JACKSONVILLE",
"state" : "Florida",
"stateCode" : "FL",
"zipCode" : "23211"
},
"updateYourRecords" : false
}
The payer
object contains information about the health plan that returned this coverage information. The payerId
property is the health plan's Availity id. We also return any known contact information for the health plan in the contactInformation
array.
"payer" : {
"payerId" : "BCBSF",
"payerName" : "FLORIDA BLUE",
"contactInformation" : [{
"name" : "BILLING DEPT",
"phone" : "1-800-123-4567",
"workPhone" : "1-800-123-4567 x120",
"fax" : "1-800-234-4321",
"emailAddress" : "ASDF@EXAMPLE.COM",
"url" : "WWW.EXAMPLE.COM",
"ediAccessNumber" : "12341123"
}]
}
The requestingProvider
object contains information about the provider that requested this coverage information. This includes information sent on the request to the health plan and any additional information the health plan returned about that provider.
"requestingProvider" : {
"name" : "Business Name",
"lastName" : "LAST",
"firstName" : "FIRST",
"middleName" : "MIDDLE",
"npi" : "1234567893",
"taxId" : "111222333",
"payerAssignedProviderId" : "U1283",
"ein" : "111222333",
"ssn" : "111222333",
"payerId" : "12939",
"pharmacyProcessorNumber" : "123123",
"planId" : "2148124",
"stateLicenseNumber" : "123129312",
"medicareProviderNumber" : "1231243",
"medicaidProviderNumber" : "891823",
"facilityId" : "9127371",
"pin" : "1112",
"contractNumber" : "2391781-1",
"electronicPin" : "1293",
"submitterId" : "G1923",
"payerAssignedUserId" : "E1231",
"providerPlanNetworkId" : "19231-12",
"facilityNetworkId" : "123123-312",
"specialty" : "HOSPITAL",
"specialtyCode" : "282N00000X",
"role" : "Admitting",
"roleCode" : "AD"
}
The plans
array contains any health plans returned for the member. Each plan
has an overall status indicated by the status
and statusCode
properties. We also return any pertinent identifiers and dates tied to the plan.
"plans" : [{
"status" : "Active",
"statusCode" : "1",
"groupNumber" : "12314",
"groupName" : "EXAMPLE COMPANY",
"policyNumber" : "219312",
"planNumber" : "213124",
"planName" : "BLUE OPTIONS",
"planNetworkId" : "213123",
"planNetworkName" : "EXAMPLE NETWORK",
"contractClassCode" : "21312",
"contractNumber" : "41257",
"medicalRecordNumber" : "238124",
"healthInsuranceClaimNumbe" : "184891",
"identificationCardSerialNumber" : "12939123",
"identityCardNumber" : "1239123",
"issueNumber" : "1",
"medicaidRecipientIdentificationNumber" : "123123",
"priorIdentificationNumber" : "13141",
"agencyClaimNumber" : "141",
"caseNumber" : "189923-1",
"admissionDate" : "2017-04-21T00:00:00.000+0000",
"dischargeDate" : "2017-05-01T00:00:00.000+0000",
"issueDate" : "2017-05-01T00:00:00.000+0000",
"serviceDate" : "2017-05-01T00:00:00.000+0000",
"coverageStartDate" : "2017-01-01T00:00:00.000+0000",
"coverageEndDate" : "2017-12-31T00:00:00.000+0000",
"planStartDate" : "2017-01-01T00:00:00.000+0000",
"planEndDate" : "2017-12-31T00:00:00.000+0000",
"planEnrollmentDate" : "2017-01-01T00:00:00.000+0000",
"certificationDate" : "2017-01-01T00:00:00.000+0000",
"eligibilityStartDate" : "2017-01-01T00:00:00.000+0000",
"eligibilityEndDate" : "2017-12-31T00:00:00.000+0000",
"policyEffectiveDate" : "2017-01-01T00:00:00.000+0000",
"policyExpirationDate" : "2017-12-31T00:00:00.000+0000",
"effectiveChangeDate" : "2017-01-01T00:00:00.000+0000",
"cobraStartDate" : "2017-01-01T00:00:00.000+0000",
"cobraEndDate" : "2017-12-31T00:00:00.000+0000",
"lastUpdateDate" : "2017-01-01T00:00:00.000+0000",
"addedDate" : "2017-01-01T00:00:00.000+0000",
"premiumPaidToBeginDate" : "2017-01-01T00:00:00.000+0000",
"premiumPaidToEndDate" : "2017-12-31T00:00:00.000+0000",
"statusDate" : "2017-01-01T00:00:00.000+0000",
"additionalPayers" : [...],
"primaryCareProvider" : {...},
"contacts" : [...],
"payerNotes" : [...],
"preexistingConditions" : {...},
"benefits" : [...]
}]
A plan can contain information about other health plans in the additionalPayers
array. This includes various identifiers, dates, and member information associated with the other healthplan. The primary
, secondary
, and tertiary
properties indicate how this health plan participates in coordination of benefits for the member.
"additionalPayers" : [{
"name" : "Example Insurance",
"type" : "Commercial",
"typeCode" : "C1",
"planNumber" : "128318",
"planName" : "Sample Plan",
"groupNumber" : "81283",
"groupName" : "Example Group",
"policyNumber" : "8123",
"planNetworkId" : "123",
"planNetworkName" : "Example Network",
"dischargeDate" : "2017-01-01T00:00:00.000+0000",
"periodStartDate" : "2017-01-01T00:00:00.000+0000",
"periodEndDate" : "2017-12-31T00:00:00.000+0000",
"completionDate" : "2017-01-01T00:00:00.000+0000",
"coordinationOfBenefitsBeginDate" : "2017-01-01T00:00:00.000+0000",
"coordinationOfBenefitsEndDate" : "2017-12-31T00:00:00.000+0000",
"coordinationOfBenefitsDate" : "2017-01-01T00:00:00.000+0000",
"coverageStartDate" : "2017-01-01T00:00:00.000+0000",
"coverageEndDate" : "2017-12-31T00:00:00.000+0000",
"addedDate" : "2017-01-01T00:00:00.000+0000",
"planStartDate" : "2017-01-01T00:00:00.000+0000",
"benefitBeginDate" : "2017-01-01T00:00:00.000+0000",
"benefitEndDate" : "2017-12-31T00:00:00.000+0000",
"primaryCareProviderDate" : "2017-01-01T00:00:00.000+0000",
"lastVisitDate" : "2017-01-01T00:00:00.000+0000",
"eligibilityStartDate" : "2017-01-01T00:00:00.000+0000",
"eligibilityEndDate" : "2017-01-01T00:00:00.000+0000",
"admissionDate" : "2017-01-01T00:00:00.000+0000",
"serviceDate" : "2017-01-01T00:00:00.000+0000",
"lastUpdateDate" : "2017-01-01T00:00:00.000+0000",
"statusDate" : "2017-01-01T00:00:00.000+0000",
"payerNotes" : ["This is a note from the secondary payer."],
"payerId" : "00590",
"contactInformation" : [{
"name" : "Billing Dept",
"phone" : "1-800-234-1234 x12",
"fax" : "1-800-345-1234 x12",
"emailAddress" : "api@availity.com",
"ediAccessNumber" : "1238",
"url" : "www.availity.com",
"workPhone" : "555-123-3122 x151
}],
"address" : {
"line1" : "123 Main St",
"line2" : "Suite 15",
"city" : "Jacksonville",
"state" : "Florida",
"stateCode" : "FL",
"zipCode" : "237812123"
},
"primary" : false,
"secondary" : true,
"tertiary" : false,
"insuredLastName" : "",
"insuredFirstName" : "",
"insuredMiddleName" : "",
"insuredMemberId" : "",
"insuredContactInformation" : [{
"name" : "Resident",
"phone" : "9042312134 x12",
"fax" : "5555554444 x12",
"emailAddress" : "bob@example.com",
"ediAccessNumber" : "1238",
"url" : "www.example.com",
"workPhone" : "555-123-3122 x152
}],
"insuredAddress" : {
"line1" : "123 Main St",
"line2" : "Suite 12",
"city" : "Jacksonville",
"state" : "Florida",
"stateCode" : "FL",
"zipCode" : "237812123"
}
}]
The primaryCareProvider
object contains any information returned by the health plan about the member's primary care provider. This information includes any known identifiers, pertinent dates, and contact information for that primary care provider.
"primaryCareProvider" : {
"name" : "Medical Center",
"lastName" : "Smith",
"firstName" : "Joe",
"middleName" : "D",
"npi" : "1234567893",
"taxId" : "111222333",
"payerAssignedProviderId" : "G1234",
"ein" : "128312314",
"ssn" : "111222333",
"etin" : "123123",
"facilityId" : "21312",
"suhi" : "4123",
"memberId" : "12312",
"naicId" : "123214",
"payerId" : "44431",
"pharmacyProcessorNumber" : "123123",
"planId" : "123124",
"address" : {
"line1" : "123 Main St",
"line2" : "Suite 1",
"city" : "Jacksonville",
"state" : "Florida",
"stateCode" : "FL",
"zipCode" : "612312341"
},
"specialty" : "HOSPITAL",
"specialtyCode" : "282N00000X",
"role" : "Admitting",
"roleCode" : "AD",
"contactInformation" : [{
"name" : "Dr Smith",
"phone" : "9042312134 x12",
"fax" : "5555554444 x12",
"emailAddress" : "bob@example.com",
"ediAccessNumber" : "1238",
"url" : "www.example.com",
"workPhone" : "555-123-3122 x152
}],
"dischargeDate" : "2017-01-01T00:00:00.000+0000",
"periodStartDate" : "2017-01-01T00:00:00.000+0000",
"periodEndDate" : "2017-01-01T00:00:00.000+0000",
"completionDate" : "2017-01-01T00:00:00.000+0000",
"coordinationOfBenefitsBeginDate" : "2017-01-01T00:00:00.000+0000",
"coordinationOfBenefitsEndDate" : "2017-01-01T00:00:00.000+0000",
"coordinationOfBenefitsDate" : "2017-01-01T00:00:00.000+0000",
"coverageStartDate" : "2017-01-01T00:00:00.000+0000",
"coverageEndDate" : "2017-01-01T00:00:00.000+0000",
"addedDate" : "2017-01-01T00:00:00.000+0000",
"planStartDate" : "2017-01-01T00:00:00.000+0000",
"benefitBeginDate" : "2017-01-01T00:00:00.000+0000",
"benefitEndDate" : "2017-01-01T00:00:00.000+0000",
"primaryCareProviderDate" : "2017-01-01T00:00:00.000+0000",
"lastVisitDate" : "2017-01-01T00:00:00.000+0000",
"eligibilityStartDate" : "2017-01-01T00:00:00.000+0000",
"eligibilityEndDate" : "2017-01-01T00:00:00.000+0000",
"admissionDate" : "2017-01-01T00:00:00.000+0000",
"serviceDate" : "2017-01-01T00:00:00.000+0000",
"lastUpdateDate" : "2017-01-01T00:00:00.000+0000",
"statusDate" : "2017-01-01T00:00:00.000+0000",
"policyNumber" : "2134",
"familyUnitNumber" : "1",
"groupNumber" : "1231",
"referralNumber" : "12312",
"alternateListId" : "32154",
"coverageListId" : "78123",
"healthInsuranceClaimNumber" : "12",
"drugFormularyNumber" : "491123",
"priorAuthorizationNumber" : "1238123",
"medicalAssistanceCategoryId" : "2139123",
"planNetworkId" : "19283",
"medicaidRecipientId" : "123123",
"deliveryInformation" : [{
"quantityQualifier" : "Visits",
"quantityQualifierCode" : "VS",
"quantity" : "12",
"amount" : "3",
"per" : "Week",
"perCode" : "WK",
"timePeriod" : "Month",
"timePeriodCode" : "34"
"timePeriods" : "2",
"pattern" : "Monday, Wednesday and Thursday",
"patternCode" : "SY",
"time" : "A.M.",
"timeCode" : "D"
}],
"payerNotes" : ["The is a note from the payer about the primary care provider."]
}
The contacts
array contains any other general contact information provided. This object contains any identifiers, pertinent dates, and contact information for the contact.
"contacts" : [{
"name" : "Joe's Discount Health Plan",
"lastName" : "Smith",
"firstName" : "Joe",
"middleName" : "D",
"npi" : "1234567893",
"taxId" : "111222333",
"payerAssignedProviderId" : "G1234",
"ein" : "128312314",
"ssn" : "111222333",
"etin" : "123123",
"facilityId" : "21312",
"suhi" : "4123",
"memberId" : "12312",
"naicId" : "123214",
"payerId" : "44431",
"pharmacyProcessorNumber" : "123123",
"planId" : "123124",
"address" : {
"line1" : "123 Main St",
"line2" : "Suite 1",
"city" : "Jacksonville",
"state" : "Florida",
"stateCode" : "FL",
"zipCode" : "612312341"
},
"specialty" : "HOSPITAL",
"specialtyCode" : "282N00000X",
"type" : "Prior Insurance Carrier",
"typeCode" : "P4",
"role" : "Admitting",
"roleCode" : "AD",
"contactInformation" : [{
"name" : "Dr Smith",
"phone" : "9042312134 x12",
"fax" : "5555554444 x12",
"emailAddress" : "bob@example.com",
"ediAccessNumber" : "1238",
"url" : "www.example.com",
"workPhone" : "555-123-3122 x152
}],
"dischargeDate" : "2014-01-01T00:00:00.000+0000",
"periodStartDate" : "2014-01-01T00:00:00.000+0000",
"periodEndDate" : "2014-01-01T00:00:00.000+0000",
"completionDate" : "2014-01-01T00:00:00.000+0000",
"coordinationOfBenefitsBeginDate" : "2014-01-01T00:00:00.000+0000",
"coordinationOfBenefitsEndDate" : "2014-01-01T00:00:00.000+0000",
"coordinationOfBenefitsDate" : "2014-01-01T00:00:00.000+0000",
"coverageStartDate" : "2014-01-01T00:00:00.000+0000",
"coverageEndDate" : "2014-01-01T00:00:00.000+0000",
"addedDate" : "2014-01-01T00:00:00.000+0000",
"planStartDate" : "2014-01-01T00:00:00.000+0000",
"benefitBeginDate" : "2014-01-01T00:00:00.000+0000",
"benefitEndDate" : "2014-01-01T00:00:00.000+0000",
"primaryCareProviderDate" : "2014-01-01T00:00:00.000+0000",
"lastVisitDate" : "2014-01-01T00:00:00.000+0000",
"eligibilityStartDate" : "2014-01-01T00:00:00.000+0000",
"eligibilityEndDate" : "2014-01-01T00:00:00.000+0000",
"admissionDate" : "2014-01-01T00:00:00.000+0000",
"serviceDate" : "2014-01-01T00:00:00.000+0000",
"lastUpdateDate" : "2014-01-01T00:00:00.000+0000",
"statusDate" : "2014-01-01T00:00:00.000+0000",
"policyNumber" : "2134",
"familyUnitNumber" : "1",
"groupNumber" : "1231",
"referralNumber" : "12312",
"alternateListId" : "32154",
"coverageListId" : "78123",
"healthInsuranceClaimNumber" : "12",
"drugFormularyNumber" : "491123",
"priorAuthorizationNumber" : "1238123",
"medicalAssistanceCategoryId" : "2139123",
"planNetworkId" : "19283",
"medicaidRecipientId" : "123123",
"authorizationRequired" : true,
"deliveryInformation" : [{
"quantityQualifier" : "Visits",
"quantityQualifierCode" : "VS",
"quantity" : "12",
"amount" : "3",
"per" : "Week",
"perCode" : "WK",
"timePeriod" : "Month",
"timePeriodCode" : "34"
"timePeriods" : "2",
"pattern" : "Monday, Wednesday and Thursday",
"patternCode" : "SY",
"time" : "A.M.",
"timeCode" : "D"
}],
"payerNotes" : ["The is a note from the payer about the primary care provider."]
}]
The payerNotes
array contains general disclaimers and messages from the health plan.
"payerNotes" : [{
"type" : "Disclaimer",
"typeCode" : "D",
"message" : "This is a disclaimer!"
}]
The preexistingConditions
contains any general information about coverage of pre-existing conditions returned by the health plan. This object is organized by network with each network array containing detailed benefit information (see benefit detail object below).
"preexistingConditions" : {
"inNetwork" : [...],
"outOfNetwork" : [...],
"notApplicableNetwork" : [...],
"noNetwork" : [...]
}
The benefits
array contains detailed information about coverage of various benefits. It is organized by service type with each entry containing benefit information about a particular service type. The name
and type
properties identify the service type this benefit pertains to.
The benefit has an overall status indicated by the status
and statusCode
properties. Additional status information is broken down in the statusDetails
object. This object is organized by network with each network array containing detailed benefit information (see benefit detail object below).
Financial information about the benefit is contained in the amounts
object. You can find information about the co-pay, out-of-pocket expenses, deductibles, and co-insurance here. Each of these financial sections is organized by network with each network array containing detailed benefit information (see benefit detail object below).
Limitations on this benefit are described in the limitations
object. It is also organized by network with each network array containing detailed benefit information (see benefit detail object below).
Non-covered information is located in the nonCovered
property. This object is organized by network with each network array containing detailed benefit information (see benefit detail object below).
Coverage basis information is located in the coverageBasis
property. This object is organized by network with each network array containing detailed benefit information (see benefit detail object below).
Information about pre-existing conditions is located in the preexistingConditions
property. This object is organized by network with each network array containing detailed benefit information (see benefit detail object below).
Additional health plans that cover this particular benefit are specified in the additionalPayers
array. This array contains the same type of object with the same possible properties as the plan-level additionalPayers
array.
Contacts related to this particular benefit are specified in the contacts
array. This array contains the same type of object with the same possible properties as the plan level contacts
array.
The payerNotes
array contains any notes from the health plan that pertain to this particular benefit.
"benefits" : [{
"name" : "Medical Care",
"type" : "1",
"status" : "Active",
"statusCode" : "1",
"statusDetails" : {
"inNetwork" : [...],
"outOfNetwork" : [...],
"notApplicableNetwork" : [...],
"noNetwork" : [...]
},
"amounts" : {
"coPayment" : {
"inNetwork" : [...],
"outOfNetwork" : [...],
"notApplicableNetwork" : [...],
"noNetwork" : [...]
},
"outOfPocket" : {
"inNetwork" : [...],
"outOfNetwork" : [...],
"notApplicableNetwork" : [...],
"noNetwork" : [...]
},
"deductibles" : {
"inNetwork" : [...],
"outOfNetwork" : [...],
"notApplicableNetwork" : [...],
"noNetwork" : [...]
},
"coInsurance" : {
"inNetwork" : [...],
"outOfNetwork" : [...],
"notApplicableNetwork" : [...],
"noNetwork" : [...]
}
},
"limitations" : {
"inNetwork" : [...],
"outOfNetwork" : [...],
"notApplicableNetwork" : [...],
"noNetwork" : [...]
},
"nonCovered" : {
"inNetwork" : [...],
"outOfNetwork" : [...],
"notApplicableNetwork" : [...],
"noNetwork" : [...]
},
"coverageBasis" : {
"inNetwork" : [...],
"outOfNetwork" : [...],
"notApplicableNetwork" : [...],
"noNetwork" : [...]
},
"preexistingConditions" : {
"inNetwork" : [...],
"outOfNetwork" : [...],
"notApplicableNetwork" : [...],
"noNetwork" : [...]
},
"additionalPayers : [...],
"contacts : [...],
"payerNotes : [{
"type" : "Disclaimer",
"typeCode" : "D",
"message" : "This is a disclaimer!"
}]
}]
Information about benefits is conveyed in the benefit-detail format. This can include specific status information about an aspect of a benefit (status and statusCode), financial information (amount, total remaining), where service should be performed (placeOfService and placeOfServiceCode), dates pertaining to this detail, contacts related to this detail (the same contact object as the plan and benefit-level contacts), and even information about how a service should be delivered deliveryInformation
.
{
"status" : "Active",
"statusCode" : "1",
"insuranceType" : "Point of Service (POS)",
"insuranceTypeCode" : "PS",
"amount" : "50.00",
"units" : "USD",
"amountTimePeriod" : "Visit",
"amountTimePeriodCode" : "27",
"remaining" : "25.00",
"remainingTimePeriod" : "Visit",
"remainingTimePeriodCode" : "27",
"total" : "25.00",
"totalTimePeriod" : "Visit",
"totalTimePeriodCode" : "27",
"level" : "Family",
"levelCode" : "FAM",
"quantity" : "1",
"quantityQualifier" : "Days",
"quantityQualifierCode" : "DY",
"authorizationRequired" : false,
"placeOfService" : "Office",
"placeOfServiceCode" : "11",
"description" : "BASIC COVERAGE",
"dischargeDate" : "2014-01-01T00:00:00.000+0000",
"periodStartDate" : "2014-01-01T00:00:00.000+0000",
"periodEndDate" : "2014-01-01T00:00:00.000+0000",
"completionDate" : "2014-01-01T00:00:00.000+0000",
"coordinationOfBenefitsDate" : "2014-01-01T00:00:00.000+0000",
"coordinationOfBenefitsBeginDate" : "2014-01-01T00:00:00.000+0000",
"coordinationOfBenefitsEndDate" : "2014-01-01T00:00:00.000+0000",
"coverageStartDate" : "2014-01-01T00:00:00.000+0000",
"coverageEndDate" : "2014-01-01T00:00:00.000+0000",
"addedDate" : "2014-01-01T00:00:00.000+0000",
"planStartDate" : "2014-01-01T00:00:00.000+0000",
"primaryCareProviderDate" : "2014-01-01T00:00:00.000+0000",
"lastVisitDate" : "2014-01-01T00:00:00.000+0000",
"eligibilityStartDate" : "2014-01-01T00:00:00.000+0000",
"eligibilityEndDate" : "2014-01-01T00:00:00.000+0000",
"benefitBeginDate" : "2014-01-01T00:00:00.000+0000",
"benefitEndDate" : "2014-01-01T00:00:00.000+0000",
"admissionDate" : "2014-01-01T00:00:00.000+0000",
"serviceDate" : "2014-01-01T00:00:00.000+0000",
"lastUpdateDate" : "2014-01-01T00:00:00.000+0000",
"statusDate" : "2014-01-01T00:00:00.000+0000",
"contacts" : [...],
"payerNotes" : ["A note from the payer."],
"deliveryInformation" : [{
"quantityQualifier" : "Visits",
"quantityQualifierCode" : "VS",
"quantity" : "12",
"amount" : "3",
"per" : "Week",
"perCode" : "WK",
"timePeriod" : "Month",
"timePeriodCode" : "34"
"timePeriods" : "2",
"pattern" : "Monday, Wednesday and Thursday",
"patternCode" : "SY",
"time" : "A.M.",
"timeCode" : "D"
}]
}
Coverage Response Field Mapping Tables
Below you will find tables that provide mapping to various fields in the resource response.
The following are possible values for insuranceTypeCode and insuranceType fields:
Insurance Type Code | Insurance Type |
---|---|
12 | Medicare Secondary Working Aged Beneficiary or Spouse with Employer Group Health Plan |
13 | Medicare Secondary End-Stage Renal Disease Beneficiary in the Mandated Coordination Period with an Employer's Group Health Plan |
14 | Medicare Secondary, No-fault Insurance Including Auto is Primary |
15 | Medicare Secondary Worker's Compensation |
16 | Medicare Secondary Public Health Service (PHS) or Other Federal Agency |
41 | Medicare Secondary Black Lung |
42 | Medicare Secondary Veteran's Adminstration |
43 | Medicare Secondary Disabled Beneficiary Under Age 65 with Large Group Health Plan (LGHP) |
47 | Medicare Secondary, Other Liability Insurance is Primary |
AP | Auto Insurance Policy |
C1 | Commercial |
CO | Consolidated Omnibus Budget Reconciliation Act (COBRA) |
CP | Medicare Conditionally Primary |
D | Disability |
DB | Disability Benefits |
EP | Exclusive Provider Organization |
FF | Family or Friends |
GP | Group Policy |
HM | Health Maintenance Organization (HMO) |
HN | Health Maintenance Organization (HMO) - Medicare Risk |
HS | Special Low Income Medicare Beneficiary |
IN | Indemnity |
IP | Individual Policy |
LC | Long Term Care |
LD | Long Term Policy |
LI | Life Insurance |
LT | Litigation |
MA | Medicare Part A |
MB | Medicare Part B |
MC | Medicaid |
MH | Medigap Part A |
MI | Medigap Part B |
MP | Medicare Primary |
OT | Other |
PE | Property Insurance - Personal |
PL | Personal |
PP | Personal Payment (Cash - No Insurance) |
PR | Preferred Provider Organization (PPO) |
PS | Point of Service (POS) |
QM | Qualified Medicare Beneficiary |
RP | Property Insurance - Real |
SP | Supplemental Policy |
TF | Tax Equity Fiscal Responsibility Act (TEFRA) |
WC | Workers Compensation |
WU | Wrap Up Policy |
The following are possible values for subscriberRelationshipCode and subscriberRelationship fields:
Subscriber Relationship Code | Subscriber Relationship |
---|---|
18 | Self |
01 | Spouse |
19 | Child |
20 | Employee |
21 | Unknown |
39 | Organ Donor |
40 | Cadaver Donor |
53 | Life Partner |
G8 | Other Relationship |
34 | Other Adult |
The following are possible values for levelCode and level fields:
Level Code | Level |
---|---|
CHD | Children Only |
DEP | Dependents Only |
ECH | Employee and Children |
EMP | Employee Only |
ESP | Employee and Spouse |
FAM | Family |
IND | Individual |
SPC | Spouse and Children |
SPO | Spouse Only |
The following are possible values for timePeriodCode and timePeriod fields:
Time Period Code | Time Period |
---|---|
6 | Hour |
7 | Day |
13 | 24 Hours |
21 | Years |
22 | Service Year |
23 | Calendar Year |
24 | Year to Date |
25 | Contract |
26 | Episode |
27 | Visit |
28 | Outlier |
29 | Remaining |
30 | Exceeded |
31 | Not Exceeded |
32 | Lifetime |
33 | Lifetime Remaining |
34 | Month |
35 | Week |
36 | Admission |
The following are possible values for statusCode and status fields for plans
and benefits
:
Status Code | Status |
---|---|
0 | Coverage Unknown |
1 | Active Coverage |
2 | Active - Full Risk Capitation |
3 | Active - Services Capitated |
4 | Active - Services Capitated to Primary Care Physician |
5 | Active - Pending Investigation |
6 | Inactive |
7 | Inactive - Pending Eligibility Update |
8 | Inactive - Pending Investigation |
The following are possible values for quantityQualifierCode and quantityQualifier fields:
Quantity Qualifier Code | Quantity Qualifier |
---|---|
8H | Minimum |
99 | Quantity Used |
CA | Covered - Actual |
CE | Covered - Estimated |
D3 | Number of Co-insurance Days |
DB | Deductible Blood Units |
DY | Days |
HS | Hours |
LA | Life-time Reserve - Actual |
LE | Life-time Reserve - Estimated |
M2 | Maximum |
MN | Month |
P6 | Number of Services or Procedures |
QA | Quantity Approved |
S7 | Maximum Age |
S8 | Minimum Age |
VS | Visits |
YY | Years |
The following are possible values for categoryCode and category fields for various contacts
and Coverages.requestingProvider
and Coverages.plans.primaryCareProvider
:
Category Code | Category |
---|---|
1 | Active Coverage |
2 | Active - Full Risk Capitation |
3 | Active - Services Capitated |
4 | Active - Services Capitated to Primary Care Physician |
5 | Active - Pending Investigation |
6 | Inactive |
7 | Inactive - Pending Eligibility Update |
8 | Inactive - Pending Investigation |
A | Co-Insurance |
B | Co-Payment |
C | Deductible |
CB | Coverage Basis |
D | Benefit Description |
E | Exclusions |
F | Limitations |
G | Out of Pocket (Stop Loss) |
H | Unlimited |
I | Non-Covered |
J | Cost Containment |
K | Reserve |
L | Primary Care Provider |
M | Pre-existing Condition |
MC | Managed Care Coordinator |
N | Services Restricted to Following Provider |
O | Not Deemed a Medical Necessity |
P | Benefit Disclaimer |
Q | Second Surgical Opinion Required |
R | Other or Additional Payor |
S | Prior Year(s) History |
T | Card(s) Reported Lost/Stolen |
U | Contact Following Entity for Eligibility or Benefit Information |
V | Cannot Process |
W | Other Source of Data |
X | Health Care Facility |
Y | Spend Down |
The following are possible values for placeOfServiceCode and placeOfService fields:
Place of Service Code | Place of Service |
---|---|
01 | Pharmacy |
03 | School |
04 | Homeless Shelter |
05 | Indian Health Service Free-standing Facility |
06 | Indian Health Service Provider-based Facility |
07 | Tribal 638 Free-standing Facility |
08 | Tribal 638 Provider-based Facility |
11 | Office |
12 | Home |
13 | Assisted Living Facility |
14 | Group Home |
15 | Mobile Unit |
19 | Off Campus-Outpatient Hospital |
20 | Urgent Care Facility |
21 | Inpatient Hospital |
22 | On Campus-Outpatient Hospital |
23 | Emergency Room - Hospital |
24 | Ambulatory Surgical Center |
25 | Birthing Center |
26 | Military Treatment Facility |
31 | Skilled Nursing Facility |
32 | Nursing Facility |
33 | Custodial Care Facility |
34 | Hospice |
41 | Ambulance - Land |
42 | Ambulance - Air or Water |
49 | Independent Clinic |
50 | Federally Qualified Health Center |
51 | Inpatient Psychiatric Facility |
52 | Psychiatric Facility - Partial Hospitalization |
53 | Community Mental Health Center |
54 | Intermediate Care Facility/Mentally Retarded |
55 | Residential Substance Abuse Treatment Facility |
56 | Psychiatric Residential Treatment Center |
57 | Non-residential Substance Abuse Treatment Facility |
60 | Mass Immunization Center |
61 | Comprehensive Inpatient Rehabilitation Facility |
62 | Comprehensive Outpatient Rehabilitation Facility |
65 | End-State Renal Disease Treatment Facility |
71 | Public Health Clinic |
72 | Rural Health Clinic |
81 | Independent Laboratory |
99 | Other Place of Service |
The following are possible values for typeCode and code fields:
Note: In addition to the following list, type could also be a procedureCode.
Type Code | Code |
---|---|
85 | AIDS |
84 | Abortion |
64 | Acupuncture |
28 | Adjunctive Dental Services |
57 | Air Transportation |
AJ | Alcoholism |
GY | Allergy |
79 | Allergy Testing |
15 | Alternate Method Dialysis |
13 | Ambulatory Service Center Facility |
7 | Anesthesia |
97 | Anesthesiologist |
71 | Audiology Exam |
10 | Blood Charges |
91 | Brand Name Prescription Drug |
B2 | Brand Name Prescription Drug - Formulary |
B3 | Brand Name Prescription Drug - Non-Formulary |
B1 | Burn Care |
58 | Cabulance |
87 | Cancer |
BL | Cardiac |
BG | Cardiac Rehabilitation |
CQ | Case Management |
78 | Chemotherapy |
33 | Chiropractic |
34 | Chiropractic Office Visits |
16 | Chronic Renal Disease (CRD) Equipment |
BD | Cognitive Therapy |
3 | Consultation |
C1 | Coronary Care |
BC | Day Care (Psychiatric) |
37 | Dental Accident |
35 | Dental Care |
36 | Dental Crowns |
DG | Dermatology |
DS | Diabetic Supplies |
23 | Diagnostic Dental |
5 | Diagnostic Lab |
73 | Diagnostic Medical |
4 | Diagnostic X-Ray |
76 | Dialysis |
63 | Donor Procedures |
AK | Drug Addiction |
DM | Durable Medical Equipment |
12 | Durable Medical Equipment Purchase |
18 | Durable Medical Equipment Rental |
86 | Emergency Services |
BP | Endocrine |
26 | Endodontics |
AR | Experimental Drug Therapy |
BR | Eye |
CP | Eyewear and Eyewear Accessories |
82 | Family Planning |
CO | Flu Vaccination |
AM | Frames |
89 | Free Standing Prescription Drug |
BN | Gastrointestinal |
60 | General Benefits |
92 | Generic Prescription Drug |
GF | Generic Prescription Drug - Formulary |
GN | Generic Prescription Drug - Non-Formulary |
BT | Gynecological |
30 | Health Benefit Plan Coverage |
42 | Home Health Care |
43 | Home Health Prescriptions |
44 | Home Health Visits |
45 | Hospice |
47 | Hospital |
53 | Hospital - Ambulatory Surgical |
51 | Hospital - Emergency Accident |
52 | Hospital - Emergency Medical |
48 | Hospital - Inpatient |
50 | Hospital - Outpatient |
49 | Hospital - Room and Board |
80 | Immunizations |
61 | In-vitro Fertilization |
BA | Independent Medical Evaluation |
83 | Infertility |
72 | Inhalation Therapy |
IC | Intensive Care |
BS | Invasive Procedures |
AO | Lenses |
59 | Licensed Ambulance |
54 | Long Term Care |
BM | Lymphatic |
62 | MRI/CAT Scan |
90 | Mail Order Prescription Drug |
BW | Mail Order Prescription Drug: Brand Name |
BX | Mail Order Prescription Drug: Generic |
55 | Major Medical |
CM | Mammogram, High Risk Patient |
CN | Mammogram, Low Risk Patient |
BE | Massage Therapy |
69 | Maternity |
27 | Maxillofacial Prosthetics |
1 | Medical Care |
56 | Medically Related Transportation |
MH | Mental Health |
CG | Mental Health Facility - Inpatient |
CH | Mental Health Facility - Outpatient |
CE | Mental Health Provider - Inpatient |
CF | Mental Health Provider - Outpatient |
NI | Neonatal Intensive Care |
BQ | Neurology |
65 | Newborn Care |
AQ | Nonmedically Necessary Physical |
BI | Nursery |
BU | Obstetrical |
BV | Obstetrical/Gynecological |
AD | Occupational Therapy |
ON | Oncology |
40 | Oral Surgery |
38 | Orthodontics |
BK | Orthopedic |
9 | Other Medical |
77 | Otological Exam |
BB | Partial Hospitalization (Psychiatric) |
66 | Pathology |
BH | Pediatric |
24 | Periodontics |
88 | Pharmacy |
AE | Physical Medicine |
PT | Physical Therapy |
BY | Physician Visit - Office: Sick |
BZ | Physician Visit - Office: Well |
32 | Plan Waiting Period |
19 | Pneumonia Vaccine |
93 | Podiatry |
95 | Podiatry - Nursing Home Visits |
94 | Podiatry - Office Visits |
17 | Pre-Admission Testing |
74 | Private Duty Nursing |
CB | Private Duty Nursing - Home |
CA | Private Duty Nursing - Inpatient |
96 | Professional (Physician) |
A3 | Professional (Physician) Visit - Home |
99 | Professional (Physician) Visit - Inpatient |
A1 | Professional (Physician) Visit - Nursing Home |
98 | Professional (Physician) Visit - Office |
A0 | Professional (Physician) Visit - Outpatient |
A2 | Professional (Physician) Visit - Skilled Nursing Facility |
75 | Prosthetic Device |
39 | Prosthodontics |
A4 | Psychiatric |
A7 | Psychiatric - Inpatient |
A8 | Psychiatric - Outpatient |
A5 | Psychiatric - Room and Board |
A6 | Psychotherapy |
PU | Pulmonary |
BF | Pulmonary Rehabilitation |
6 | Radiation Therapy |
A9 | Rehabilitation |
AB | Rehabilitation - Inpatient |
AC | Rehabilitation - Outpatient |
AA | Rehabilitation - Room and Board |
RN | Renal |
14 | Renal Supplies in the Home |
RT | Residential Psychiatric Treatment |
46 | Respite Care |
25 | Restorative |
41 | Routine (Preventive) Dental |
AN | Routine Exam (Vision) |
81 | Routine Physical |
CL | Screening Laboratory |
CK | Screening X-ray |
20 | Second Surgical Opinion |
AG | Skilled Nursing Care |
AH | Skilled Nursing Care - Room and Board |
BJ | Skin |
67 | Smoking Cessation |
22 | Social Work |
AF | Speech Therapy |
AI | Substance Abuse |
CI | Substance Abuse Facility - Inpatient |
CJ | Substance Abuse Facility - Outpatient |
2 | Surgical |
8 | Surgical Assistance |
CD | Surgical Benefits - Facility |
CC | Surgical Benefits - Professional (Physician) |
21 | Third Surgical Opinion |
TC | Transitional Care |
TN | Transitional Nursery Care |
70 | Transplants |
UC | Urgent Care |
11 | Used Durable Medical Equipment |
AL | Vision (Optometry) |
68 | Well Baby Care |
DELETE /V1/COVERAGES/:ID
You can delete a particular coverage by issuing a DELETE against it.
When you make a valid request, the resource will return a status code of
204
if the resource was successfully deleted.
$ curl -X DELETE "https://api.availity.com/availity/v1/coverages/0001194499098175762045868562105833796329766732695450956940743265"
->
HTTP/1.1 204 No Content
x-api-id: 54cbda17-e010-44f3-a38c-b038c106e0bf
X-Session-ID: 54cbda17-e010-44f3-a38c-b038c106e0bf
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Tue, 24 Feb 2015 20:58:03 GMT
X-Global-Transaction-ID: 34319985
Connection: close
Configurations
The Configurations
service is an extremely powerful API that will make building custom applications that support multiple health plans very easy.
If you've ever tried to support access to multiple heath plans in your application you know how difficult this can be. Even though there are standards in place, such as ASC X12 transactions and HL7, a lot of health plans will support these standards at different levels. This would traditional leave the burden up to you, the developer, on how to normalize this inforamtion across a range of health plans you need to support.
This is where the Availity Configurations
API will help save you many weeks of development time. It provides details for each payer we support and provides details such as what are the required fields for a specific payer, required field combinations, validation patterns that can be used by your front end applications, code/values for populating selection groups, etc.
All of this information is kept up to date with the health plans. By utilizing this service to build your application you can ensure you always have the most current data and validation requirements and make them available to your application.
The Resource
Field | Type | Description |
---|---|---|
type | String | The type of resource that this Configuration describes. |
subtypeId | String | The subtype of the resource that this Configuration describes. |
subtypeValue | String | A description of the subtype of the resources that this Configurations describes. |
payerId | String | The id of the health plan that this Configuration is for. |
payerName | String | The name of the health plan that this Configuration is for. |
elements | Object | The elements object describes the input rules for each component of the resource. |
requiredFieldCombinations | Object | The requiredFieldCombinations object provides groups of minimum required fields that can be entered. At least one of each entry must be satisfied. |
Example Use Case
Let's take a look at an example using this service that will allow us to discover what fields and field combinations are required to call the Coverages
API. When you look at the Coverages
documentation you will notice that for the GET request, all of the parameters are identified as Required: No
.
The first thing you'll want to do to begin using the Coverages
service is to call the Configurations
service and specify the type
and payerId
that you want to send a request to. The Coverages
service type is 270
and you can find a list of supported payerId
's on our developer portal here: Supported Health Plans.
Here is an excerpt from the Configurations
service response for the payer Florida Blue
:
{
"configurations": [
{
"type": "270",
"payerId": "BCBSF",
"payerName": "FLORIDA BLUE",
"elements": {
"providerLastName": {
"type": "Text",
"label": "Provider Last Name",
"order": 0,
"allowed": true,
"required": false,
"errorMessage": "Please enter a valid Provider Last Name.",
"defaultValue": "AVAILITY",
"pattern": "^[a-zA-Z0-9\\s!&,()+'\\-./;?=#\\\\]{1,60}$",
"maxLength": 60
},
"providerFirstName": {
"type": "Text",
"label": "Provider First Name",
"order": 1,
"allowed": true,
"required": false,
"errorMessage": "Please enter a valid Provider First Name.",
"pattern": "^[a-zA-Z0-9\\s!&,()+'\\-./;?=#\\\\]{1,35}$",
"maxLength": 35
},
"providerType": {
"type": "Unsupported",
"label": "Provider Type",
"order": 2,
"allowed": false,
"required": false,
"errorMessage": "This field is not supported."
},
"providerNpi": {
"type": "Text",
"label": "Provider NPI",
"order": 4,
"allowed": true,
"required": false,
"errorMessage": "Enter a valid National Provider Identifier (NPI) containing 10 numeric digits and beginning with a 1, 2, 3, or 4.",
"pattern": "^[1-4][0-9]{9}$",
"maxLength": 10
},
"providerTaxId": {
"type": "Text",
"label": "Provider Tax ID",
"order": 5,
"allowed": true,
"required": false,
"errorMessage": "Enter a valid Tax ID containing nine numeric digits and no dashes.",
"pattern": "^[0-9]{9}$",
"maxLength": 9
}
}
}
]
}
The first part of the response shows the transaction type - 270
for Eligibility, the payer Id, and the payer name.
Under the elements
object is where we find the list of fields this payer supports and whether they are required or not. If a parameter is not supported the field type is listed as Unsupported
.
Let's look at the providerLastName
parameter and walk through each of the attributes:
type
: The data type for this parameter.label
: The name that can be used to display in your applications UI.order
: An optional ordering index you can use when laying out fields in your applications UI.allowed
: Boolean indicator specifying if this parameter is valid to use.required
: Boolean indicator specifying if this parameter is required.errorMessage
: An error message you can use in your applications UI if this field does not pass validation. This can be used if you perform client side validation or if this field is in error after you've submitted a request and it comes back invalid.defaultValue
: A default value that can be used for pre-populating a field in your applications UI.pattern
: A regular expression you can use to validate input parameter values.maxLength
: The maximum legth allowed for this parameter.
Next let's look at the providerType
paramter. The first thing we notice is the type
attribute is of type Unsupported
. That tells us that for this transaction type Florida Blue does not support the providerType
parameter so we should not send it with our request.
GET /V1/CONFIGURATIONS
You can find and retrieve Configurations using this endpoint.
Parameters
Parameter | Type | Description |
---|---|---|
type | String | The type of configuration you are looking for. |
subtypeId | String | The subtype id of the configuration you are looking for. |
payerId | String | The health plan id of the configuration you are looking for. |
Examples
$ curl -X GET -i https://api.availity.com/availity/v1/configurations?type=270
->
HTTP/1.1 200 OK
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
X-Global-Transaction-ID: 36774789
Connection: close
{
"totalCount": 2,
"count": 2,
"offset": 0,
"limit": 50,
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/configurations?type=270"
}
},
"configurations": [
{
"type": "270",
"payerId": "BCBSF",
"payerName" : "FLORIDA BLUE"
},
{
"type": "270",
"payerId": "HUMANA",
"payerName" : "Humana"
}
]
}
$ curl -X GET -i https://api.availity.com/availity/v1/configurations?type=service-reviews&subtypeId=HS&payerId=BCBSF
->
HTTP/1.1 200 OK
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
X-Global-Transaction-ID: 36774789
Connection: close
{
"totalCount": 1,
"count": 1,
"offset": 0,
"limit": 50,
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/configurations?type=service-reviews&subtypeId=HS&payerId=BCBSF"
}
},
"configurations": [
{
"type": "service-reviews",
"subtypeId" : "HS",
"subtypeValue" : "Health Service Review",
"payerId": "BCBSF",
"payerName" : "FLORIDA BLUE"
"elements" : {
"requestingProvider" : {
"type": "Object",
"order": 0,
"allowed" : true,
"required" : true,
"elements" : {
"npi" : {
"type": "Text",
"label": "Requesting Provider NPI",
"order": 0,
"allowed": true,
"required": false,
"errorMessage": "Enter a valid Requesting Provider NPI.",
"pattern": "^[1-4][0-9]{9}$",
"maxLength": 10
},
"taxId" : {
"type": "Text",
"label": "Requesting Provider Tax ID",
"order": 1,
"allowed": true,
"required": false,
"errorMessage": "Enter a valid Requesting Provider Tax ID",
"pattern": "^[0-9]{9}$",
"maxLength": 9
}
}
},
"patient" : {
"type": "Object",
"order": 1,
"allowed" : true,
"required" : true,
"elements" {
"birthDate" : {
"type": "Date",
"label": "Patient Date of Birth",
"order": 0,
"allowed": true,
"required": true,
"errorMessage": "Enter a valid date that is not in the future.",
"min": "1870-01-01T05:00:00.000+0000",
"max": "2015-05-06T03:59:59.999+0000"
},
"medicareCoverage" : {
"type": "Boolean",
"label": "Medicare Coverage",
"order": 1,
"allowed": false,
"required": false,
"errorMessage": "Please enter a valid Medicare Coverage.",
"allowedWhen": {
"serviceTypeCode": {
"equalTo": "42"
}
},
"requiredWhen": {
"serviceTypeCode": {
"equalTo": "42"
}
}
}
}
},
"serviceTypeCode" : {
"type": "Enumeration",
"label": "Type",
"order": 2,
"allowed": true,
"required": true,
"errorMessage": "Please enter a valid Service Type.",
"mode": "DropDown",
"values": [
{
"code": "1",
"value": "Medical Care"
},
{
"code": "42",
"value": "Home Health Care"
}
]
},
"diagnoses" : {
"type": "ObjectArray",
"order": 3,
"errorMessage": "Please enter between 1 and 12 valid Diagnoses.",
"maxRepeats": 12,
"allowed": true,
"objectTypes": {
"diagnosis": {
"label": "Diagnosis",
"maxInstances": 12,
"required": true
}
},
"elements": {
"code": {
"type": "Collection",
"label": "Diagnosis Code",
"order": 0,
"allowed": true,
"required": true,
"errorMessage": "Please enter a valid Diagnosis Code.",
"valuesWhen": {
"qualifierCode" : [
{
"equalTo" : "BF",
"values": {
"href": "https://api.availity.com/availity/v1/codes?list=ICD9CMD"
}
}
]
}
}
}
}
},
"requiredFieldCombinations" : {
"requestingProvider" : [
["npi"],
["taxId"]
]
}
}
]
}
Available Information
type | subtypeId | payerId | Usage |
---|---|---|---|
270 | - | - | Returns the list of health plans that support Coverages. |
270 | - | a payer id | Returns the validation rules for Coverages for the specified health plan. |
claim-statuses | - | - | Returns the list of payers that support ClaimStatues. |
claim-statuses | - | a payer id | Returns the validation rules for ClaimStatuses for the specified payer. |
professional-claims | - | - | Returns the list of payers that support ProfessionalClaims. |
professional-claims | PRE_DETERMINATION | a payer id | Returns the validation rules for a predetermination ProfessionalClaim for the specified payer. |
institutional-claims | - | - | Returns the list of payers that support InstitutionalClaims. |
institutional-claims | PRE_DETERMINATION | a payer id | Returns the validation rules for a predetermination InstitutionalClaim for the specified payer. |
service-reviews | - | - | Returns the list of health plans that support each type of ServiceReview. |
service-reviews | - | a payer id | Returns the list of types of ServiceReviews supported by the specified health plan. |
service-reviews | AR | - | Returns the list of health plans that support Admission Review (inpatient) ServiceReviews. |
service-reviews | HS | - | Returns the list of health plans that support Health Services Review (outpatient) ServiceReviews. |
service-reviews | SC | - | Returns the list of health plans that support Specialty Care Review (referral) ServiceReviews. |
service-reviews | AR | a payer id | Returns the validation rules for Admission Review (inpatient) ServiceReviews for the specified health plan. |
service-reviews | HS | a payer id | Returns the validation rules for Health Services Review (outpatient) ServiceReviews for the specified health plan. |
service-reviews | SC | a payer id | Returns the validation rules for Specialty Care Review (referral) ServiceReviews. |
service-reviews-inquiry | - | - | Returns the list of health plans that support ServiceReview inquiries. |
service-reviews-inquiry | - | a payer id | Returns the validation rules for ServiceReview inquiries for the specified health plan. |
Service Reviews
This resource represents a request to obtain authorization to perform a service or refer a patient to another provider. Your application can use the endpoints defined for it to find, create, and manage these requests.
WORKING WITH THE DEMO ENDPOINTS
Availity allows you to specify the type of response you want when interacting with our Service Review demonstration service by sending a header (X-Api-Mock-Scenario-ID) with the appropriate response scenario id. The supported response scenarios are listed below.
For POST methods send an empty JSON body such as: "{}"
Response Scenario ID | Method | HTTP Status | Description |
---|---|---|---|
SR-CreateRequestAccepted-i | POST | 202 | Availity is in the process of sending the member's service review information to the health plan. |
SR-DeleteRequestAccepted-i | DELETE | 202 | Availity is processing your delete request. |
SR-CreateRequestError-i | POST | 400 | Your request failed Availity's input validation rules. |
SR-DeleteRequestError-i | DELETE | 400 | Your request failed Availity's delete validation rules. |
SR-GetComplete-i | GET - use id 12345678 | 200 | Availity has successfully retrieved the member's service review information from the health plan. |
SR-GetInProgress-i | GET - use id 12345678 | 202 | Availity is processing your request. |
SR-GetPayerDown-i | GET - use id 12345678 | 504 | Availity did not receive a response from the health plan within the time allotted. You should try your request again later. |
SR-UpdateRequestAccepted-i | PUT | 202 | Availity is currently processing your request. |
SR-UpdateRequestError-i | PUT | 400 | Your request failed Availity's input validation rules. |
SR-GetPayerError-i | GET | 400 | The health plan indicated that something is wrong with the request. The resource should have a list of validationMessages. Correct and resubmit the request. |
SR-GetRetrying-i | GET - use id 12345678 | 202 | The health plan did not respond. Availity is retrying the request |
SRI-GetAccepted-i | GET | 202 | Availity is currently processing your request. |
SRI-GetComplete-i | GET | 200 | Availity has successfully retrieved the member's service review inquiry information from the health plan. |
SRI-GetInProgress-i | GET | 202 | Availity is currently processing your request. |
SRI-GetPayerError-i | GET | 400 | The health plan indicated that something is wrong with the request. The resource should have a list of validationMessages. Correct and resubmit the request. |
SRI-GetPayerDown-i | GET | 504 | Availity did not receive a response from the health plan within the time allotted. You should try your request again later. |
SRI-GetRetrying-i | GET – use id 12345678 | 202 | The health plan did not respond. Availity is retrying the request |
SRI-GetRequestError-i | GET | 400 | The health plan indicated that something is wrong with the request. The resource should have a list of validationMessages. Correct and resubmit the request |
You can confirm you've received a mock response by inspecting the response headers. You should see the following header:
X-Api-Mock-Response: true
THE RESOURCE
Field | Type | Description |
---|---|---|
id | String | A unique identifier that Availity has assigned to this ServiceReview. |
createdDate | Timestamp | The date and time when this item was created in Availity's system. |
updatedDate | Timestamp | The date and time when this item was last updated. |
expirationDate | Timestamp | The date and time when this item will be removed from Availity's system. |
customerId | String | The id of the Availity customer that owns this ServiceReview. Availity may ask for this during support calls. |
controlNumber | String | The id of the last transaction associated with this ServiceReview. The health plan may ask for this during support calls. |
updatable | boolean | A flag that indicates whether or not this ServiceReview can be updated. |
updatableFields | String Array | Fields in this service review that can be updated. |
deletable | boolean | A flag that indicates whether or not this ServiceReview can be deleted. |
status | String | A description of the current status of this ServiceReview. |
statusCode | String | A code that represents the current status. |
statusReasons | Object Array | An array of reasons that the health plan has given for the current status. |
statusReasons.value | String | A description of the status reason. |
statusReasons.code | String | A code that represents the status reason. |
validationMessages | Object Array | An array of error messages explaining problems with this ServiceReview. Errors encountered during validation at Availity will have a field and possibly an index. Errors returned by the health plan will have a code. |
validationMessages.errorMessage | String | A description of the problem. |
validationMessages.field | String | The field of the ServiceReview that has the problem. |
validationMessages.index | Number* | The index (if applicable) of the item with the field that has the problem. |
validationMessages.code | String | A code identifying the error. |
certificationIssueDate | Date | The date on which the health plan authorized the service or referral. |
certificationEffectiveDate | Date | The date on which the health plan's authorization will take effect. |
certificationExpirationDate | Date | The date on which the health plan's authorization will expire. |
certificationNumber | String | The authorization number assigned by the health plan to be used on claims. |
referenceNumber | String | A reference number assigned by the health plan to pended or otherwise incomplete ServiceReviews. |
traceNumbers | String Array | An array of trace numbers that the health plan has assigned to this ServiceReview. |
requestType | String | A description type of request (inpatient service, outpatient service, or referral). |
requestTypeCode | String | A code respresenting the type of request. |
payer | Object | An object representing the health plan of the patient. |
payer.id | String | The Availity payer id for the health plan. |
payer.name | String | The name of the health plan. |
payer.contactName | String | The contact name of the health plan. |
payer.phone | String | The phone number of the health plan. |
payer.extension | String | The phone number extension of the health plan. |
payer.fax | String | The fax number of the health plan. |
payer.emailAddress | String | The email address of the health plan. |
payer.url | String | The website address of the health plan. |
payerNotes | Object Array | An array of notes that the health plan has added to this ServiceReview. |
payerNotes.message | String | The text of a note. |
requestingProvider | Object | An object representing the provider that is requesting authorization to perform a service or refer a patient. |
requestingProvider.lastName | String | The last or business name of the requesting provider. |
requestingProvider.firstName | String | The first name of the requesting provider. |
requestingProvider.middleName | String | The middle name of the requesting provider. |
requestingProvider.suffix | String | The suffix of the requesting provider. |
requestingProvider.npi | String | The national provider id of the requesting provider. |
requestingProvider.taxId | String | The tax id of the requesting provider. |
requestingProvider.payerAssignedProviderId | String | The health plan assigned id of the requesting provider. |
requestingProvider.submitterId | String | The submitter id of the requesting provider. |
requestingProvider.specialty | String | A description of the specialty of the requesting provider. |
requestingProvider.specialtyCode | String | A code that represents the specialty of the requesting provider. |
requestingProvider.addressLine1 | String | The first line of the address of the requesting provider. |
requestingProvider.addressLine2 | String | The second line of the address of the requesting provider. |
requestingProvider.city | String | The city of the requesting provider. |
requestingProvider.state | String | The name of the state of the requesting provider. |
requestingProvider.stateCode | String | The code of the state of the requesting provider. |
requestingProvider.zipCode | String | The ZIP code of the requesting provider. |
requestingProvider.contactName | String | A contact name for the requesting provider. |
requestingProvider.phone | String | The phone number of the requesting provider. |
requestingProvider.extension | String | The phone extension of the requesting provider. |
requestingProvider.fax | String | The fax number of the requesting provider. |
requestingProvider.emailAddress | String | The email address of the requesting provider. |
requestingProvider.url | String | The website address of the requesting provider. |
subscriber | Object | An object representing the health plan subscriber. |
subscriber.memberId | String | The member id of the subscriber. |
subscriber.lastName | String | The last name of the subscriber. |
subscriber.firstName | String | The first name of the subscriber. |
subscriber.middleName | String | The middle name of the subscriber. |
subscriber.suffix | String | The suffix of the subscriber. |
subscriber.addressLine1 | String | The first line of the address of the subscriber. |
subscriber.addressLine2 | String | The second line of the address of the subscriber. |
subscriber.city | String | The city of the subscriber. |
subscriber.state | String | The name of the state of the subscriber. |
subscriber.stateCode | String | The code of the state of the subscriber. |
subscriber.zipCode | String | The ZIP code of the subscriber. |
patient | Object | An object representing the patient having the service or being referred. |
patient.lastName | String | The last name of the patient. |
patient.firstName | String | The first name of the patient. |
patient.middleName | String | The middle name of the patient. |
patient.suffix | String | The suffix of the patient. |
patient.subscriberRelationship | String | A description of the patient's relationship to the subscriber. |
patient.subscriberRelationshipCode | String | A code representing the patient's relationship to the subscriber. |
patient.birthDate | Date | The birth date of the patient. |
patient.gender | String | A description of the gender of the patient. |
patient.genderCode | String | A code representing the gender of the patient. |
patient.addressLine1 | String | The first line of the address of the patient. |
patient.addressLine2 | String | The second line of the address of the patient. |
patient.city | String | The city of the patient. |
patient.state | String | The name of the state of the patient. |
patient.stateCode | String | The code of the state that the patient resides. |
patient.zipCode | String | The ZIP code of the patient. |
patient.status | String | A description of the status of the patient. |
patient.statusCode | String | A code representing the status of the patient. |
patient.condition | String | A description of condition of the patient. |
patient.conditionCode | String | A code representing the condition of the patient. |
patient.medicareCoverage | String | An indicator identifying whether or not this patient has Medicare coverage. |
patient.prognosis | String | A description of the prognosis of the patient. |
patient.prognosisCode | String | A code representing the prognosis of the patient. |
diagnoses | Object Array | An array of diagnoses that are related to the service or referral. |
diagnoses.qualifier | String | The description of the qualifier indicating what type of diagnosis code is used. |
diagnoses.qualifierCode | String | A code representing the qualifier indicating what type of diagnosis code is used. |
diagnoses.value | String | A description of the diagnosis. |
diagnoses.code | String | A code representing the diagnosis. |
diagnoses.date | Date | The date that the patient was given this diagnosis. |
serviceType | String | A description of the type of service to be performed. |
serviceTypeCode | String | A code representing the type of service to be performed. |
placeOfService | String | A description of the place of service. |
placeOfServiceCode | String | A code representing the place of service. |
serviceLevel | String | A description of the level of service. |
serviceLevelCode | String | A code representing the level of service. |
fromDate | Date | The service start date or admission date. |
toDate | Date | The service end date or discharge date. |
quantity | String | The number of units associated with the service. |
quantityType | String | A description of the quantity units. |
quantityTypeCode | String | A code representing the quantity units. |
admissionType | String | A description of the type of admission on an inpatient authorization request. |
admissionTypeCode | String | A code representing the type of admission on an inpatient authorization request. |
admissionSource | String | A description of the source of admission on an inpatient authorization request. |
admissionSourceCode | String | A code representing the source of admission on an inpatient authorization request. |
nursingHomeResidentialStatus | String | A description of the nursing home residential status on an inpatient authorization request. |
nursingHomeResidentialStatusCode | String | A code representing the nursing home residential status on an inpatient authorization request. |
homeHealthStartDate | Date | The start of home health services for a home health outpatient authorization request. |
homeHealthCertificationPeriodStartDate | Date | The start of the home health certification period for a home health outpatient authorization request. |
homeHealthCertificationPeriodEndDate | Date | The end of the home health certification period for a home health outpatient authorization request. |
transportType | String | A description of the type of transport being performed on a medically related transport outpatient authorization request. |
transportTypeCode | String | A code representing the type of transport being performed on a medically related transport outpatient authorization request. |
transportDistance | String | The distance the patient will be transported on a medically related transport outpatient authorization request. |
transportPurpose | String | The purpose of transporting the patient. |
transportLocations | Object Array | An array of locations associated with a medically related transport outpatient authorization request. |
transportLocations.name | String | The name of the transport location. |
transportLocations.addressLine1 | String | Line one of the address of the transport location. |
transportLocations.addressLine2 | String | Line two of the address of the transport location. |
transportLocations.city | String | The city of the transport location. |
transportLocations.state | String | The name of the state of the transport location. |
transportLocations.stateCode | String | The code of the state of the transport location. |
transportLocations.zipCode | String | The ZIP code of the transport location. |
renderingProviders | Object Array | An array of providers (that will render the service are being referred to) and facilities (where the service will be performed). |
renderingProviders.role | String | A description of the role of this rendering provider. |
renderingProviders.roleCode | String | A code representing the role of this rendering provider. |
renderingProviders.lastName | String | The last or business name of this rendering provider. |
renderingProviders.firstName | String | The first name of this rendering provider. |
renderingProviders.middleName | String | The middle name of this rendering provider. |
renderingProviders.suffix | String | The suffix of this rendering provider. |
renderingProviders.npi | String | The national provider id of this rendering provider. |
renderingProviders.taxId | String | The tax id of this rendering provider. |
renderingProviders.payerAssignedProviderId | String | The health plan assigned provider id of this rendering provider. |
renderingProviders.specialty | String | A description of the specialty of this rendering provider. |
renderingProviders.specialtyCode | String | A code representing the specialty of this rendering provider. |
renderingProviders.addressLine1 | String | The first line of the address of this rendering provider. |
renderingProviders.addressLine2 | String | The second line of the address of this rendering provider. |
renderingProviders.city | String | The city of this rendering provider. |
renderingProviders.state | String | The name of the state of this rendering provider. |
renderingProviders.stateCode | String | The code of the state of this rendering provider. |
renderingProviders.zipCode | String | The ZIP code of this rendering provider. |
renderingProviders.contactName | String | A contact name for this rendering provider. |
renderingProviders.phone | String | The phone number of this rendering provider. |
renderingProviders.extension | String | The phone extension of this rendering provider. |
renderingProviders.fax | String | The fax number of this rendering provider. |
renderingProviders.emailAddress | String | The email address of this rendering provider. |
renderingProviders.url | String | The website address of this rendering provider. |
procedures | Object Array | An array of procedures to be performed. |
procedures.status | String | A description of the authorization status of this procedure. |
procedures.statusCode | String | A code representing the authorization status of this procedure. |
procedures.statusReasons | String | An array of reasons the health plan has given for the status of authorization on this procedure. |
procedures.statusReasons.value | String | A description of the reason for the status. |
procedures.statusReasons.code | String | A code representing the reason for the status. |
procedures.certificationIssueDate | Date | The date on which the health plan authorized the procedure. |
procedures.certificationEffectiveDate | Date | The date on which the health plan's authorization will take effect. |
procedures.certificationExpirationDate | Date | The date on which the health plan's authorization will expire. |
procedures.certificationNumber | String | The authorization number assigned by the health plan to be used on claims. |
procedures.qualifier | String | A description of the category of procedure code. |
procedures.qualifierCode | String | A code representing the category of procedure code. |
procedures.value | String | A description of the procedure. |
procedures.code | String | A code representing the procedure. |
procedures.modifier1 | String | A description of the first modifier applied to this procedure. |
procedures.modifier1Code | String | A code representing the first modifier applied to this procedure. |
procedures.modifier2 | String | A description of the second modifier applied to this procedure. |
procedures.modifier2Code | String | A code representing the second modifier applied to this procedure. |
procedures.modifier3 | String | A description of the third modifier applied to this procedure. |
procedures.modifier3Code | String | A code representing the third modifier applied to this procedure. |
procedures.modifier4 | String | A description of the fourth modifier applied to this procedure. |
procedures.modifier4Code | String | A code representing the fourth modifier applied to this procedure. |
procedures.description | String | A free form description written by the provider describing this procedure. |
procedures.quantity | String | The quantity of this procedure to be rendered. |
procedures.quantityType | String | A description of the type of quantity. |
procedures.quantityTypeCode | String | A code representing the type of quantity. |
procedures.fromDate | Date | The start date of the procedure. |
procedures.toDate | Date | The end date of procedure. |
procedures.payerNotes | Object Array | An array of notes that the health plan has added to this procedure. |
procedures.payerNotes.message | String | The text of a note. |
procedures.traceNumbers | String Array | An array of trace numbers that the health plan has assigned to this procedure. |
SERVICE REVIEW STATUSES
ServiceReview.statusCode | ServiceReview.status | Description |
---|---|---|
A1 | Certified in Total | The health plan has fully authorized the request. The resource will have a certificationNumber that you can use on a claim. |
A2 | Certified - Partial | The health plan has partially authorized the request. Check the procedures for more details. |
A3 | Not Certified | The health plan has denied the request. Check the statusReasons for more details. |
A6 | Modified | The health plan has indicated that the request has been modified. Check back later. |
C | Cancelled | The health plan has indicated that the request has been cancelled. |
CT | Contact Payer | The health plan has indicated that the requesting provider should contact them. See the health plan object in the resource for contact information. |
NA | No Action Required | The health plan has indicated that an authorization is not required for the request. |
51 | Complete | The health plan has indicated that the request is complete. |
71 | Term Expired | The health plan has indicated that the term has expired. |
POST /V2/SERVICE-REVIEWS
This endpoint creates service reviews asynchronously. To submit a transaction, make a valid request and we will respond with a location header containing a URL you can query for your result.
RESPONSE STATUSES
HTTP Status Code | Description |
---|---|
202 | We are currently processing your request. |
400 | Your request has been rejected. It either failed our validation rules or was rejected by the health plan. The errors property will contain detailed information. Errors that specify a field are Availity validation rule failures. Errors that specify a code are from the health plan. |
500 | We were unable to parse your request. |
VALIDATION RULES
The validation rules for the ServiceReview resource can vary by health plan, the type of authorization being requested, and the type of service to be performed. Availity organizes these rules and makes them available through the Configuration resource. The Configuration resource documents the fields you need to send to create a ServiceReview and explains what values are valid for those fields. See Configurations.
EXAMPLES
If your request is invalid, we will respond with a status code of 400 and a list of errors for you to correct.
$ curl -i -H "Content-Type: application/json" -X POST -d '{
"payer" : {
"id" : "BCBSF",
},
"requestingProvider" : {
"lastName" : "Slice n Dice Discount Surgery"
},
"subscriber" : {
"memberId" : "XBH1823812"
},
"patient" : {
"lastName" : "Smith",
"firstName" : "Bob",
"birthDate" : "1956-01-29",
},
"diagnoses" : [{
"qualifierCode" : "ABF",
"code" : "W5602XA"
}],
"requestTypeCode" : "AR",
"serviceTypeCode" : "1",
"placeOfServiceCode" : "11",
"fromDate" : "2014-05-01",
"toDate" : "2014-05-03",
"quantity" : "3",
"quantityTypeCode" : "DA",
"admissionTypeCode" : "1",
"renderingProviders" : [{
"roleCode" : "71",
"lastName" : "Jones",
"firstName" : "Jane",
"npi" : "1231231238"
},{
"roleCode" : "FA",
"lastName" : "Slice and Dice Surgery Center",
"npi" : "1234912380"
}],
"procedures" : [{
"qualifierCode" : "HC",
"code" : "S8948",
"quantity" : "1",
"quantityTypeCode" : "UN"
}]
}' https://api.availity.com/availity/v2/service-reviews
HTTP/1.1 400 Bad Request
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
X-Global-Transaction-ID: 36774789
Connection: close
{
"userMessage": "The request was invalid. See the 'errors' property for details.",
"developerMessage": "The request was invalid. See the 'errors' property for details.",
"documentation": "https://developer.availity.com/documentation",
"reasonCode": 0,
"statusCode": 400,
"errors": [
{
"field": "requestingProvider.npi",
"errorMessage": "Please enter a valid Requesting Provider NPI.",
"index": 0
}
}
}
If your request is valid, we will respond with a status code of 202 and a location header where you can check back for your response. We will continue to respond in this way until we have heard back from the health plan.
$ curl -i -H "Content-Type: application/json" -X POST -d '{
"payer" : {
"id" : "BCBSF",
},
"requestingProvider" : {
"lastName" : "Slice n Dice Discount Surgery",
"npi" : "1234567893"
},
"subscriber" : {
"memberId" : "XBH1823812"
},
"patient" : {
"lastName" : "Smith",
"firstName" : "Bob",
"birthDate" : "1956-01-29",
},
"diagnoses" : [{
"qualifierCode" : "ABF",
"code" : "W5602XA"
}],
"requestTypeCode" : "AR",
"serviceTypeCode" : "1",
"placeOfServiceCode" : "11",
"fromDate" : "2014-05-01",
"toDate" : "2014-05-03",
"quantity" : "3",
"quantityTypeCode" : "DA",
"admissionTypeCode" : "1",
"renderingProviders" : [{
"roleCode" : "71",
"lastName" : "Jones",
"firstName" : "Jane",
"npi" : "1231231238"
},{
"roleCode" : "FA",
"lastName" : "Slice and Dice Surgery Center",
"npi" : "1234912380"
}],
"procedures" : [{
"qualifierCode" : "HC",
"code" : "S8948",
"quantity" : "1",
"quantityTypeCode" : "UN"
}]
}' https://api.availity.com/availity/v2/service-reviews
->
HTTP/1.1 202 Accepted
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
Location: https://api.availity.com/availity/v2/service-reviews/-11923818311
X-Status-Message: We are processing your request.
GET /V2/SERVICE-REVIEWS/:ID
You can retrieve a service review using this endpoint.
RESPONSE STATUSES
HTTP Status Code | Description |
---|---|
200 | We are done processing your request and the response body contains the result. |
202 | We are currently processing your request. We may be retrying it. The X-Status-Message header will contain additional detail. |
404 | We did not find a ServiceReview with the id that you sent. |
504 | We were unable to process your request. The health plan did not respond after several retry attempts. Please try your request again later. |
EXAMPLES
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v2/service-reviews/-11923818311
->
HTTP/1.1 200 OK
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
X-Global-Transaction-ID: 36774789
Connection: close
{
"id" : "-11923818311",
"createdDate" : "2014-04-28T21:59:29.000+0000",
"updatedDate" : "2014-04-29T08:28:01.000+0000",
"expirationDate" : "2014-05-14T21:59:29.000+0000",
"customerId" : "11314",
"updatable" : false,
"status" : "Certified in Total",
"statusCode" : "A1",
"certificationIssueDate" : "2014-04-29",
"certificationEffectiveDate" : "2014-05-01",
"certificationExpirationDate" : "2014-05-03",
"certificationNumber" : "129738127",
"payer" : {
"id" : "BCBSF",
"name" : "Florida Blue",
"contactName" : "Billing Dept",
"phone" : "1-800-555-4444"
},
"requestingProvider" : {
"lastName" : "Slice n Dice Discount Surgery",
"npi" : "1234567893"
},
"subscriber" : {
"memberId" : "XBH1823812"
},
"patient" : {
"lastName" : "Smith",
"firstName" : "Bob",
"birthDate" : "1956-01-29",
"subscriberRelationship" : "Self",
"subscriberRelationshipCode" : "18"
},
"diagnoses" : [{
"qualifier" : "ICD-10",
"qualifierCode" : "ABF",
"value" : "Struck by dolphin, initial encounter",
"code" : "W5602XA"
}],
"requestType" : "Admission Review",
"requestTypeCode" : "AR",
"serviceType" : "Medical Care",
"serviceTypeCode" : "1",
"placeOfService" : "Office",
"placeOfServiceCode" : "11",
"fromDate" : "2014-05-01",
"toDate" : "2014-05-03",
"quantity" : "3",
"quantityType" : "Days",
"quantityTypeCode" : "DA",
"admissionType" : "Emergency",
"admissionTypeCode" : "1",
"renderingProviders" : [{
"role" : "Attending Provider",
"roleCode" : "71",
"lastName" : "Jones",
"firstName" : "Jane",
"npi" : "1231231238"
},{
"role" : "Facility",
"roleCode" : "FA",
"lastName" : "Slice and Dice Surgery Center",
"npi" : "1234912380"
}],
"procedures" : [{
"qualifier" : "HCPCS",
"qualifierCode" : "HC",
"value" : "Low-level laser treatment, 15 minutes",
"code" : "S8948",
"quantity" : "1",
"quantityType" : "Units",
"quantityTypeCode" : "UN"
}]
}
GET /V2/SERVICE-REVIEWS
You can search the for service reviews in the health plan's system using this endpoint.
This endpoint queries the health plan's system asynchronously. To submit a transaction, make a valid request and we will respond with a location header containing a URL you can query for your result.
Parameter | Type | Description |
---|---|---|
payer.id | String | The Availity payer id of the health plan. |
requestingProvider.specialtyCode | String | The specialty code of the requesting provider. |
requestingProvider.lastName | String | The last or business name of the requesting provider. |
requestingProvider.firstName | String | The first name of the requesting provider. |
requestingProvider.middleName | String | The middle name of the requesting provider. |
requestingProvider.suffix | String | The suffix of the requesting provider. |
requestingProvider.npi | String | The NPI of the requesting provider. |
requestingProvider.taxId | String | The tax id of the requesting provider. |
requestingProvider.payerAssignedProviderId | String | The payer assigned provider id of the requesting provider. |
requestingProvider.submitterId | String | The submitter id of the requesting provider. |
requestingProvider.addressLine1 | String | Line one of the address of the requesting provider. |
requestingProvider.addressLine2 | String | Line two of the address of the requesting provider. |
requestingProvider.city | String | The city of the requesting provider. |
requestingProvider.stateCode | String | The state code of the requesting provider. |
requestingProvider.zipCode | String | The ZIP code of the requesting provider. |
requestingProvider.contactName | String | The contact name of the requesting provider. |
requestingProvider.phone | String | The phone number of the requesting provider. |
requestingProvider.extension | String | The phone extension of the requesting provider. |
requestingProvider.fax | String | The fax number of the requesting provider. |
subscriber.memberId | String | The member id of the subscriber. |
subscriber.firstName | String | The first name of the subscriber. |
subscriber.lastName | String | The last name of the subscriber. |
subscriber.middleName | String | The middle name of the subscriber. |
subscriber.suffix | String | The suffix of the subscriber. |
patient.lastName | String | The last name of the patient. |
patient.firstName | String | The first name of the patient. |
patient.middleName | String | The middle name of the patient. |
patient.suffix | String | The suffix of the patient. |
patient.birthDate | Date | The birth date of the patient. |
patient.subscriberRelationshipCode | String | The code of the patient's relationship to the subscriber. |
requestTypeCode | String | The type code of service reviews you would like to query for. |
fromDate | Date | The service from date. |
toDate | Date | The service to date. |
certificationIssueDate | Date | The date the service review certification was issued. |
certificationNumber | String | The number assigned to certified service reviews. |
referenceNumber | String | The number assigned to uncertified service reviews. |
statusCode | String | The status code of the service reviews. |
sessionId | String | Used for polling for a result. |
RESPONSE STATUSES
HTTP Status Code | Description |
---|---|
200 | We are done processing your request and the response body contains the result. |
202 | We are currently processing your request. We may be retrying it. The X-Status-Message header will contain additional detail. |
400 | Your request has been rejected. It either failed our validation rules or was rejected by the health plan. The errors property will contain detailed information. Errors that specify a field are Availity validation rule failures. Errors that specify a code are from the health plan. |
504 | We were unable to process your request. The health plan did not respond after several retry attempts. Please try your request again later. |
VALIDATION RULES
The validation rules for the ServiceReview resource can vary by health plan, the type of authorization being requested, and the type of service to be performed. Availity organizes these rules and makes them available through the Configuration resource. The Configuration resource documents the fields you need to send to create a ServiceReview and explains what values are valid for those fields. See Configurations.
EXAMPLES
If your request is invalid, we will respond with a status code of 400 and a list of errors for you to correct.
$ curl -i -X GET -i https://api.availity.com/availity/v2/service-reviews?requestTypeCode=AR&requestingProviderLastName=SLICE N DICE DISCOUNT SURGERY&requestingProviderAddressLine1=123Street&requestingProviderCity=Jacksonville&requestingProviderState=FL&requestingProviderZipCode=123451234&requestingProviderContactName=John&requestingProviderPhone=1112223333&memberId=TEST1&patientLastName=Doe&patientFirstName=John&patientBirthDate=1990-01-01&fromDate=2015-01-01
->
HTTP/1.1 400 Bad Request
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
X-Global-Transaction-ID: 36774789
Connection: close
{
"userMessage": "The request was invalid. See the 'errors' property for details.",
"developerMessage": "The request was invalid. See the 'errors' property for details.",
"documentation": "https://developer.availity.com/documentation",
"reasonCode": 0,
"statusCode": 400,
"errors": [
{
"field": "requestingProvider.npi",
"errorMessage": "Please enter a valid Requesting Provider NPI.",
"index": 0
}
}
}
If your request is valid, we will respond with a status code of 202 and a location header where you can check back for your response. We will continue to respond in this way until we have heard back from the health plan.
$ curl -i -X GET -i https://api.availity.com/availity/v2/service-reviews?requestTypeCode=AR&requestingProviderLastName=SLICE N DICE DISCOUNT SURGERY&requestingProviderAddressLine1=123Street&requestingProviderCity=Jacksonville&requestingProviderState=FL&requestingProviderZipCode=123451234&requestingProviderContactName=John&requestingProviderPhone=1112223333&memberId=TEST1&patientLastName=Doe&patientFirstName=John&patientBirthDate=1990-01-01&fromDate=2015-01-01&requestingProviderNpi=1234567893
->
HTTP/1.1 202 Accepted
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
X-Global-Transaction-ID: 36774789
Connection: close
Location: https://api.availity.com/availity/v2/service-reviews?sessionId=-1283121411
X-Status-Message: We are processing your request.
If the health plan responds with validation messages indicating that they were unable to fulfill your request, we will respond with a status code of 400 and a list of errors from the health plan.
$ curl -i -X GET -i https://api.availity.com/availity/v2/service-reviews?sessionId=-1283121411
->
HTTP/1.1 400 Bad Request
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
X-Global-Transaction-ID: 36774789
Connection: close
{
"userMessage": "The request was invalid. See the 'errors' property for details.",
"developerMessage": "The request was invalid. See the 'errors' property for details.",
"documentation": "https://developer.availity.com/documentation",
"reasonCode": 0,
"statusCode": 400,
"errors": [
{
"code": "67",
"errorMessage": "Patient Not Found - Please Correct and Resubmit"
}
}
}
If we are unable to communicate with the health plan (due to maintenance), we will respond with a status code of 504 and a message indicating that the health plan is down for maintenance.
$ curl -i -X GET -i https://api.availity.com/availity/v2/service-reviews?sessionId=-1283121411
->
HTTP/1.1 504 Gateway Timeout
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
X-Global-Transaction-ID: 36774789
Connection: close
{
"userMessage":"The health plan is down for maintenance.",
"developerMessage":"We were unable to complete a transaction with the payer.",
"documentation": "https://developer.availity.com/documentation",
"reasonCode":7,
"statusCode":504
}
Once the health plan has successfully fulfilled your inquiry request, we will respond with a status code of 200 and summaries of each service review we found.
$ curl -i -X GET -i https://api.availity.com/availity/v2/service-reviews?sessionId=-1283121411
->
HTTP/1.1 200 OK
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
X-Global-Transaction-ID: 36774789
Connection: close
{
"totalCount" : 2,
"count" : 2,
"offset" : 0,
"limit" : 50,
"links" : {
"self" : {
"href" : "https://api.availity.com/availity/v2/service-reviews?requestTypeCode=AR&requestingProviderLastName=SLICE N DICE DISCOUNT SURGERY&requestingProviderAddressLine1=123Street&requestingProviderCity=Jacksonville&requestingProviderState=FL&requestingProviderZipCode=123451234&requestingProviderContactName=John&requestingProviderPhone=1112223333&memberId=TEST1&patientLastName=Doe&patientFirstName=John&patientBirthDate=1990-01-01&fromDate=2015-01-01&requestingProviderNpi=1234567893"
}
},
"serviceReviews" : [{
"links" : {
"self" : {
"href" : "https://api.availity.com/availity/v2/service-reviews/111231"
}
},
"id" : "111231",
"status" : "Pended",
"statusCode" : "A4",
"createdDate" : "2015-01-21T17:44:46.000+0000",
"updatedDate" : "2015-01-22T17:44:52.000+0000",
"expirationDate" : "2015-02-15T17:44:46.000+0000",
"updatable" : false,
"referenceNumber" : "REF12345",
"payer" : {
"name" : "FLORIDA BLUE",
"id" : "BCBSF"
},
"requestingProvider" : {
"lastName" : "SLICE AND DICE DISCOUNT SURGERY",
"npi" : "1234567893",
},
"subscriber" : {
"firstName" : "BRUCE",
"lastName" : "WAYNE",
"memberId" : "ASDF123124",
},
"patient" : {
"firstName" : "BRUCE",
"lastName" : "WAYNE",
"subscriberRelationship" : "Self",
"subscriberRelationshipCode" : "18",
"birthDate" : "1962-08-10",
},
"requestType" : "Admission Review",
"requestTypeCode" : "AR",
"serviceType" : "Medical Care",
"serviceTypeCode" : "1",
"fromDate" : "2015-01-22",
"toDate" : "2015-01-25"
},{
"links" : {
"self" : {
"href" : "https://api.availity.com/availity/v2/service-reviews/111221"
}
},
"id" : "111221",
"status" : "Certified in Total",
"statusCode" : "A1",
"createdDate" : "2015-01-25T17:44:46.000+0000",
"updatedDate" : "2015-01-25T17:44:52.000+0000",
"expirationDate" : "2015-02-17T17:44:46.000+0000",
"updatable" : false,
"certificationNumber" : "1231723",
"payer" : {
"name" : "FLORIDA BLUE",
"id" : "BCBSF"
},
"requestingProvider" : {
"lastName" : "SLICE AND DICE DISCOUNT SURGERY",
"npi" : "1234567893",
},
"subscriber" : {
"firstName" : "FRED",
"lastName" : "FLINTSTONE",
"memberId" : "ASDF23123123"
},
"patient" : {
"firstName" : "WILMA",
"lastName" : "FLINTSTONE",
"subscriberRelationship" : "Spouse",
"subscriberRelationshipCode" : "01",
"birthDate" : "1961-01-15"
},
"requestType" : "Admission Review",
"requestTypeCode" : "AR",
"serviceType" : "Medical Care",
"serviceTypeCode" : "1",
"fromDate" : "2015-01-26",
"toDate" : "2015-01-27"
}]
}
PUT /V2/SERVICE-REVIEWS
This endpoint updates service reviews asynchronously. Only a service review with updatable=true can be updated. Once you make a valid request, we will respond with a location header containing a URL you can query for your result while we asynchronously send an updated copy of the service review to the health plan.
RESPONSE STATUSES
HTTP Status Code | Description |
---|---|
202 | We are currently processing your request. |
400 | Your request has been rejected. It either failed our validation rules (a 400 in res) See the errors property for details. |
404 | We did not find a ServiceReview with the id that you sent. |
500 | We were unable to parse your request. |
EXAMPLES
$ curl -i -H "Content-Type: application/json" -X PUT -d '{
"links" : {
"self" : {
"href" : "https://api.availity.com/availity/v2/service-reviews/-11923818311"
}
},
"id" : "-11923818311",
"payer" : {
"id" : "BCBSF",
"name" : "Florida Blue"
},
"requestingProvider" : {
"lastName" : "Slice n Dice Discount Surgery",
"npi" : "1234567893"
},
"subscriber" : {
"memberId" : "XBH1823812"
},
"patient" : {
"lastName" : "Smith",
"firstName" : "Bob",
"birthDate" : "1956-01-29",
"subscriberRelationshipCode" : "18"
},
"diagnoses" : [{
"qualifierCode" : "ABF",
"code" : "W5602XA"
}],
"requestTypeCode" : "AR",
"serviceTypeCode" : "1",
"placeOfServiceCode" : "11",
"fromDate" : "2014-05-01",
"toDate" : "2014-05-03",
"quantity" : "3",
"quantityTypeCode" : "DA",
"admissionTypeCode" : "1",
"renderingProviders" : [{
"roleCode" : "71",
"lastName" : "Jones",
"firstName" : "Jane",
"npi" : "1231231238"
},{
"roleCode" : "FA",
"lastName" : "Slice and Dice Surgery Center",
"npi" : "1234912380"
}],
"procedures" : [{
"qualifierCode" : "HC",
"code" : "S8948",
"quantity" : "1",
"quantityTypeCode" : "UN"
}]
}' https://api.availity.com/availity/v2/service-reviews
->
HTTP/1.1 202 Accepted
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
Location: https://api.availity.com/availity/v2/service-reviews/-11923818311
X-Status-Message: We are processing your request.
UPDATABILITY
The ServiceReview resource contains a flag called updatable that indicates whether or not it can be updated. Availity does not allow you to update ServiceReviews that are currently in progress (being processed in our system). Furthermore, health plans can indicate whether or not a ServiceReview is updatable and, if so, which fields can be changed. This can differ from one ServiceReview to another and can change over the life span of a ServiceReview.
In all ServiceReviews that have an updatable property of true, you will find an updatableFields collection (ServiceReview.updatableFields). The health plan determines which fields are updatable for each service review. You will find the fields they have marked as updatable in this collection.
DELETE /V2/SERVICE-REVIEWS/:ID
This endpoint voids an existing service review asynchronously. Only a service review with deleteable=true can be voided. Once you make a valid request, we will respond with a location header containing a URL you can query for your result while we asynchronously send a void request to the health plan.
RESPONSE STATUSES
HTTP Status Code | Description |
---|---|
202 | We are currently processing your request. |
400 | Your request has been rejected. |
404 | We did not find a ServiceReview with the id that you sent. |
500 | We were unable to parse your request. |
EXAMPLES
$ curl -i -H "Content-Type: application/json" -X DELETE https://api.availity.com/availity/v2/service-reviews/-11923818311
->
HTTP/1.1 202 Accepted
x-api-id: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Session-ID: a8380404-0d07-47fa-9e86-44eee35a02bb
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Thu, 26 Feb 2015 05:10:26 GMT
X-Global-Transaction-ID: 36774789
Connection: close
Location: https://api.availity.com/availity/v2/service-reviews/-11923818311
X-Status-Message: We are processing your request.
DELETABILITY
The ServiceReview resource contains a flag called deletable that indicates whether or not it can be deleted. Availity does not allow you to dlete ServiceReviews that are currently in progress (being processed in our system). Furthermore, health plans can indicate whether or not a ServiceReview is deletable. This can differ from one ServiceReview to another and can change over the life span of a ServiceReview.
Claim Statuses
This resource represents a request and response for claim status information from a health plan. Your application can use the endpoints defined for it to find, create, and manage these requests.
The Resource
Field | Type | Description |
---|---|---|
id | String | A unique identifier that Availity has assigned to this ClaimStatus. |
createdDate | TimeStamp | The date and time when this item was created in Availity's system. |
updatedDate | TimeStamp | The date and time when this item was last updated. |
expirationDate | TimeStamp | The date and time when this item will be removed from Availity's system. |
customerId | String | The id of the Availity customer that owns this ClaimStatus. Availity may ask for this during support calls. |
controlNumber | String | The id of the last transaction associated with this ClaimStatus. The health plan may ask for this during support calls. |
status | String | A description of the current status of this ClaimStatus. |
statusCode | String | A code that represents the current status. |
fromDate | Date | The from date specified in the initial claim status inquiry request. |
toDate | Date | The to date specified in the initial claim status inquiry request. |
claimNumber | String | The health plan's claim tracking number assigned when the original claim was received and processed. |
claimAmount | String | The total claim charge amount of the original claim processed by the health plan. |
facilityTypeCode | String | The code identifying where services were, or may have been, performed for institutional claims. |
facilityType | String | A description of the facility type. |
frequencyTypeCode | String | The code identifying the frequency of an institutional claim. |
frequencyType | String | A description of the frequency type. |
payer | Object | An object representing the health plan of the patient. |
payer.id | String | The Availity id of the health plan. |
payer.name | String | The name of the health plan. |
payer.contactName | String | The contact name of the health plan. |
payer.phone | String | The phone number of the health plan. |
payer.extension | String | The phone number extension of the health plan. |
payer.fax | String | The fax number of the health plan. |
payer.emailAddress | String | The email address of the health plan. |
payer.ediAccessNumber | String | The electronic data interchange access Number or the health plan. |
submitter | Object | An object representing the organization or person that is requesting/submitting the claim status. |
submitter.lastName | String | The last or business name of the submitter. |
submitter.firstName | String | The first name of the submitter. |
submitter.middleName | String | The middle name of the submitter. |
submitter.suffix | String | The suffix of the submitter. |
submitter.id | String | The identifier of the submitter. |
submitter.traceId | String | A reference id assigned by the health plan to uniquely identify the transaction. |
submitter.statusDetails | Object Array | An array of status information reported for the submitter. |
submitter.statusDetails.category | String | A description of the logical groupings of claim status codes. |
submitter.statusDetails.categoryCode | String | An identifier used to specify the logical groupings of claim status codes. |
submitter.statusDetails.status | String | A description of the status associated with a claim or service line. |
submitter.statusDetails.statusCode | String | An identifier of the status associated with a claim or service line. |
submitter.statusDetails.entity | String | A description of the entity associated with the claim status code. |
submitter.statusDetails.entityCode | String | An identifier of the entity associated with the claim status code. |
submitter.statusDetails.effectiveDate | Date | The effective date of the status information. |
providers | Object Array | An array containing information regarding the provider of services from the original claim. |
providers.lastName | String | The last or business name of the service provider. |
providers.firstName | String | The first name of the service provider. |
providers.middleName | String | The middle name of the service provider. |
providers.suffix | String | The suffix of the service provider. |
providers.npi | String | The national provider id of the service provider. |
providers.taxId | String | The tax id of the service provider. |
providers.payerAssignedProviderId | String | The health plan assigned id for the service provider. |
providers.traceId | String | A reference id assigned by the health plan to uniquely identify the transaction. |
providers.statusDetails | Object Array | An array of status information reported for the provider associated with the original claim. |
providers.statusDetails.category | String | A description of the logical groupings of claim status codes. |
providers.statusDetails.categoryCode | String | An identifier used to specify the logical groupings of claim status codes. |
providers.statusDetails.status | String | A description of the status associated with a claim or service line. |
providers.statusDetails.statusCode | String | An identifier of the status associated with a claim or service line. |
providers.statusDetails.entity | String | A description of the entity associated with the claim status code. |
providers.statusDetails.entityCode | String | An identifier of the entity associated with the claim status code. |
providers.statusDetails.effectiveDate | Date | The effective date of the status information. |
subscriber | Object | An object representing the health plan subscriber. |
subscriber.lastName | String | The last name of the subscriber. |
subscriber.firstName | String | The first name of the subscriber. |
subscriber.middleName | String | The middle name of the subscriber. |
subscriber.suffix | String | The suffix of the subscriber. |
subscriber.memberId | String | The member id of the subscriber. |
subscriber.taxId | String | The tax id of the subscriber. |
patient | Object | An object representing the patient for which the original claim was filed. |
patient.lastName | String | The last name of the patient. |
patient.firstName | String | The first name of the patient. |
patient.middleName | String | The middle name of the patient. |
patient.suffix | String | The suffix of the patient. |
patient.birthDate | Date | The birth date of the patient. |
patient.gender | String | A description of the gender of the patient. |
patient.genderCode | String | A code representing the gender of the patient. |
patient.accountNumber | String | A reference identifier for the patient assigned by the service provider. |
patient.subscriberRelationship | String | A description of the patient's relationship to the subscriber. |
patient.subscriberRelationshipCode | String | A code representing the patient's relationship to the subscriber. |
claimStatuses | Object Array | An array of claim status information returned from the health plan. |
claimStatuses.traceId | String | A reference id assigned by the health plan to uniquely identify this claim status. |
claimStatuses.claimControlNumber | String | A unique identifier of the originally submitted/processed claim assigned by the health plan. |
claimStatuses.facilityTypeCode | String | The code identifying where services were, or may have been, performed for institutional claims. |
claimStatuses.facilityType | String | A description of the facility type. |
claimStatuses.frequencyTypeCode | String | The code identifying the frequency of an institutional claim. |
claimStatuses.frequencyType | String | A description of the frequency type. |
claimStatuses.patientControlNumber | String | A reference identifier for the patient assigned by the service provider that was included on the original claim. |
claimStatuses.pharmacyPrescriptionNumber | String | The pharmacy prescription number from the original claim. |
claimStatuses.voucherNumber | String | The voucher number returned from the health plan. |
claimStatuses.claimIdentificationNumber | String | An identifier of the originally submitted claim assigned by a clearinghouse or intermediary. |
claimStatuses.fromDate | Date | The date on which the service began. |
claimStatuses.toDate | Date | The date on which the service ended. |
claimStatuses.statusDetails | Object Array | An array of status information reported for the original claim. |
claimStatuses.statusDetails.category | String | A description of the logical groupings of claim status codes. |
claimStatuses.statusDetails.categoryCode | String | An identifier used to specify the logical groupings of claim status codes. |
claimStatuses.statusDetails.status | String | A description of the status associated with a claim or service line. |
claimStatuses.statusDetails.statusCode | String | An identifier of the status associated with a claim or service line. |
claimStatuses.statusDetails.entity | String | A description of the entity associated with the claim status code. |
claimStatuses.statusDetails.entityCode | String | An identifier of the entity associated with the claim status code. |
claimStatuses.statusDetails.effectiveDate | Date | The effective date of the status information. |
claimStatuses.statusDetails.claimAmount | String | The amount of the originally submitted claim charges. |
claimStatuses.statusDetails.claimAmountUnits | String | The units of the claim amount. (USD) |
claimStatuses.statusDetails.paymentAmount | String | The amount payed by the health plan on the originally submitted claim. |
claimStatuses.statusDetails.paymentAmountUnits | String | The units of claim payment amount. (USD) |
claimStatuses.statusDetails.finalizedDate | Date | The date the original claim was paid. |
claimStatuses.statusDetails.remittanceDate | Date | The date the payment check was issued. |
claimStatuses.statusDetails.checkNumber | String | The number of the check that paid the claim paid amount. |
claimStatuses.serviceLines | Object Array | An array of service line information from the originally submitted/processed claim. |
claimStatuses.serviceLines.procedureQualifier | String | A description of the type or source of the procedure code. |
claimStatuses.serviceLines.procedureQualifierCode | String | A code that identifies the type or source of the procedure code. |
claimStatuses.serviceLines.procedure | String | A description of the procedure performed from the originally submitted claim. |
claimStatuses.serviceLines.procedureCode | String | A code respresenting the procedure performed from the originally submitted claim. |
claimStatuses.serviceLines.modifier1 | String | A description of the first modifier applied to this procedure. |
claimStatuses.serviceLines.modifier1Code | String | A code representing the first modifier applied to this procedure. |
claimStatuses.serviceLines.modifier2 | String | A description of the second modifier applied to this procedure. |
claimStatuses.serviceLines.modifier2Code | String | A code representing the second modifier applied to this procedure. |
claimStatuses.serviceLines.modifier3 | String | A description of the third modifier applied to this procedure. |
claimStatuses.serviceLines.modifier3Code | String | A code representing the third modifier applied to this procedure. |
claimStatuses.serviceLines.modifier4 | String | A description of the fourth modifier applied to this procedure. |
claimStatuses.serviceLines.modifier4Code | String | A code representing the fourth modifier applied to this procedure. |
claimStatuses.serviceLines.chargeAmount | String | The amount of the originally submitted charges for the service. |
claimStatuses.serviceLines.chargeAmountUnits | String | The units of the service line charge amount. (USD) |
claimStatuses.serviceLines.paymentAmount | String | The amount payed by the health plan for the servcie. |
claimStatuses.serviceLines.paymentAmountUnits | String | The units of the service payment amount. (USD) |
claimStatuses.serviceLines.service | String | A description of the product or service performed reported in this service line. |
claimStatuses.serviceLines.serviceCode | String | An identifier of the product or service performed reported in this service line. |
claimStatuses.serviceLines.quantity | String | The originally submitted units of service. |
claimStatuses.serviceLines.controlNumber | String | A reference identifier for the service assigned by the health plan. |
claimStatuses.serviceLines.fromDate | Date | The date on which the service began. |
claimStatuses.serviceLines.toDate | Date | The date on which the service ended. |
claimStatuses.serviceLines.statusDetails | Object Array | An array of status information reported for the service line of the original claim. |
claimStatuses.serviceLines.statusDetails.category | String | A description of the logical groupings of claim status codes. |
claimStatuses.serviceLines.statusDetails.categoryCode | String | An identifier used to specify the logical groupings of claim status codes. |
claimStatuses.serviceLines.statusDetails.status | String | A description of the status associated with a claim or service line. |
claimStatuses.serviceLines.statusDetails.statusCode | String | An identifier of the status associated with a claim or service line. |
claimStatuses.serviceLines.statusDetails.entity | String | A description of the entity associated with the claim status code. |
claimStatuses.serviceLines.statusDetails.entityCode | String | An identifier of the entity associated with the claim status code. |
claimStatuses.serviceLines.statusDetails.effectiveDate | Date | The effective date of the status information. |
claimCount | String | The total number of unique claims reported by this claim status inquiry. |
Statuses
ClaimStatus.statusCode | ClaimStatus.status | Description |
---|---|---|
0 | In Progress | Availity is communicating with the health plan. Check back in a few seconds. |
19 | Request Error | The health plan indicated that something is wrong with the request. The resource will have a list of validationMessages. Correct and update the resource. |
R1 | Communication Error, Retrying | The health plan did not respond. Availity will retry the request over the next 30 minutes. |
7 | Communication Error, Retries Exhausted | The health plan did not respond after multiple retries. Please resubmit the request later. |
3 | Complete (Invalid Response) | Availity has received a response from the health plan but it contained errors that may or may not affect the data returned in the asset. |
4 | Complete | Availity has received a response from the health plan and it is now available for viewing. |
GET /V1/CLAIM-STATUSES
You can search the collection of claim statuses using this endpoint.
Parameter | Type | Description |
---|---|---|
payer.id | String | The Availity id for the health plan. |
submitter.lastName | String | The last or business name of the submitter. |
submitter.firstName | String | The first name of the submitter. |
submitter.middleName | String | The middle name of the submitter. |
submitter.suffix | String | The suffix of the submitter. |
submitter.id | String | The identifier of the submitter. |
providers.lastName | String | The last or business name of the service provider. |
providers.firstName | String | The first name of the service provider. |
providers.middleName | String | The middle name of the service provider. |
providers.suffix | String | The suffix of the service provider. |
providers.npi | String | The national provider id of the service provider. |
providers.taxId | String | The tax id of the service provider. |
providers.payerAssignedProviderId | String | The health plan assigned id for the service provider. |
subscriber.memberId | String | The member id of the subscriber. |
subscriber.lastName | String | The last name of the subscriber. |
subscriber.firstName | String | The first name of the subscriber. |
subscriber.middleName | String | The middle name of the subscriber. |
subscriber.suffix | String | The suffix of the subscriber. |
patient.lastName | String | The last name of the patient. |
patient.firstName | String | The first name of the patient. |
patient.middleName | String | The middle name of the patient. |
patient.suffix | String | The suffix of the patient. |
patient.birthDate | Date | The birth date of the patient. |
patient.genderCode | String | A code representing the gender of the patient. |
patient.accountNumber | String | A reference identifier for the patient assigned by the service provider. |
patient.subscriberRelationshipCode | String | A code representing the patient's relationship to the subscriber. |
fromDate | Date | The service from date. |
toDate | Date | The service to date. |
claimNumber | String | The health plan's claim tracking number assigned when the original claim was received and processed. |
claimAmount | String | The total claim charge amount of the original claim processed by the health plan. |
facilityTypeCode | String | The code identifying where services were, or may have been, performed for institutional claims. |
frequencyTypeCode | String | The code identifying the frequency of an institutional claim. |
q | String | Fuzzy search parameter - triggers us to search our database instead of reaching out to the health plan. |
sortBy | String | Field we will sort by when returning results from our database. Currently only supports - updatedDate. |
sortDirection | String | The direction we will sort results from our database. Supports asc and desc. Defaults to desc. |
id | String | Allows you to retrive summaries of multiple claim statuses by specifying the id of each. |
The endpoint returns summary versions of the claim status resource. Here is an example with all possible fields shown:
{
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses/-1437397854912689422"
}
},
"id": "-1437397854912689422",
"customerId": "1194",
"userId": "aka71627884343",
"status": "Complete",
"statusCode": "0",
"createdDate": "2015-06-05T17:47:23.000+0000",
"updatedDate": "2015-06-05T17:47:23.000+0000",
"expirationDate": "2015-06-06T17:47:23.000+0000",
"fromDate": "2015-05-15T04:00:00.000+0000",
"toDate": "2015-05-19T04:00:00.000+0000",
"claimNumber": "CL4IM2TATUSNUM8ER",
"claimAmount": "12345678.90",
"facilityTypeCode": "12",
"facilityType": "Hospital Inpatient, Part B only",
"frequencyTypeCode": "1",
"frequencyType": "Admit thru Discharge Claim",
"claimCount": "1"
"payer": {
"id": "BCBSF",
"name" : "FLORIDA BLUE"
},
"submitter": {
"lastName": "SUBMITTERLASTNAME",
"firstName": "SUBMITTERFIRSTNAME",
"middleName": "SUBMITTERMIDDLENAME",
"suffix": "SUBMITTERSUFFIX",
"id": "SUBMITTERID"
},
"providers": [
{
"lastName": "PROVIDERLASTNAME",
"firstName": "PROVIDERFIRSTNAME",
"middleName": "PROVIDERMIDDLENAME",
"suffix": "PROVIDERSUFFIX",
"npi": "1234567893"
"taxId": "1234567893"
"payerAssignedProviderId": "1234567893"
}
],
"subscriber": {
"firstName": "SUBSCRIBERFIRSTNAME",
"lastName": "SUBSCRIBERLASTNAME",
"middleName": "SUBSCRIBERMIDDLENAME",
"suffix": "SUBSCRIBERSUFFIX",
"memberId": "ABC123456789"
},
"patient": {
"firstName": "PATIENTFIRSTNAME",
"lastName": "PATIENTLASTNAME",
"middleName": "PATIENTMIDDLENAME",
"suffix": "PATIENTSUFFIX",
"birthDate": "1999-09-09",
"gender": "Male",
"genderCode": "M",
"accountNumber": "PAT1ENTACC0UNTNUMB3R",
"subscriberRelationship": "Spouse",
"subscriberRelationshipCode": "01"
}
}
Multi-summary Mode
The first way to interact with the endpoint is called multi-summary mode. It allows you to retrieve summary versions and check the status of multiple claim statuses at once. You can initiate it by specifying one or more id parameters where each id is the id of a claim status you are interested in. Any other parameters will be ignored. You can get up to 50 claim status summaries at a time using this feature. Here is an example of getting two summaries by id:
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/claim-statuses?id=-6444806312330895858&id=-1437397854912689422
->
HTTP/1.1 200 OK
Cache-Control: private,no-store,max-age=0,must-revalidate
Connection: close
Content-Type: application/json
Date: Tue, 09 Jun 2015 19:54:52 GMT
X-Global-Transaction-ID: 113993145
X-Session-ID: 84f311c9-7aca-45fe-b256-d6049c499d66
x-api-id: 84f311c9-7aca-45fe-b256-d6049c499d66
X-Api-Mock-Response: true
{
"totalCount": 2,
"count": 2,
"offset": 0,
"limit": 50,
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses?id=-6444806312330895858&id=-1437397854912689422"
}
},
"claimStatuses": [
{
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses/-6444806312330895858"
}
},
"id": "-6444806312330895858",
"customerId": "1194",
"controlNumber": "36374",
"userId": "aka71627884343",
"status": "Complete",
"statusCode": "4",
"createdDate": "2015-06-05T17:50:30.000+0000",
"updatedDate": "2015-06-05T17:50:30.000+0000",
"expirationDate": "2015-06-06T17:50:30.000+0000",
"fromDate": "2015-05-15T04:00:00.000+0000",
"toDate": "2015-05-19T04:00:00.000+0000",
"claimNumber": "CL4IM2TATUSNUM8ER",
"claimAmount": "12345678.90",
"facilityTypeCode": "12",
"facilityType": "Hospital Inpatient, Part B only",
"frequencyTypeCode": "1",
"frequencyType": "Admit thru Discharge Claim",
"payer": {
"id": "BCBSF"
},
"submitter": {
"lastName": "SUBMITTERLASTNAME",
"firstName": "SUBMITTERFIRSTNAME",
"id": "SUBMITTERID"
},
"providers": [
{
"lastName": "PROVIDERLASTNAME",
"firstName": "PROVIDERFIRSTNAME",
"npi": "1234567893"
}
],
"subscriber": {
"firstName": "TEST",
"middleName": "B",
"lastName": "PATIENT",
"suffix": "III",
"memberId": "BEAH276TESTGEN"
},
"patient": {
"firstName": "TEST",
"middleName": "B",
"lastName": "PATIENT",
"suffix": "III",
"birthDate": "1999-09-09",
"gender": "Male",
"genderCode": "M",
"accountNumber": "UNKNOWN",
"subscriberRelationship": "Self",
"subscriberRelationshipCode": "18"
},
"claimCount": "1"
},
{
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses/-1437397854912689422"
}
},
"id": "-1437397854912689422",
"customerId": "1194",
"controlNumber": "36373",
"userId": "aka71627884343",
"status": "Complete (Invalid Response)",
"statusCode": "3",
"createdDate": "2015-06-05T17:47:23.000+0000",
"updatedDate": "2015-06-05T17:47:23.000+0000",
"expirationDate": "2015-06-06T17:47:23.000+0000",
"fromDate": "2015-05-15T04:00:00.000+0000",
"toDate": "2015-05-19T04:00:00.000+0000",
"claimNumber": "CL4IM2TATUSNUM8ER",
"claimAmount": "12345678.90",
"facilityTypeCode": "12",
"facilityType": "Hospital Inpatient, Part B only",
"frequencyTypeCode": "1",
"frequencyType": "Admit thru Discharge Claim",
"payer": {
"id": "BCBSF"
},
"submitter": {
"lastName": "SUBMITTERLASTNAME",
"firstName": "SUBMITTERFIRSTNAME",
"id": "SUBMITTERID"
},
"providers": [
{
"lastName": "PROVIDERLASTNAME",
"firstName": "PROVIDERFIRSTNAME",
"npi": "1234567893"
}
],
"subscriber": {
"firstName": "SUBSCRIBERFIRSTNAME",
"lastName": "SUBSCRIBERLASTNAME",
"memberId": "ABC123456789"
},
"patient": {
"firstName": "PATIENTFIRSTNAME",
"lastName": "PATIENTLASTNAME",
"birthDate": "1999-09-09",
"gender": "Male",
"genderCode": "M",
"accountNumber": "PAT1ENTACC0UNTNUMB3R",
"subscriberRelationship": "Unknown",
"subscriberRelationshipCode": "21"
},
"claimCount": "1"
}
}]
}
Search Mode
The second way to interact with the endpoint is called search mode. It allows you to search the claim statuses that are in Availity's database. This mode is useful for building searchable list views of claim statuses. You initiate it by sending a q parameter (even a blank one). We will use this parameter to perform a fuzzy search in our database. In addition, you can perform case insensitive filtering by sending any of the other parameters (except id). Furthermore, this mode supports sorting and paging. Here is an example:
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/claim-statuses?q=&providers.npi=1234567893
->
HTTP/1.1 200 OK
Cache-Control: private,no-store,max-age=0,must-revalidate
Connection: close
Content-Type: application/json
Date: Tue, 09 Jun 2015 19:54:52 GMT
X-Global-Transaction-ID: 113993145
X-Session-ID: 84f311c9-7aca-45fe-b256-d6049c499d66
x-api-id: 84f311c9-7aca-45fe-b256-d6049c499d66
X-Api-Mock-Response: true
{
"totalCount": 5,
"count": 5,
"offset": 0,
"limit": 50,
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses?q=&providers.npi=1234567893"
}
},
"claimStatuses": [
{
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses/-6444806312330895858"
}
},
"id": "-6444806312330895858",
"customerId": "1194",
"controlNumber": "36374",
"userId": "aka71627884343",
"status": "Complete",
"statusCode": "4",
"createdDate": "2015-06-05T17:50:30.000+0000",
"updatedDate": "2015-06-05T17:50:30.000+0000",
"expirationDate": "2015-06-06T17:50:30.000+0000",
"fromDate": "2015-05-15T04:00:00.000+0000",
"toDate": "2015-05-19T04:00:00.000+0000",
"claimNumber": "CL4IM2TATUSNUM8ER",
"claimAmount": "12345678.90",
"facilityTypeCode": "12",
"facilityType": "Hospital Inpatient, Part B only",
"frequencyTypeCode": "1",
"frequencyType": "Admit thru Discharge Claim",
"payer": {
"id": "BCBSF"
},
"submitter": {
"lastName": "SUBMITTERLASTNAME",
"firstName": "SUBMITTERFIRSTNAME",
"id": "SUBMITTERID"
},
"providers": [
{
"lastName": "PROVIDERLASTNAME",
"firstName": "PROVIDERFIRSTNAME",
"npi": "1234567893"
}
],
"subscriber": {
"firstName": "SUBSCRIBERFIRSTNAME",
"middleName": "SUBSCRIBERMIDDLENAME",
"lastName": "SUBSCRIBERLASTNAME",
"suffix": "III",
"memberId": "BEAH276TESTGEN"
},
"patient": {
"firstName": "PATIENTFIRSTNAME",
"middleName": "PATIENTMIDDLENAME",
"lastName": "PATIENTLASTNAME",
"suffix": "III",
"birthDate": "1999-09-09",
"gender": "Male",
"genderCode": "M",
"accountNumber": "UNKNOWN",
"subscriberRelationship": "Self",
"subscriberRelationshipCode": "18"
},
"claimCount": "1"
},
{
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses/-1437397854912689422"
}
},
"id": "-1437397854912689422",
"customerId": "1194",
"controlNumber": "36373",
"userId": "aka71627884343",
"status": "Complete (Invalid Response)",
"statusCode": "3",
"createdDate": "2015-06-05T17:47:23.000+0000",
"updatedDate": "2015-06-05T17:47:23.000+0000",
"expirationDate": "2015-06-06T17:47:23.000+0000",
"fromDate": "2015-05-15T04:00:00.000+0000",
"toDate": "2015-05-19T04:00:00.000+0000",
"claimNumber": "CL4IM2TATUSNUM8ER",
"claimAmount": "12345678.90",
"facilityTypeCode": "12",
"facilityType": "Hospital Inpatient, Part B only",
"frequencyTypeCode": "1",
"frequencyType": "Admit thru Discharge Claim",
"payer": {
"id": "BCBSF"
},
"submitter": {
"lastName": "SUBMITTERLASTNAME",
"firstName": "SUBMITTERFIRSTNAME",
"id": "SUBMITTERID"
},
"providers": [
{
"lastName": "PROVIDERLASTNAME",
"firstName": "PROVIDERFIRSTNAME",
"npi": "1234567893"
}
],
"subscriber": {
"firstName": "SUBSCRIBERFIRSTNAME",
"lastName": "SUBSCRIBERLASTNAME",
"memberId": "ABC123456789"
},
"patient": {
"firstName": "PATIENTFIRSTNAME",
"lastName": "PATIENTLASTNAME",
"birthDate": "1999-09-09",
"gender": "Male",
"genderCode": "M",
"accountNumber": "PAT1ENTACC0UNTNUMB3R",
"subscriberRelationship": "Unknown",
"subscriberRelationshipCode": "21"
},
"claimCount": "1"
},
{
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses/8093209937431557081"
}
},
"id": "8093209937431557081",
"customerId": "1194",
"controlNumber": "36358",
"userId": "aka71627884343",
"status": "Complete",
"statusCode": "4",
"createdDate": "2015-06-05T15:52:42.000+0000",
"updatedDate": "2015-06-05T15:52:42.000+0000",
"expirationDate": "2015-06-06T15:52:42.000+0000",
"fromDate": "2015-05-16T04:00:00.000+0000",
"toDate": "2015-06-01T04:00:00.000+0000",
"claimNumber": "CL4IM2TATUSNUM8ER",
"claimAmount": "12345678.90",
"facilityTypeCode": "12",
"facilityType": "Hospital Inpatient, Part B only",
"frequencyTypeCode": "1",
"frequencyType": "Admit thru Discharge Claim",
"payer": {
"id": "BCBSF"
},
"submitter": {
"lastName": "SUBMITTERLASTNAME",
"firstName": "SUBMITTERFIRSTNAME",
"id": "SUBMITTERID"
},
"providers": [
{
"lastName": "PROVIDERLASTNAME",
"firstName": "PROVIDERFIRSTNAME",
"npi": "1234567893"
}
],
"subscriber": {
"firstName": "SUBSCRIBERFIRSTNAME",
"middleName": "SUBSCRIBERMIDDLENAME",
"lastName": "SUBSCRIBERLASTNAME",
"suffix": "SR",
"memberId": "CSI276MAXSUBPAT"
},
"patient": {
"firstName": "PATIENTFIRSTNAME",
"middleName": "PATIENTMIDDLENAME",
"lastName": "PATIENTLASTNAME",
"suffix": "SR",
"birthDate": "1988-08-08",
"gender": "Female",
"genderCode": "F",
"accountNumber": "277PATIENTACCTNUM-NOCLAIMNUM123",
"subscriberRelationship": "Unknown",
"subscriberRelationshipCode": "21"
},
"claimCount": "2"
},
{
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses/3537415793032824843"
}
},
"id": "3537415793032824843",
"customerId": "1194",
"controlNumber": "36371",
"userId": "aka71627884343",
"status": "Complete",
"statusCode": "4",
"createdDate": "2015-06-04T21:00:50.000+0000",
"updatedDate": "2015-06-04T21:00:50.000+0000",
"expirationDate": "2015-06-05T21:00:50.000+0000",
"fromDate": "2015-05-15T04:00:00.000+0000",
"toDate": "2015-05-19T04:00:00.000+0000",
"claimNumber": "CL4IM2TATUSNUM8ER",
"claimAmount": "8879999.99",
"payer": {
"id": "BCBSF"
},
"submitter": {
"lastName": "SUBMITTERLASTNAME",
"firstName": "SUBMITTERFIRSTNAME",
"id": "SUBMITTER1D"
},
"providers": [
{
"lastName": "PROVIDERLASTNAME",
"firstName": "PROVIDERFIRSTNAME",
"npi": "1234567893"
}
],
"subscriber": {
"firstName": "SUBSCRIBERFIRSTNAME",
"middleName": "SUBSCRIBERMIDDLENAME",
"lastName": "SUBSCRIBERLASTNAME",
"suffix": "SR",
"memberId": "CSI276MAXSUBPAT"
},
"patient": {
"firstName": "PATIENTFIRSTNAME",
"middleName": "PATIENTMIDDLENAME",
"lastName": "PATIENT LASTNAME",
"suffix": "SR",
"birthDate": "1912-11-10",
"gender": "Female",
"genderCode": "F",
"accountNumber": "277PATIENTACCTNUM-NOCLAIMNUM123",
"subscriberRelationship": "Unknown",
"subscriberRelationshipCode": "21"
},
"claimCount": "2"
},
{
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses/-9022098185210411357"
}
},
"id": "-9022098185210411357",
"customerId": "1194",
"controlNumber": "36370",
"userId": "aka71627884343",
"status": "Complete",
"statusCode": "4",
"createdDate": "2015-06-04T20:47:41.000+0000",
"updatedDate": "2015-06-04T20:47:41.000+0000",
"expirationDate": "2015-06-05T20:47:41.000+0000",
"fromDate": "2015-05-15T04:00:00.000+0000",
"toDate": "2015-05-19T04:00:00.000+0000",
"claimNumber": "CL4IM2TATUSNUM8ER",
"claimAmount": "8879999.99",
"payer": {
"id": "BCBSF"
},
"submitter": {
"lastName": "SUBMITTERLASTNAME",
"firstName": "SUBMITTERFIRSTNAME",
"id": "SUBMITTER1D"
},
"providers": [
{
"lastName": "PROVIDERLASTNAME",
"firstName": "PROVIDERFIRSTNAME",
"npi": "1234567893"
}
],
"subscriber": {
"firstName": "SUBSCRIBERFIRSTNAME",
"lastName": "SUBSCRIBERLASTNAME",
"memberId": "CSI276SUBPATTEST"
},
"patient": {
"lastName": "PATIENTLASTNAME",
"birthDate": "1911-09-11",
"gender": "Male",
"genderCode": "M",
"accountNumber": "277PATIENTACCTNUM-NOCLAIMNUM123",
"subscriberRelationship": "Unknown",
"subscriberRelationshipCode": "21"
},
"claimCount": "2"
}
]
}
Inquiry Mode
The third way to interact with the endpoint is called inquiry mode. It allows you to search the health plan's system for claim status information. It functions in an asynchronous manner. We will return a 202 status code and location header while we process the request. Once we hear back from the health plan, we will insert any new claim statuses into our database. This mode enforces request validation that can vary by health plan. You can find detailed information about the rules by querying our configurations endpoint with a type of claim-statuses-inquiry. In general, you can send as many parameters as you want; Availity will ignore ones that are not supported by the specified health plan.
If your request is invalid, we will respond with a status code of 400 and a list of errors for you to correct.
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/claim-statuses?payer.id=BCBSF&submitter.lastName=SUBMITTERLASTNAME&submitter.firstName=SUBMITTERFIRSTNAME&submitter.id=SUBMITTERID&providers.lastName=PROVIDERLASTNAME&providers.firstName=PROVIDERFIRSTNAME&providers.npi=7654321&subscriber.memberId=ABC123456789&subscriber.lastName=SUBSCRIBERLASTNAME&subscriber.firstName=SUBSCRIBERFIRSTNAME&patient.lastName=PATIENTLASTNAME&patient.firstName=PATIENTFIRSTNAME&patient.birthDate=1999-09-09&patient.genderCode=M&patient.accountNumber=PAT1ENTACC0UNTNUMB3R&patient.subscriberRelationshipCode=01&fromDate=2015-05-15&toDate=2015-05-19&claimNumber=CL4IM2TATUSNUM8ER&claimAmount=12345678.90&facilityTypeCode=12&frequencyTypeCode=1
->
HTTP/1.1 400 Bad Request
Cache-Control: private,no-store,max-age=0,must-revalidate
Connection: close
Content-Type: application/json
Date: Tue, 09 Jun 2015 19:54:52 GMT
X-Global-Transaction-ID: 113993145
X-Session-ID: 84f311c9-7aca-45fe-b256-d6049c499d66
x-api-id: 84f311c9-7aca-45fe-b256-d6049c499d66
X-Api-Mock-Response: true
{
"userMessage": "The request was invalid. See the 'errors' property for details.",
"developerMessage": "The request was invalid. See the 'errors' property for details.",
"documentation": "https://developer.availity.com/documentation",
"reasonCode": 0,
"statusCode": 400,
"errors": [
{
"field": "providers.npi",
"errorMessage": "Enter a valid Requesting Provider National Provider Identifier (NPI) containing 10 numeric digits and beginning with a 1, 2, 3, or 4.",
"index": 0
}
}
}
If your request is valid, we will respond with a status code of 202 and a location header where you can check back for your response. We will continue to respond in this way until we have heard back from the health plan.
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/claim-statuses?payer.id=BCBSF&submitter.lastName=SUBMITTERLASTNAME&submitter.firstName=SUBMITTERFIRSTNAME&submitter.id=SUBMITTERID&providers.lastName=PROVIDERLASTNAME&providers.firstName=PROVIDERFIRSTNAME&providers.npi=1234567893&subscriber.memberId=ABC123456789&subscriber.lastName=SUBSCRIBERLASTNAME&subscriber.firstName=SUBSCRIBERFIRSTNAME&patient.lastName=PATIENTLASTNAME&patient.firstName=PATIENTFIRSTNAME&patient.birthDate=1999-09-09&patient.genderCode=M&patient.accountNumber=PAT1ENTACC0UNTNUMB3R&patient.subscriberRelationshipCode=01&fromDate=2015-05-15&toDate=2015-05-19&claimNumber=CL4IM2TATUSNUM8ER&claimAmount=12345678.90&facilityTypeCode=12&frequencyTypeCode=1
->
HTTP/1.1 202 Accepted
Cache-Control: private,no-store,max-age=0,must-revalidate
Connection: close
Content-Type: application/json
Date: Tue, 09 Jun 2015 19:54:52 GMT
X-Global-Transaction-ID: 113993145
X-Session-ID: 84f311c9-7aca-45fe-b256-d6049c499d66
x-api-id: 84f311c9-7aca-45fe-b256-d6049c499d66
X-Api-Mock-Response: true
Location: https://api.availity.com/demo/v1/claim-statuses?
X-Status-Message: We are processing your request.
{
"totalCount": 0,
"count": 0,
"offset": 0,
"limit": 50,
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses?
}
},
"claimStatuses": []
}
If the health plan responds with validation messages indicating that they were unable to fulfill your request, we will respond with a status code of 400 and a list of errors from the health plan.
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/claim-statuses?payer.id=BCBSF&submitter.lastName=SUBMITTERLASTNAME&submitter.firstName=SUBMITTERFIRSTNAME&submitter.id=SUBMITTERID&providers.lastName=PROVIDERLASTNAME&providers.firstName=PROVIDERFIRSTNAME&providers.npi=1234567893&subscriber.memberId=ABC123456789&subscriber.lastName=SUBSCRIBERLASTNAME&subscriber.firstName=SUBSCRIBERFIRSTNAME&patient.lastName=PATIENTLASTNAME&patient.firstName=PATIENTFIRSTNAME&patient.birthDate=1999-09-09&patient.genderCode=M&patient.accountNumber=PAT1ENTACC0UNTNUMB3R&patient.subscriberRelationshipCode=01&fromDate=2012-12-01&toDate=2012-12-01&claimNumber=CL4IM2TATUSNUM8ER&claimAmount=12345678.90&facilityTypeCode=12&frequencyTypeCode=1
->
HTTP/1.1 400 Bad Request
Cache-Control: private,no-store,max-age=0,must-revalidate
Connection: close
Content-Type: application/json
Date: Tue, 09 Jun 2015 19:54:52 GMT
X-Global-Transaction-ID: 113993145
X-Session-ID: 84f311c9-7aca-45fe-b256-d6049c499d66
x-api-id: 84f311c9-7aca-45fe-b256-d6049c499d66
X-Api-Mock-Response: true
{
"userMessage": "The request was invalid. See the 'errors' property for details.",
"developerMessage": "The request was invalid. See the 'errors' property for details.",
"documentation": "https://developer.availity.com/documentation",
"reasonCode": 0,
"statusCode": 400,
"errors": [
{
"code": "E1:90",
"errorMessage": "Response not possible System Status - Entity not eligible for medical benefits for submitted dates of service"
},
{
"code": "A4:35",
"errorMessage": "Acknowledgement/Not Found The Claim/Encounter cannot be found in the adjudication system - Claim/Encounter not found"
},
{
"code": "A4:187",
"errorMessage": "Acknowledgement/Not Found The Claim/Encounter cannot be found in the adjudication system - Date(s) of service"
}]
}
If we are unable to communicate with the health plan (due to maintenance), we will respond with a status code of 504 and a message indicating that the health plan is down for maintenance.
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/claim-statuses?payer.id=BCBSF&submitter.lastName=SUBMITTERLASTNAME&submitter.firstName=SUBMITTERFIRSTNAME&submitter.id=SUBMITTERID&providers.lastName=PROVIDERLASTNAME&providers.firstName=PROVIDERFIRSTNAME&providers.npi=1234567893&subscriber.memberId=ABC123456789&subscriber.lastName=SUBSCRIBERLASTNAME&subscriber.firstName=SUBSCRIBERFIRSTNAME&patient.lastName=PATIENTLASTNAME&patient.firstName=PATIENTFIRSTNAME&patient.birthDate=1999-09-09&patient.genderCode=M&patient.accountNumber=PAT1ENTACC0UNTNUMB3R&patient.subscriberRelationshipCode=01&fromDate=2015-05-15&toDate=2015-05-19&claimNumber=CL4IM2TATUSNUM8ER&claimAmount=12345678.90&facilityTypeCode=12&frequencyTypeCode=1
->
HTTP/1.1 504 Gateway Timeout
Cache-Control: private,no-store,max-age=0,must-revalidate
Connection: close
Content-Type: application/json
Date: Tue, 09 Jun 2015 19:54:52 GMT
X-Global-Transaction-ID: 113993145
X-Session-ID: 84f311c9-7aca-45fe-b256-d6049c499d66
x-api-id: 84f311c9-7aca-45fe-b256-d6049c499d66
X-Api-Mock-Response: true
{
"userMessage":"The health plan is down for maintenance.",
"developerMessage":"We were unable to complete a transaction with the payer.",
"documentation": "https://developer.availity.com/documentation",
"reasonCode":7,
"statusCode":504
}
Once the health plan has successfully fulfilled your request, we will respond with a status code of 200 and summaries of each claim status we found.
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/claim-statuses?payer.id=BCBSF&submitter.lastName=SUBMITTERLASTNAME&submitter.firstName=SUBMITTERFIRSTNAME&submitter.id=SUBMITTERID&providers.lastName=PROVIDERLASTNAME&providers.firstName=PROVIDERFIRSTNAME&providers.npi=1234567893&subscriber.memberId=ABC123456789&subscriber.lastName=SUBSCRIBERLASTNAME&subscriber.firstName=SUBSCRIBERFIRSTNAME&patient.lastName=PATIENTLASTNAME&patient.firstName=PATIENTFIRSTNAME&patient.birthDate=1999-09-09&patient.genderCode=M&patient.accountNumber=PAT1ENTACC0UNTNUMB3R&patient.subscriberRelationshipCode=01&fromDate=2015-05-15&toDate=2015-05-19&claimNumber=CL4IM2TATUSNUM8ER&claimAmount=12345678.90&facilityTypeCode=12&frequencyTypeCode=1
->
HTTP/1.1 200 OK
Cache-Control: private,no-store,max-age=0,must-revalidate
Connection: close
Content-Type: application/json
Date: Tue, 09 Jun 2015 19:54:52 GMT
X-Global-Transaction-ID: 113993145
X-Session-ID: 84f311c9-7aca-45fe-b256-d6049c499d66
x-api-id: 84f311c9-7aca-45fe-b256-d6049c499d66
X-Api-Mock-Response: true
{
"totalCount": 1,
"count": 1,
"offset": 0,
"limit": 1,
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses?id=-1437397854912689422
}
},
"claimStatuses": [
{
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses/-1437397854912689422"
}
},
"id": "-1437397854912689422",
"customerId": "1194",
"userId": "aka71627884343",
"status": "In Progress",
"statusCode": "0",
"createdDate": "2015-06-05T17:47:23.000+0000",
"updatedDate": "2015-06-05T17:47:23.000+0000",
"expirationDate": "2015-06-06T17:47:23.000+0000",
"fromDate": "2015-05-15T04:00:00.000+0000",
"toDate": "2015-05-19T04:00:00.000+0000",
"claimNumber": "CL4IM2TATUSNUM8ER",
"claimAmount": "12345678.90",
"facilityTypeCode": "12",
"facilityType": "Hospital Inpatient, Part B only",
"frequencyTypeCode": "1",
"frequencyType": "Admit thru Discharge Claim",
"payer": {
"id": "BCBSF"
},
"submitter": {
"lastName": "SUBMITTERLASTNAME",
"firstName": "SUBMITTERFIRSTNAME",
"id": "SUBMITTERID"
},
"providers": [
{
"lastName": "PROVIDERLASTNAME",
"firstName": "PROVIDERFIRSTNAME",
"npi": "1234567893"
}
],
"subscriber": {
"firstName": "SUBSCRIBERFIRSTNAME",
"lastName": "SUBSCRIBERLASTNAME",
"memberId": "ABC123456789"
},
"patient": {
"firstName": "PATIENTFIRSTNAME",
"lastName": "PATIENTLASTNAME",
"birthDate": "1999-09-09",
"gender": "Male",
"genderCode": "M",
"accountNumber": "PAT1ENTACC0UNTNUMB3R",
"subscriberRelationship": "Spouse",
"subscriberRelationshipCode": "01"
}
}
]
}
GET /V1/CLAIM-STATUSES/:ID
You can retrieve a claim status using this endpoint.
Example
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/claim-statuses/5334032768852043884
->
HTTP/1.1 200 OK
x-api-id: 98b6e65a-4d97-47f7-b9dc-2addb6544895
X-Session-ID: 98b6e65a-4d97-47f7-b9dc-2addb6544895
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Tue, 9 Jun 2015 09:30:37 GMT
X-Global-Transaction-ID: 37112879
Connection: close
{
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/claim-statuses/5334032768852043884"
}
},
"id": "5334032768852043884",
"customerId": "1194",
"controlNumber": "36392",
"userId": "userid",
"status": "Complete",
"statusCode": "4",
"createdDate": "2015-06-08T15:41:42.000+0000",
"updatedDate": "2015-06-08T15:41:42.000+0000",
"expirationDate": "2015-06-12T17:20:25.000+0000",
"payer": {
"id": "BCBSF",
"name": "BCBSF"
},
"submitter": {
"lastName": "DOCTORS OFFICE",
"id": "G8486"
},
"providers": [
{
"lastName": "DOCTORS OFFICE"
"npi": "1003847047"
}
],
"subscriber": {
"firstName": "JAMES",
"middleName": "E",
"lastName": "JONES",
"memberId": "ABCD1234567"
},
"patient": {
"firstName": "JAMES",
"middleName": "E",
"lastName": "JONES",
"birthDate": "1991-11-28",
"gender": "Male",
"genderCode": "M",
"accountNumber": "UNKNOWN",
"subscriberRelationship": "Self",
"subscriberRelationshipCode": "18"
},
"claimStatuses": [
{
"traceId": "534180414",
"claimControlNumber": "Q100000471322718",
"facilityTypeCode": "13",
"facilityType": "Hospital Outpatient",
"frequencyTypeCode": "1",
"frequencyType": "Admit thru Discharge Claim",
"patientControlNumber": "UNKNOWN",
"fromDate": "2015-05-15",
"toDate": "2015-05-15",
"statusDetails": [
{
"category": "Finalized The Claim/Encounter has completed the adjudication cycle and no more action will be taken",
"categoryCode": "F0",
"status": "Awaiting next periodic adjudication cycle",
"statusCode": "38",
"effectiveDate": "2015-06-01",
"claimAmount": "1568.34",
"claimAmountUnits": "USD",
"paymentAmount": "0",
"paymentAmountUnits": "USD",
"finalizedDate": "2015-05-27",
"remittanceDate": "2015-06-01",
"checkNumber": "203881588"
}
],
"serviceLines": [
{
"procedureQualifier": "National Uniform Billing Committee (NUBC) UB92 Codes",
"procedureQualifierCode": "NU",
"chargeAmount": "195.87",
"chargeAmountUnits": "USD",
"paymentAmount": "0",
"paymentAmountUnits": "USD",
"quantity": "1",
"controlNumber": "1",
"fromDate": "2015-05-15",
"toDate": "2015-05-15",
"statusDetails": [
{
"category": "Finalized/Payment The Claim/Line has been paid",
"categoryCode": "F1",
"status": "Processed according to contract provisions (Contract refers to provisions that exist between the Health Plan and a Provider of Health Care Services)",
"statusCode": "107",
"effectiveDate": "2015-06-01"
}
]
},
{
"procedureQualifier": "National Uniform Billing Committee (NUBC) UB92 Codes",
"procedureQualifierCode": "NU",
"chargeAmount": "195.79",
"chargeAmountUnits": "USD",
"paymentAmount": "0",
"paymentAmountUnits": "USD",
"quantity": "1",
"controlNumber": "2",
"fromDate": "2015-05-15",
"toDate": "2015-05-15",
"statusDetails": [
{
"category": "Finalized/Payment The Claim/Line has been paid",
"categoryCode": "F1",
"status": "Processed according to contract provisions (Contract refers to provisions that exist between the Health Plan and a Provider of Health Care Services)",
"statusCode": "107",
"effectiveDate": "2015-06-01"
}
]
},
{
"procedureQualifier": "National Uniform Billing Committee (NUBC) UB92 Codes",
"procedureQualifierCode": "NU",
"chargeAmount": "7.52",
"chargeAmountUnits": "USD",
"paymentAmount": "0",
"paymentAmountUnits": "USD",
"quantity": "1",
"controlNumber": "3",
"fromDate": "2015-05-15",
"toDate": "2015-05-15",
"statusDetails": [
{
"category": "Finalized/Payment The Claim/Line has been paid",
"categoryCode": "F1",
"status": "Processed according to contract provisions (Contract refers to provisions that exist between the Health Plan and a Provider of Health Care Services)",
"statusCode": "107",
"effectiveDate": "2015-06-01"
}
]
},
{
"procedureQualifier": "National Uniform Billing Committee (NUBC) UB92 Codes",
"procedureQualifierCode": "NU",
"chargeAmount": "412.54",
"chargeAmountUnits": "USD",
"paymentAmount": "0",
"paymentAmountUnits": "USD",
"quantity": "1",
"controlNumber": "4",
"fromDate": "2015-05-15",
"toDate": "2015-05-15",
"statusDetails": [
{
"category": "Finalized/Payment The Claim/Line has been paid",
"categoryCode": "F1",
"status": "Processed according to contract provisions (Contract refers to provisions that exist between the Health Plan and a Provider of Health Care Services)",
"statusCode": "107",
"effectiveDate": "2015-06-01"
}
]
},
{
"procedureQualifier": "National Uniform Billing Committee (NUBC) UB92 Codes",
"procedureQualifierCode": "NU",
"chargeAmount": "385.41",
"chargeAmountUnits": "USD",
"paymentAmount": "0",
"paymentAmountUnits": "USD",
"quantity": "1",
"controlNumber": "5",
"fromDate": "2015-05-15",
"toDate": "2015-05-15",
"statusDetails": [
{
"category": "Finalized/Payment The Claim/Line has been paid",
"categoryCode": "F1",
"status": "Processed according to contract provisions (Contract refers to provisions that exist between the Health Plan and a Provider of Health Care Services)",
"statusCode": "107",
"effectiveDate": "2015-06-01"
}
]
},
{
"procedureQualifier": "National Uniform Billing Committee (NUBC) UB92 Codes",
"procedureQualifierCode": "NU",
"chargeAmount": "371.21",
"chargeAmountUnits": "USD",
"paymentAmount": "0",
"paymentAmountUnits": "USD",
"quantity": "1",
"controlNumber": "6",
"fromDate": "2015-05-15",
"toDate": "2015-05-15",
"statusDetails": [
{
"category": "Finalized/Payment The Claim/Line has been paid",
"categoryCode": "F1",
"status": "Processed according to contract provisions (Contract refers to provisions that exist between the Health Plan and a Provider of Health Care Services)",
"statusCode": "107",
"effectiveDate": "2015-06-01"
}
]
}
]
}
],
"claimCount": "1"
}
Responses
HTTP Status Code | Description |
---|---|
200 | We have returned an up to date copy of the resource. |
202 | We have not yet received a response from the health plan, but are still trying. You should try again later. |
400 | The health plan indicated that something is wrong with the request. The resource should have a list of validationMessages. Correct and resubmit the request. |
404 | We did not find a ClaimStatus with the id that you specified. |
504 | We did not receive a respsone from the health plan within the time allotted. You should try your request again later. |
DELETE /V1/CLAIM-STATUSES/:ID
You can delete a claim status using this endpoint.
Example
$ curl -H "x-api-key: $API_KEY" -X DELETE -i https://api.availity.com/demo/v1/claim-statuses/-3067319688589945459
->
HTTP/1.1 204 No Content
x-api-id: 98b6e65a-4d97-47f7-b9dc-2addb6544895
X-Session-ID: 98b6e65a-4d97-47f7-b9dc-2addb6544895
X-Api-Mock-Response: true
Cache-Control: private, no-store, max-age=0, must-revalidate
Content-Type: application/json
Date: Tue, 9 Jun 2015 09:30:37 GMT
X-Global-Transaction-ID: 37112879
Connection: close
Responses
HTTP Status Code | Description |
---|---|
204 | We have deleted the resource from our system. |
404 | We did not find a ClaimStatus with the id that you specified. |
Care Cost Estimator - Professional
A Care Cost Estimator (CCE), also known as Predetermination
, is a claim request for payment that a health care provider submits to a health plan before they've provided a service or items to a member. Your application can use this endpoint to submit an professional claim predetermination for an professional claim, additionally you can use the endpoint to find and manage previous claim predetermination requests.
Working with the DEMO endpoints
Availity allows you to specify the type of response you want when interacting with our Professional Care Cost Estimator demonstration service by sending a header (X-Api-Mock-Scenario-ID) with the appropriate response scenario id. The supported response scenarios are listed below.
For POST methods send an empty JSON body such as: "{}"
Response Scenario ID | Method | HTTP Status | Description |
---|---|---|---|
CCEP-Success | GET - use id 123 | 200 | Availity has successfully retrieved the member's claim predetermination information from the health plan. |
CCEP-Accepted | POST | 202 | Availity is in the process of retrieving the member's claim predetermination information from the health plan. |
CCEP-RequestErrors1 | POST | 400 | Your request failed Availity's input validation rules. |
CCEP-RequestErrors2 | POST | 400 | Your request failed Availity's input validation rules. |
CCEP-RequestParseError | POST | 500 | We were unable to parse your request. |
CCEP-MultiServiceLines | GET - use id 54321 | 200 | Availity has successfully retrieved the member's claim predetermination information that contains multiple service lines from the health plan. |
You can confirm you've received a mock response by inspecting the response headers. You should see the following header:
X-Api-Mock-Response: true
Overview
A predetermination of benefits is a review by a health plans automated claim processing system or a their medical staff to decide if they agree that the treatment is right for the patient's health needs. A predetermination is done before a patient receives healthcare. This allows the patient to know early if it is covered by their health plan.
Each health plan has different required information they need to process a CCE. Because of this, you'll want to ensure you utilize the Configurations
service to determine the required fields for a specific health plan before submitting it. See the Configurations service for details on it's use.
Configuration Service Subtype
The type name for the professional-claims
service is: professional-claims Use the subtypeId name of: PRE_DETERMINATION
Example usage:
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/configurations?type=professional-claims&payerId=BCBSF&subtypeId=PRE_DETERMINATION
Submitting a Predetermination Claim
The PRE_DETERMINATION request type submits a claim request to a health plan to determine a patient's out of pocket estimate based on their plans coverage. Note that this does not produce an adjudicated claim.
The Resource
Field | Type | Description |
---|---|---|
id | String | A unique identifier that Availity has assigned to this ProfessionalClaim. |
createdDate | TimeStamp | The date and time when this item was created in Availity's system. |
updatedDate | TimeStamp | The date and time when this item was last updated. |
expirationDate | TimeStamp | The date and time when this item will be removed from Availity's system. |
customerId | String | The id of the Availity customer that owns this ProfessionalClaim. Availity may ask for this during support calls. |
requestTypeCode | String | The type of request to perform for professional claims. Use PRE_DETERMINATION for Predetermination. |
submitter | Object | An object representing the submitter of a claim. |
submitter.lastName | String | The last or business name of the submitter. |
submitter.firstName | String | The first name of the submitter. |
submitter.middleName | String | The middle name of the submitter. |
submitter.suffix | String | The suffix of the submitter. |
submitter.id | String | The identifier of the submitter. |
submitter.contactName | String | The contact name of the submitter. |
submitter.phone | String | The phone number of the submitter. |
submitter.extension | String | The phone extension of the submitter. |
submitter.fax | String | The fax number of the submitter. |
submitter.email | String | The email of the submitter. |
payer | Object | An object representing the health plan of the patient. |
payer.id | String | The Availity id of the health plan. |
payer.name | String | The name of the health plan. |
payer.claimFilingIndicatorCode | String | The claim filing indicator code for the type of insurance. |
billingProvider | Object | An object representing the billing provider of the claim. |
billingProvider.specialtyCode | String | The claim filing indicator code for the type of insurance. |
billingProvider.lastName | String | The last name of individual (Person) or business name (Non-Person Entity) of the billing provider. – REQUIRED |
billingProvider.firstName | String | The first name of the billing provider. Situational: REQUIRED if submitting Individual (Person) billingProvider.ein or billingProvider.ssn |
billingProvider.middleName | String | The middle name of the billing provider. |
billingProvider.suffix | String | The suffix of the billing provider. |
billingProvider.npi | String | The national provider id of the billing provider. |
billingProvider.addressLine1 | String | The first line of the address of the billing provider. |
billingProvider.addressLine2 | String | The second line of the address of the billing provider. |
billingProvider.city | String | The city of the billing provider. |
billingProvider.stateCode | String | The code of the state of the billing provider. |
billingProvider.zipCode | String | The ZIP code of the billing provider. |
billingProvider.ein | String | The employer identification number of the billing provider. |
billingProvider.ssn | String | The social security number of the billing provider. |
billingProvider.stateLicenseNumber | String | The state license number of the billing provider. |
billingProvider.payerAssignedProviderId | String | The payer assigned provider id of the billing provider. |
billingProvider.contactName | String | The contact name of the billing provider. |
billingProvider.phone | String | The phone number of the billing provider. |
billingProvider.extension | String | The phone extension of the billing provider. |
billingProvider.fax | String | The fax number of the billing provider. |
billingProvider.email | String | The email of the billing provider. |
billingProvider.payTo.addressLine1 | String | The first line of the address for the pay to of the billing provider. |
billingProvider.payTo.addressLine2 | String | The second line of the address for the pay to of the billing provider. |
billingProvider.payTo.city | String | The city of the pay to of the billing provider. |
billingProvider.payTo.stateCode | String | The code of the state for the pay to of the billing provider. |
billingProvider.payTo.zipCode | String | The ZIP code for the pay to of the billing provider. |
subscriber | Object | An object representing the subscriber of the claim. |
subscriber.lastName | String | The last or business name of the subscriber. |
subscriber.firstName | String | The first name of the subscriber. |
subscriber.middleName | String | The middle name of the subscriber. |
subscriber.suffix | String | The suffix of the subscriber. |
subscriber.memberId | String | The member id of the subscriber. |
subscriber.groupNumber | String | The group number of the subscriber. |
subscriber.groupName | String | The group name of the subscriber. |
subscriber.addressLine1 | String | The first line of the address of the subscriber. |
subscriber.addressLine2 | String | The second line of the address of the subscriber. |
subscriber.city | String | The city of the subscriber. |
subscriber.stateCode | String | The code of the state of the subscriber. |
subscriber.zipCode | String | The ZIP code of the subscriber. |
subscriber.totalDeductible | String | The total individual deductible dollar amount for this health care plan. |
subscriber.accumulatedDeductible | String | The accumulated individual deductible dollar amount for this health care plan. |
subscriber.remainingDeductible | String | The remaining individual deductible dollar amount for this health care plan. |
subscriber.onHold | Boolean | Indicates where the subscriber is on hold. |
subscriber.holdReasons | Object Array | An array of hold reasons for the claim. |
subscriber.holdReasons.code | String | A code indicating the hold reason. |
subscriber.holdReasons.description | String | A description for why the hold is in place. |
patient | Object | An object representing the patient of the claim. |
patient.lastName | String | The last or business name of the patient. |
patient.firstName | String | The first name of the patient. |
patient.middleName | String | The middle name of the patient. |
patient.suffix | String | The suffix of the patient. |
patient.addressLine1 | String | The first line of the address of the patient. |
patient.addressLine2 | String | The second line of the address of the patient. |
patient.city | String | The city of the patient. |
patient.stateCode | String | The code of the state of the patient. |
patient.zipCode | String | The ZIP code of the patient. |
patient.birthDate | Date | The birth date of the patient. |
patient.gender | String | A description of the gender of the patient. |
patient.genderCode | String | A code representing the gender of the patient. |
patient.subscriberRelationship | String | A description of the patient's relationship to the subscriber. |
patient.subscriberRelationshipCode | String | A code representing the patient's relationship to the subscriber. |
claimInformation | Object | An object representing the claim information of the claim. |
claimInformation.bundled | Boolean | Indicating whether the payer believes that the actual services performed and reported must be paid under only one procedure code. |
claimInformation.controlNumber | String | A unique reference identifier provided by the submitter. |
claimInformation.placeOfServiceCode | String | A code representing the place of service. |
claimInformation.frequencyTypeCode | String | A code specifying the frequency of the claim. |
claimInformation.providerSignatureOnFile | Boolean | Indicates whether a provider's signature is on file with the healthcare plan. |
claimInformation.providerAcceptAssignmentCode | String | A code indicating whether the provider accepts assignment. |
claimInformation.benefitsAssignmentCertification | String | A code indicating assignment of benefits for a claim. |
claimInformation.informationReleaseCode | String | A code indicating whether the provider has on file a signed statement by the patient authorizing the release of medical data to other organizations. |
claimInformation.displayMessage | String | The display message a payer may return. |
claimInformation.messages | Object Array | An array of messages. |
claimInformation.messages.code | String | The message code. |
claimInformation.messages.description | String | The message description. |
claimInformation.messages.procedure | String | The procedure for the message. |
claimInformation.diagnoses | Object Array | An array of diagnosis codes for the claim. |
claimInformation.diagnoses.qualifier | String | The description of the qualifier indicating what type of diagnosis code is used. |
claimInformation.diagnoses.qualifierCode | String | A code representing the qualifier indicating what type of diagnosis code is used. |
claimInformation.diagnoses.code | String | A code representing the diagnosis. |
claimInformation.serviceLines | Object Array | An array of service lines for the claim. |
claimInformation.serviceLines.fromDate | String | The start date of the service. |
claimInformation.serviceLines.toDate | String | The end date of the service. |
claimInformation.serviceLines.controlNumber | String | A unique reference identifier provided by the submitter. |
claimInformation.serviceLines.placeOfServiceCode | String | A code representing the place of service. This overrides the placeOfServiceCode at the Claim Information level. |
claimInformation.serviceLines.procedureCode | String | A code representing the procedure performed. |
claimInformation.serviceLines.modifierCode1 | String | A description of the first modifier applied to this procedure. |
claimInformation.serviceLines.modifierCode2 | String | A description of the second modifier applied to this procedure. |
claimInformation.serviceLines.modifierCode3 | String | A description of the third modifier applied to this procedure. |
claimInformation.serviceLines.modifierCode4 | String | A description of the forth modifier applied to this procedure. |
claimInformation.serviceLines.diagnosisCodePointer1 | String | A pointer to the first diagnosis code in this service. |
claimInformation.serviceLines.diagnosisCodePointer2 | String | A pointer to the second diagnosis code in this service. |
claimInformation.serviceLines.diagnosisCodePointer3 | String | A pointer to the third diagnosis code in this service. |
claimInformation.serviceLines.diagnosisCodePointer4 | String | A pointer to the forth diagnosis code in this service. |
claimInformation.serviceLines.amount | String | This total charge amount for this service line. The amount is inclusive of the provider’s base charge and any applicable tax and/or postage claimed amounts. |
claimInformation.serviceLines.quantity | String | The units of service. |
claimInformation.serviceLines.quantityTypeCode | String | A code representing the quantity units. |
claimInformation.serviceLines.estimatedPatientResponsibility | String | The estimated amount of the patient's responsibility. |
claimInformation.serviceLines.bundlingDescription | String | The service bundling description. |
claimInformation.serviceLines.denyReason | String | The reason why the procedure is denied. |
claimInformation.serviceLines.holdReasons | Object Array | An array of hold reasons for the procedure. |
claimInformation.serviceLines.holdReasons.code | String | The hold reason code. |
claimInformation.serviceLines.holdReasons.description | String | The hold reason description. |
claimInformation.serviceLines.messages | Object Array | An array of messages for the procedure. |
claimInformation.serviceLines.messages.code | String | The message code. |
claimInformation.serviceLines.messages.description | String | The message description. |
claimInformation.serviceLines.messages.procedure | String | The procedure for the message. |
claimInformation.serviceLines.displayMessage | String | The display message a payer may return. |
claimInformation.serviceLines.allowed | Object | An object representing the allowed portion of the procedure performed. |
claimInformation.serviceLines.allowed.amount | String | The amount allowed for the procedure performed. |
claimInformation.serviceLines.allowed.code | String | The code for the procedure performed. |
claimInformation.serviceLines.allowed.codeType | String | A code type for the procedure performed. |
claimInformation.serviceLines.allowed.description | String | The description of the allowed amount the procedure performed. |
claimInformation.serviceLines.allowed.procedure | String | The procedure code of the procedure performed. |
claimInformation.serviceLines.allowed.patientLiable | Boolean | Indicates whether the patient is liable. |
claimInformation.serviceLines.notCovered | Object | An object representing the not covered portion of the procedure performed. |
claimInformation.serviceLines.notCovered.amount | String | The amount not covered for the procedure performed. |
claimInformation.serviceLines.notCovered.code | String | The code for the procedure performed. |
claimInformation.serviceLines.notCovered.codeType | String | A code type for the procedure performed. |
claimInformation.serviceLines.notCovered.description | String | The description of the not covered amount the procedure performed. |
claimInformation.serviceLines.notCovered.procedure | String | The procedure code of the procedure performed. |
claimInformation.serviceLines.notCovered.patientLiable | Boolean | Indicates whether the patient is liable. |
claimInformation.serviceLines.coPay | Object | An object representing the copay portion of the procedure performed. |
claimInformation.serviceLines.coPay.amount | String | The amount of copay for the procedure performed. |
claimInformation.serviceLines.coPay.code | String | The code for the procedure performed. |
claimInformation.serviceLines.coPay.codeType | String | A code type for the procedure performed. |
claimInformation.serviceLines.coPay.description | String | The description of the copay amount the procedure performed. |
claimInformation.serviceLines.coPay.procedure | String | The procedure code of the procedure performed. |
claimInformation.serviceLines.coPay.patientLiable | Boolean | Indicates whether the patient is liable. |
claimInformation.serviceLines.coInsurance | Object | An object representing the co-insurance portion of the procedure performed. |
claimInformation.serviceLines.coInsurance.amount | String | The amount of co-insurance for the procedure performed. |
claimInformation.serviceLines.coInsurance.code | String | The code for the procedure performed. |
claimInformation.serviceLines.coInsurance.codeType | String | A code type for the procedure performed. |
claimInformation.serviceLines.coInsurance.description | String | The description of the co-insurance amount the procedure performed. |
claimInformation.serviceLines.coInsurance.procedure | String | The procedure code of the procedure performed. |
claimInformation.serviceLines.coInsurance.patientLiable | Boolean | Indicates whether the patient is liable. |
claimInformation.serviceLines.deductible | Object | An object representing the deductible portion of the procedure performed. |
claimInformation.serviceLines.deductible.amount | String | The amount of deductible for the procedure performed. |
claimInformation.serviceLines.deductible.code | String | The code for the procedure performed. |
claimInformation.serviceLines.deductible.codeType | String | A code type for the procedure performed. |
claimInformation.serviceLines.deductible.description | String | The description of the deductible amount the procedure performed. |
claimInformation.serviceLines.deductible.procedure | String | The procedure code of the procedure performed. |
claimInformation.serviceLines.deductible.patientLiable | Boolean | Indicates whether the patient is liable. |
POST /V1/PROFESSIONAL-CLAIMS
This endpoint creates a CCE asynchronously. To submit a CCE, make a valid request and a response will be returned with a location header containing a URL you can query for your result.
RESPONSES
HTTP Status Code | Description |
---|---|
202 | The CCE was accepted for processing. Poll the URL in the Location header. The X-Status-Message header will contain additional detail. |
400 | The CCE request failed validation. It either failed our validation rules or was rejected by the health plan. The errors property will contain detailed information. Errors that specify a field are Availity validation rule failures. Errors that specify a code are from the health plan. Correct the errors and resubmit the request. |
500 | We were unable to parse your request. Correct the errors and resubmit the request. |
VALIDATION RULES
The validation rules for the ProfessionalClaim resource can vary by health plan, the type of claim being requested, and the type of service to be performed. Availity organizes these rules and makes them available through the Configuration
service. The Configuration
resource documents the fields you need to send to create a ProfessionalClaim and explains what values are valid for those fields. See the Configurations service for details.
EXAMPLES
If your request is invalid, we will respond with a status code of 400 and a list of errors for you to correct.
$ curl -i -H "x-api-key: $API_KEY" -H "Content-Type: application/json" -X POST -d '{
"requestTypeCode": "PRE_DETERMINATION",
"billingProvider": {
"npi": "123456789"
},
"patient": {
"relationshipCode": "01",
"lastName": "Smith",
"firstName": "Bob",
"stateCode": "FL",
"birthDate": "1980-02-12",
"genderCode": "M"
},
"payer": {
"id": "BCBSF"
},
"submitter": {
"id": "123456789",
"lastName": "SUBMITTER"
},
"subscriber": {
"memberId": "JDH001",
"groupName": "ASDF 1-2",
"groupNumber": "12312412"
},
"claimInformation": {
"placeOfServiceCode": "11",
"diagnoses": [
{
"qualifierCode": "ABK",
"code": "J3089"
}
],
"serviceLines": [
{
"procedureCode": "92523",
"quantity": "100",
"amount": "250",
"fromDate": "2016-05-10"
}
]
}
}' https://api.availity.com/demo/v1/professional-claims
HTTP/1.1 400 Bad Request
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json
Date: Fri, 03 Jun 2016 18:19:16 GMT
x-api-id: 7407a7ee-1940-4c8b-b9ec-57e9b0059214
X-Session-ID: 7407a7ee-1940-4c8b-b9ec-57e9b0059214
Connection: close
{
"userMessage" : "Your request was invalid.",
"developerMessage" : "The request was invalid. See the 'errors' property for details.",
"reasonCode" : 0,
"statusCode" : 400,
"errors" : [ {
"field" : "billingProvider.ein",
"errorMessage" : "Enter a valid Billing Provider EIN.",
"index" : 0,
"nestedEntityErrors" : [ ]
}, {
"field" : "billingProvider.npi",
"errorMessage" : "Enter a valid Billing Provider National Provider Identifier (NPI) containing 10 numeric digits and beginning with a 1, 2, 3, or 4.",
"index" : 0,
"nestedEntityErrors" : [ ]
}, {
"field" : "billingProvider.payerAssignedProviderId",
"errorMessage" : "Enter a valid Billing Provider Payer Assigned Provider ID",
"index" : 0,
"nestedEntityErrors" : [ ]
} ]
}
If your request is valid, we will respond with a status code of 202 and a location header where you can check back for your response. We will continue to respond in this way until we have heard back from the health plan.
$ curl -i -H "x-api-key: $API_KEY" -H "Content-Type: application/json" -X POST -d '{
"requestTypeCode": "PRE_DETERMINATION",
"billingProvider": {
"npi": "1234567893",
"ein": "111222333",
"payerAssignedProviderId": "XYZ321"
},
"patient": {
"relationshipCode": "01",
"lastName": "Smith",
"firstName": "Bob",
"stateCode": "FL",
"birthDate": "1980-02-12",
"genderCode": "M"
},
"payer": {
"id": "BCBSF"
},
"submitter": {
"id": "123456789",
"lastName": "SUBMITTER"
},
"subscriber": {
"memberId": "JDH001",
"groupName": "ASDF 1-2",
"groupNumber": "12312412"
},
"claimInformation": {
"placeOfServiceCode": "11",
"diagnoses": [
{
"qualifierCode": "ABK",
"code": "J3089"
}
],
"serviceLines": [
{
"procedureCode": "92523",
"quantity": "100",
"amount": "250",
"fromDate": "2016-05-10"
}
]
}
}' https://api.availity.com/demo/v1/professional-claims
->
HTTP/1.1 202 Accepted
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json;charset=utf-8
Date: Fri, 03 Jun 2016 20:00:40 GMT
Location: https://api.availity.com/demo/v1/professional-claims/1684335841477061460
x-api-id: 78a4490e-8437-49c1-a5b5-0eab3ba1d996
X-Session-ID: 78a4490e-8437-49c1-a5b5-0eab3ba1d996
X-Status-Message: We are processing your request.
Connection: close
GET /V1/PROFESSIONAL-CLAIMS/:ID
You can retrieve a CCE using this endpoint.
RESPONSES
HTTP Status Code | Description |
---|---|
200 | We are done processing your request and the response body contains the result. |
202 | We are currently processing your request. We may be retrying it. |
400 | Your CCE request failed validation. You can correct the errors and resubmit. |
404 | We did not find a ProfessionalClaim with the id that you sent. |
504 | We were unable to process your request. The health plan did not respond after several retry attempts. Please try your request again later. |
EXAMPLES
You can request the URI that was returned in the Location response header during from your POST request. If the resource is found but we have not received a response from the health plan, we will respond with a status code of 202 and a Location header where you can check back for your response. We will continue to respond in this way until we have heard back from the health plan.
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/professional-claims/1684335841477061460
->
HTTP/1.1 202 Accepted
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json;charset=utf-8
Date: Mon, 06 Jun 2016 18:11:34 GMT
Location: https://api.availity.com/demo/v1/professional-claims/1684335841477061460
x-api-id: 25a71361-7f75-4dc9-918b-021e163b0df8
X-Session-ID: 25a71361-7f75-4dc9-918b-021e163b0df8
X-Status-Message: The health plan did not respond. We are retrying the request.
Connection: close
Once we have a response from the health plan, we will respond with a status code of 200 and a ProfessionalClaim resource.
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/professional-claims/1684335841477061460
->
HTTP/1.1 200 OK
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json;charset=utf-8
Date: Mon, 06 Jun 2016 18:35:19 GMT
x-api-id: 22d78708-6094-4e95-a8fe-3bb762975fd3
X-Availity-Transaction-ID: 1613032
X-Session-ID: 22d78708-6094-4e95-a8fe-3bb762975fd3
Connection: close
Server: Jetty(8.1.17.v20150415)
{
"id" : "1684335841477061460",
"createdDate" : "2016-06-06T18:34:46.000+0000",
"updatedDate" : "2016-06-06T18:34:52.000+0000",
"expirationDate" : "2016-06-07T18:34:46.000+0000",
"requestTypeCode" : "PRE_DETERMINATION",
"submitter" : {
"lastName" : "Island Ear Nose and Throat",
"id" : "263749002"
},
"payer" : {
"id" : "BCBSF"
},
"billingProvider" : {
"npi" : "1255569224",
"payerAssignedProviderId" : "G4402"
},
"subscriber" : {
"memberId" : "H23183209",
"totalDeductible" : "6100.00",
"accumulatedDeductible" : "0.00",
"remainingDeductible" : "6100.00",
"onHold" : false
},
"patient" : {
"lastName" : "CARIDAD",
"firstName" : "ANISLEIDY",
"birthDate" : "1992-11-22",
"gender" : "Female",
"genderCode" : "F",
"subscriberRelationship" : "Self",
"subscriberRelationshipCode" : "18"
},
"claimInformation" : {
"bundled" : false,
"diagnoses" : [ {
"qualifier" : "International Classification of Diseases Clinical Modification (ICD-10-CM) Principal Diagnosis",
"qualifierCode" : "ABK",
"code" : "J3089"
} ],
"serviceLines" : [ {
"procedure" : "PROFESSIONAL SVCS FOR THE SUPERVISION OF PREP & PROVISION OF ANTIGENS FOR ALLERGEN IMMUNOTHERAPY; SINGLE OR MULTIPLE ANTIGENS (SPE",
"procedureCode" : "95165",
"amount" : "2500.00",
"estimatedPatientResponsibility" : "10.00",
"allowed" : {
"amount" : "1807.50",
"code" : "PPSCH",
"codeType" : "AL",
"description" : "Allowed amount based on fee schedule",
"patientLiable" : false
},
"coPay" : {
"amount" : "10.00",
"code" : "BCPI",
"codeType" : "CP",
"patientLiable" : true
}
} ]
}
}
Care Cost Estimator - Institutional
A Care Cost Estimator (CCE), also known as Predetermination
, is a claim request for payment that a health care provider submits to a health plan before they've provided a service or items to a member. Your application can use this endpoint to submit an institutional claim predetermination for an institutional claim, additionally you can use the endpoint to find and manage previous claim predetermination requests.
Working with the DEMO endpoints
Availity allows you to specify the type of response you want when interacting with our Institutional Care Cost Estimator demonstration service by sending a header (X-Api-Mock-Scenario-ID) with the appropriate response scenario id. The supported response scenarios are listed below.
For POST methods send an empty JSON body such as: "{}"
Response Scenario ID | Method | HTTP Status | Description |
---|---|---|---|
CCEI-Success | GET - use id 123 | 200 | Availity has successfully retrieved the member's CCE predetermination information from the health plan. |
CCEI-Accepted | POST | 202 | Availity is in the process of retrieving the member's CCE predetermination information from the health plan. |
CCEI-RequestErrors1 | POST | 400 | Your request failed Availity's input validation rules. |
CCEI-RequestErrors2 | POST | 400 | Your request failed Availity's input validation rules. |
CCEI-RequestParseError | POST | 500 | We were unable to parse your request. |
You can confirm you've received a mock response by inspecting the response headers. You should see the following header:
X-Api-Mock-Response: true
Overview
A predetermination of benefits is a review by a health plans automated claim processing system or a their medical staff to decide if they agree that the treatment is right for the patient's health needs. A predetermination is done before a patient receives healthcare. This allows the patient to know early if it is covered by their health plan.
Each health plan has different required information they need to process a CCE. Because of this, you'll want to ensure you utilize the Configurations
service to determine the required fields for a specific health plan before submitting it. See the Configurations service for details on it's use.
Configuration Service Subtype
The type name for the institutional-claims
service is: institutional-claims Use the subtypeId name of: PRE_DETERMINATION
Example usage:
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/configurations?type=institutional-claims&payerId=BCBSF&subtypeId=PRE_DETERMINATION
Submitting a Predetermination Institutional Claim
The PRE_DETERMINATION request subtype submits a claim request to a health plan to determine a patient's out of pocket estimate based on their plans coverage. Note that this does not produce an adjudicated claim.
The Resource
Field | Type | Description |
---|---|---|
id | String | A unique identifier that Availity has assigned to this InstitutionalClaim. |
createdDate | TimeStamp | The date and time when this item was created in Availity's system. |
updatedDate | TimeStamp | The date and time when this item was last updated. |
expirationDate | TimeStamp | The date and time when this item will be removed from Availity's system. |
customerId | String | The id of the Availity customer that owns this InstitutionalClaim. Availity may ask for this during support calls. |
requestTypeCode | String | The type of request to perform for institutional claims. Use PRE_DETERMINATION for Predetermination. |
submitter | Object | An object representing the submitter of a claim. |
submitter.lastName | String | The last or business name of the submitter. |
submitter.firstName | String | The first name of the submitter. |
submitter.middleName | String | The middle name of the submitter. |
submitter.suffix | String | The suffix of the submitter. |
submitter.id | String | The identifier of the submitter. |
submitter.contactName | String | The contact name of the submitter. |
submitter.phone | String | The phone number of the submitter. |
submitter.extension | String | The phone extension of the submitter. |
submitter.fax | String | The fax number of the submitter. |
submitter.email | String | The email of the submitter. |
payer | Object | An object representing the health plan of the patient. |
payer.id | String | The Availity id of the health plan. |
payer.name | String | The name of the health plan. |
payer.claimFilingIndicatorCode | String | The claim filing indicator code for the type of insurance. |
billingProvider | Object | An object representing the billing provider of the claim. |
billingProvider.specialtyCode | String | The claim filing indicator code for the type of insurance. |
billingProvider.name | String | The business name of the billing provider. |
billingProvider.npi | String | The national provider id of the billing provider. |
billingProvider.addressLine1 | String | The first line of the address of the billing provider. |
billingProvider.addressLine2 | String | The second line of the address of the billing provider. |
billingProvider.city | String | The city of the billing provider. |
billingProvider.stateCode | String | The code of the state of the billing provider. |
billingProvider.zipCode | String | The ZIP code of the billing provider. |
billingProvider.ein | String | The employer identification number of the billing provider. |
billingProvider.payerAssignedProviderId | String | The payer assigned provider id of the billing provider. |
billingProvider.contactName | String | The contact name of the billing provider. |
billingProvider.phone | String | The phone number of the billing provider. |
billingProvider.extension | String | The phone extension of the billing provider. |
billingProvider.fax | String | The fax number of the billing provider. |
billingProvider.email | String | The email of the billing provider. |
billingProvider.payTo.addressLine1 | String | The first line of the address for the pay to of the billing provider. |
billingProvider.payTo.addressLine2 | String | The second line of the address for the pay to of the billing provider. |
billingProvider.payTo.city | String | The city of the pay to of the billing provider. |
billingProvider.payTo.stateCode | String | The code of the state for the pay to of the billing provider. |
billingProvider.payTo.zipCode | String | The ZIP code for the pay to of the billing provider. |
subscriber | Object | An object representing the subscriber of the claim. |
subscriber.lastName | String | The last or business name of the subscriber. |
subscriber.firstName | String | The first name of the subscriber. |
subscriber.middleName | String | The middle name of the subscriber. |
subscriber.suffix | String | The suffix of the subscriber. |
subscriber.memberId | String | The member id of the subscriber. |
subscriber.groupNumber | String | The group number of the subscriber. |
subscriber.groupName | String | The group name of the subscriber. |
subscriber.addressLine1 | String | The first line of the address of the subscriber. |
subscriber.addressLine2 | String | The second line of the address of the subscriber. |
subscriber.city | String | The city of the subscriber. |
subscriber.stateCode | String | The code of the state of the subscriber. |
subscriber.zipCode | String | The ZIP code of the subscriber. |
subscriber.totalFamilyDeductible | String | The total family deductible dollar amount for the health care plan. |
subscriber.accumulatedFamilyDeductible | String | The accumulated family deductible dollar amount for the health care plan. |
subscriber.remainingFamilyDeductible | String | The remaining family deductible dollar amount for the health care plan. |
subscriber.totalDeductible | String | The total individual deductible dollar amount for this health care plan. |
subscriber.accumulatedDeductible | String | The accumulated individual deductible dollar amount for this health care plan. |
subscriber.remainingDeductible | String | The remaining individual deductible dollar amount for this health care plan. |
subscriber.onHold | Boolean | Indicates whether a subscriber is on hold. |
subscriber.holdReasons | Object Array | An array of hold reasons for the claim. |
subscriber.holdReasons.code | String | A code indicating the hold reason. |
subscriber.holdReasons.description | String | A description for why the hold is in place. |
patient | Object | An object representing the patient of the claim. |
patient.lastName | String | The last or business name of the patient. |
patient.firstName | String | The first name of the patient. |
patient.middleName | String | The middle name of the patient. |
patient.suffix | String | The suffix of the patient. |
patient.addressLine1 | String | The first line of the address of the patient. |
patient.addressLine2 | String | The second line of the address of the patient. |
patient.city | String | The city of the patient. |
patient.stateCode | String | The code of the state of the patient. |
patient.zipCode | String | The ZIP code of the patient. |
patient.birthDate | Date | The birth date of the patient. |
patient.gender | String | A description of the gender of the patient. |
patient.genderCode | String | A code representing the gender of the patient. |
patient.subscriberRelationship | String | A description of the patient's relationship to the subscriber. |
patient.subscriberRelationshipCode | String | A code representing the patient's relationship to the subscriber. |
claimInformation | Object | An object representing the claim information of the claim. |
claimInformation.controlNumber | String | A unique reference identifier provided by the submitter that was provided in the original claim status request. |
claimInformation.facilityTypeCode | String | A code representing where services may be performed. |
claimInformation.frequencyTypeCode | String | A code specifying the frequency of the claim. |
claimInformation.providerAcceptAssignmentCode | String | A code indicating whether the provider accepts assignment. |
claimInformation.benefitsAssignmentCertification | String | A code indicating assignment of benefits for a claim. |
claimInformation.informationReleaseCode | String | A code indicating whether the provider has on file a signed statement by the patient authorizing the release of medical data to other organizations. |
claimInformation.admissionTypeCode | String | A code indicating the priority of this admission. |
claimInformation.admissionSourceCode | String | A code indicating the source of this admission. |
claimInformation.patientStatusCode | String | A code indicating patient status as of the "statement covers through date". |
claimInformation.bundled | Boolean | Indicating whether the payer believes that the actual services performed and reported must be paid under only one procedure code. |
claimInformation.displayMessage | String | The display message a payer may return. |
claimInformation.principalDiagnosis | Object | An object representing the principal diagnosis code for the claim. |
claimInformation.principalDiagnosis.qualifier | String | The description of the qualifier indicating what type of diagnosis code is used. |
claimInformation.principalDiagnosis.qualifierCode | String | A code representing the qualifier indicating what type of diagnosis code is used. |
claimInformation.principalDiagnosis.presentOnAdmissionIndicatorCode | String | Identifies the diagnosis onset as it relates to the diagnosis code. |
claimInformation.otherDiagnoses | Object Array | An array representing the other diagnosis codes for the claim. |
claimInformation.otherDiagnoses.qualifier | String | The description of the qualifier indicating what type of diagnosis code is used. |
claimInformation.otherDiagnoses.qualifierCode | String | A code representing the qualifier indicating what type of diagnosis code is used. |
claimInformation.otherDiagnoses.presentOnAdmissionIndicatorCode | String | Identifies the diagnosis onset as it relates to the diagnosis code. |
claimInformation.principalProcedure | Object | An object representing the principal procedure code for the claim. |
claimInformation.principalProcedure.qualifier | String | The description of the qualifier indicating what type of procedure code is used. |
claimInformation.principalProcedure.qualifierCode | String | A code representing the qualifier indicating what type of procedure code is used. |
claimInformation.principalProcedure.code | String | A code respresenting the procedure performed. |
claimInformation.otherProcedures | Object Array | An array representing the other procedure codes for the claim. |
claimInformation.otherProcedures.qualifier | String | The description of the qualifier indicating what type of procedure code is used. |
claimInformation.otherProcedures.qualifierCode | String | A code representing the qualifier indicating what type of procedure code is used. |
claimInformation.otherProcedures.code | String | A code representing the procedure performed. |
claimInformation.serviceLines | Object Array | An array of service lines for the claim. |
claimInformation.controlNumber | String | A unique reference identifier provided by the submitter that was provided in the original claim status request. |
claimInformation.serviceLines.fromDate | String | The start date of the service. |
claimInformation.serviceLines.toDate | String | The end date of the service. |
claimInformation.serviceLines.revenueCode | String | The identifying number for a product or service. |
claimInformation.serviceLines.procedure | Stirng | The description of the procedure performed. |
claimInformation.serviceLines.procedureCode | String | A code respresenting the procedure performed. |
claimInformation.serviceLines.modifierCode1 | String | A description of the first modifier applied to this procedure. |
claimInformation.serviceLines.modifierCode2 | String | A description of the second modifier applied to this procedure. |
claimInformation.serviceLines.modifierCode3 | String | A description of the third modifier applied to this procedure. |
claimInformation.serviceLines.modifierCode4 | String | A description of the forth modifier applied to this procedure. |
claimInformation.serviceLines.amount | String | This total charge amount for this service line. The amount is inclusive of the provider’s base charge and any applicable tax and/or postage claimed amounts. |
claimInformation.serviceLines.quantity | String | The units of service. |
claimInformation.serviceLines.quantityTypeCode | String | A code representing the quantity units. |
claimInformation.serviceLines.estimatedPatientResponsibility | String | The estimated amount of the patient's responsibility. |
claimInformation.serviceLines.bundlingDescription | String | The description from the payer if bundling was performed. |
claimInformation.serviceLines.denyReason | String | The reason why the procedure is denied. |
claimInformation.serviceLines.holdReasons | Object Array | An array of hold reasons for the procedure. |
claimInformation.serviceLines.holdReasons.code | String | The hold reason code. |
claimInformation.serviceLines.holdReasons.description | String | The hold reason description. |
claimInformation.serviceLines.messages | Object Array | An array of messages for the procedure. |
claimInformation.serviceLines.messages.code | String | The message code. |
claimInformation.serviceLines.messages.description | String | The message description. |
claimInformation.serviceLines.messages.procedure | String | The procedure for the message. |
claimInformation.serviceLines.displayMessage | String | The display message a payer may return. |
claimInformation.serviceLines.allowed | Object | An object representing the allowed portion of the procedure performed. |
claimInformation.serviceLines.allowed.amount | String | The amount allowed for the procedure performed. |
claimInformation.serviceLines.allowed.code | String | The code for the procedure performed. |
claimInformation.serviceLines.allowed.codeType | String | A code type for the procedure performed. |
claimInformation.serviceLines.allowed.description | String | The description of the allowed amount the procedure performed. |
claimInformation.serviceLines.allowed.procedure | String | The procedure code of the procedure performed. |
claimInformation.serviceLines.allowed.patientLiable | Boolean | Indicates whether the patient is liable. |
claimInformation.serviceLines.notCovered | Object | An object representing the not covered portion of the procedure performed. |
claimInformation.serviceLines.notCovered.amount | String | The amount not covered for the procedure performed. |
claimInformation.serviceLines.notCovered.code | String | The code for the procedure performed. |
claimInformation.serviceLines.notCovered.codeType | String | A code type for the procedure performed. |
claimInformation.serviceLines.notCovered.description | String | The description of the not covered amount the procedure performed. |
claimInformation.serviceLines.notCovered.procedure | String | The procedure code of the procedure performed. |
claimInformation.serviceLines.notCovered.patientLiable | Boolean | Indicates whether the patient is liable. |
claimInformation.serviceLines.coPay | Object | An object representing the copay portion of the procedure performed. |
claimInformation.serviceLines.coPay.amount | String | The amount of copay for the procedure performed. |
claimInformation.serviceLines.coPay.code | String | The code for the procedure performed. |
claimInformation.serviceLines.coPay.codeType | String | A code type for the procedure performed. |
claimInformation.serviceLines.coPay.description | String | The description of the copay amount the procedure performed. |
claimInformation.serviceLines.coPay.procedure | String | The procedure code of the procedure performed. |
claimInformation.serviceLines.coPay.patientLiable | Boolean | Indicates whether the patient is liable. |
claimInformation.serviceLines.coInsurance | Object | An object representing the co-insurance portion of the procedure performed. |
claimInformation.serviceLines.coInsurance.amount | String | The amount of co-insurance for the procedure performed. |
claimInformation.serviceLines.coInsurance.code | String | The code for the procedure performed. |
claimInformation.serviceLines.coInsurance.codeType | String | A code type for the procedure performed. |
claimInformation.serviceLines.coInsurance.description | String | The description of the co-insurance amount the procedure performed. |
claimInformation.serviceLines.coInsurance.procedure | String | The procedure code of the procedure performed. |
claimInformation.serviceLines.coInsurance.patientLiable | Boolean | Indicates whether the patient is liable. |
claimInformation.serviceLines.deductible | Object | An object representing the deductible portion of the procedure performed. |
claimInformation.serviceLines.deductible.amount | String | The amount of deductible for the procedure performed. |
claimInformation.serviceLines.deductible.code | String | The code for the procedure performed. |
claimInformation.serviceLines.deductible.codeType | String | A code type for the procedure performed. |
claimInformation.serviceLines.deductible.description | String | The description of the deductible amount the procedure performed. |
claimInformation.serviceLines.deductible.procedure | String | The procedure code of the procedure performed. |
claimInformation.serviceLines.deductible.patientLiable | Boolean | Indicates whether the patient is liable. |
POST /V1/INSTITUTIONAL-CLAIMS
This endpoint creates a CCE asynchronously. To submit a CCE, make a valid request and a response will be returned with a location header containing a URL you can query for your result.
RESPONSES
HTTP Status Code | Description |
---|---|
202 | The CCE was accepted for processing. Poll the URL in the Location header. The X-Status-Message header will contain additional detail. |
400 | The CCE request failed validation. It either failed our validation rules or was rejected by the health plan. The errors property will contain detailed information. Errors that specify a field are Availity validation rule failures. Errors that specify a code are from the health plan. Correct the errors and resubmit the request. |
500 | We were unable to parse your request. Correct the errors and resubmit the request. |
VALIDATION RULES
The validation rules for the InstitutionalClaim resource can vary by health plan, the type of claim being requested, and the type of service to be performed. Availity organizes these rules and makes them available through the Configuration
service. The Configuration
resource documents the fields you need to send to create a InstitutionalClaim and explains what values are valid for those fields. See the Configurations service for details.
EXAMPLES
If your request is invalid, we will respond with a status code of 400 and a list of errors for you to correct.
$ curl -i -H "x-api-key: $API_KEY" -H "Content-Type: application/json" -X POST -d '{
"requestTypeCode": "PRE_DETERMINATION",
"billingProvider": {
"npi": "1234567893",
"ein": "111222333",
"payerAssignedProviderId": "XYZ321"
},
"patient": {
"relationshipCode": "01",
"lastName": "Smith",
"firstName": "Bob",
"stateCode": "FL",
"birthDate": "1980-02-12",
"genderCode": "M"
},
"payer": {
"id": "BCBSF"
},
"submitter": {
"id": "123456789",
"lastName": "SUBMITTER"
},
"subscriber": {
"memberId": "JDH001",
"groupName": "ASDF 1-2",
"groupNumber": "12312412"
},
"claimInformation": {
"principalDiagnosis": {
"code": "S52512A",
"qualifierCode": "ABK"
},
"serviceLines": [
{
"procedureCode": "A4719",
"quantity": "1.0",
"amount": "10.00"
}
]
}
}' https://api.availity.com/demo/v1/institutional-claims
HTTP/1.1 400 Bad Request
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json
Date: Fri, 03 Jun 2016 18:19:16 GMT
x-api-id: ad4dff7e-7d54-4388-8a80-ce4227cd702a
X-Session-ID: ad4dff7e-7d54-4388-8a80-ce4227cd702a
Connection: close
{
"userMessage" : "Your request was invalid.",
"developerMessage" : "The request was invalid. See the 'errors' property for details.",
"reasonCode" : 0,
"statusCode" : 400,
"errors" : [ {
"field" : "claimInformation.facilityTypeCode",
"errorMessage" : "Enter a valid Bill Type.",
"index" : 0,
"nestedEntityErrors" : [ ]
}, {
"field" : "claimInformation.serviceLines.fromDate",
"errorMessage" : "Enter an as of date up to 24 months in the past and up to 12 months in the future.",
"index" : 0,
"nestedEntityErrors" : [ ]
}, {
"field" : "claimInformation.serviceLines.revenueCode",
"errorMessage" : "Enter a valid Revenue Code.",
"index" : 0,
"nestedEntityErrors" : [ ]
} ]
}
If your request is valid, we will respond with a status code of 202 and a location header where you can check back for your response. We will continue to respond in this way until we have heard back from the health plan.
$ curl -i -H "x-api-key: $API_KEY" -H "Content-Type: application/json" -X POST -d '{
"requestTypeCode": "PRE_DETERMINATION",
"billingProvider": {
"npi": "1234567893",
"ein": "111222333",
"payerAssignedProviderId": "XYZ321"
},
"patient": {
"relationshipCode": "01",
"lastName": "Smith",
"firstName": "Bob",
"stateCode": "FL",
"birthDate": "1980-02-12",
"genderCode": "M"
},
"payer": {
"id": "BCBSF"
},
"submitter": {
"id": "123456789",
"lastName": "JOHNSON"
},
"subscriber": {
"memberId": "JDH001",
"groupName": "ASDF 1-2",
"groupNumber": "12312412"
},
"claimInformation": {
"facilityTypeCode": "13",
"principalDiagnosis": {
"code": "S52512A",
"qualifierCode": "ABK"
},
"serviceLines": [
{
"revenueCode": "0360",
"procedureCode": "A4719",
"quantity": "1.0",
"amount": "10.00",
"fromDate": "2016-05-10"
}
]
}
}' https://api.availity.com/demo/v1/institutional-claims
->
HTTP/1.1 202 Accepted
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json;charset=utf-8
Date: Fri, 03 Jun 2016 20:00:40 GMT
Location: https://api.availity.com/demo/v1/institutional-claims/-465960752822731184
x-api-id: 893ef842-5ec0-4223-8338-ab31bdd25c90
X-Session-ID: 893ef842-5ec0-4223-8338-ab31bdd25c90
X-Status-Message: We are processing your request.
Connection: close
GET /V1/INSTITUTIONAL-CLAIMS/:ID
You can retrieve a CCE using this endpoint.
RESPONSES
HTTP Status Code | Description |
---|---|
200 | We are done processing your request and the response body contains the result. |
202 | We are currently processing your request. We may be retrying it. |
400 | Your CCE request failed validation. You can correct the errors and resubmit. |
404 | We did not find a InstitutionalClaim with the id that you sent. |
504 | We were unable to process your request. The health plan did not respond after several retry attempts. Please try your request again later. |
EXAMPLES
You can request the URI that was returned in the Location response header during from your POST request. If the resource is found but we have not received a response from the health plan, we will respond with a status code of 202 and a Location header where you can check back for your response. We will continue to respond in this way until we have heard back from the health plan.
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/institutional-claims/-465960752822731184
->
HTTP/1.1 202 Accepted
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json;charset=utf-8
Date: Mon, 06 Jun 2016 18:11:34 GMT
Location: https://api.availity.com/demo/v1/institutional-claims/-465960752822731184
x-api-id: 25a71361-7f75-4dc9-918b-021e163b0df8
X-Session-ID: 25a71361-7f75-4dc9-918b-021e163b0df8
X-Status-Message: The health plan did not respond. We are retrying the request.
Connection: close
Once we have a response from the health plan, we will respond with a status code of 200 and a InstitutionalClaim resource. This example shows what a response looks like when the health plan is unable to determine a patients liability.
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/institutional-claims/-465960752822731184
->
HTTP/1.1 200 OK
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json;charset=utf-8
Date: Mon, 06 Jun 2016 18:35:19 GMT
x-api-id: 22d78708-6094-4e95-a8fe-3bb762975fd3
X-Availity-Transaction-ID: 1613032
X-Session-ID: 22d78708-6094-4e95-a8fe-3bb762975fd3
Connection: close
Server: Jetty(8.1.17.v20150415)
{
"id" : "-5375712665050195544",
"createdDate" : "2016-07-06T14:35:07.000+0000",
"updatedDate" : "2016-07-06T14:35:08.000+0000",
"expirationDate" : "2016-07-07T14:35:07.000+0000",
"requestTypeCode" : "PRE_DETERMINATION",
"submitter" : {
"lastName" : "JOHNSON",
"id" : "123456789"
},
"payer" : {
"id" : "BCBSF"
},
"billingProvider" : {
"ein" : "111222333",
"payerAssignedProviderId" : "G1234"
},
"subscriber" : {
"memberId" : "JBTEST1",
"onHold" : false
},
"patient" : {
"lastName" : "SMITH",
"firstName" : "JOE",
"birthDate" : "1870-01-01",
"gender" : "Male",
"genderCode" : "M",
"subscriberRelationship" : "Spouse",
"subscriberRelationshipCode" : "01"
},
"claimInformation" : {
"facilityTypeCode" : "13",
"frequencyTypeCode" : "1",
"messages" : [ {
"code" : "EAPI-90386",
"description" : " Plan profile information not found"
} ],
"displayMessage" : "Unable to determine patient liability; additional information is required. For assistance, contact BCBSF",
"principalDiagnosis" : {
"qualifier" : "International Classification of Diseases Clinical Modification (ICD-10-CM) Principal Diagnosis",
"qualifierCode" : "ABK",
"code" : "G912"
}
}
}
POST /V1/DENTAL-CLAIMS
This endpoint creates a dental claim asynchronously. To submit a dental claim, make a valid request and a response will be returned with a location header containing a URL you can query for your result.
RESPONSES
HTTP Status Code | Description |
---|---|
202 | The claim was accepted for processing. Poll the URL in the Location header. The X-Status-Message header will contain additional detail. |
200 | The claim has completed processing and will be submitted to the health plan. |
400 | The claim request failed validation. It either failed our validation rules or was rejected by the health plan. The errors property will contain detailed information. Errors that specify a field are Availity validation rule failures. Errors that specify a code are from the health plan. Correct the errors and resubmit the request. |
500 | We were unable to parse your request. Correct the errors and resubmit the request. |
VALIDATION RULES
The validation rules for the DentalClaim resource can vary by health plan, the type of claim being requested, and the type of service to be performed. Availity organizes these rules and makes them available through the Configuration
service. The Configuration
resource documents the fields you need to send to create a DentalClaim and explains what values are valid for those fields. See the Configurations service for details.
EXAMPLES
If your request is invalid, we will respond with a status code of 400 and a list of errors for you to correct.
$ curl -i -H "x-api-key: $API_KEY" -H "Content-Type: application/json" -X POST -d ' {
"requestTypeCode": "CLAIM",
"submitter": {
"lastName": "AVAILITY",
"id": "111222333",
"phone": "9045556666"
},
"payer": {
"id": "00611",
"claimFilingIndicatorCode": "BL"
},
"billingProvider": {
"ein": "111222333",
"lastName": "ASDF",
"npi": "1234567893",
"addressLine1": "123 main st",
"city": "Jacksonville",
"stateCode": "FL",
"zipCode": "322231234",
"countryCode": "US",
"specialtyCode": "282N00000X"
},
"patient": {
"lastName": "smith",
"firstName": "bob",
"addressLine1": "123 main st",
"city": "Jacksonville",
"stateCode": "FL",
"zipCode": "322231234",
"genderCode": "M",
"birthDate": "2001-01-01"
},
"claimInformation": {
"diagnoses": [{
"qualifierCode": "ABK",
"code": "J3089"
}],
"providerSignatureOnFile": true,
"frequencyTypeCode": "1",
"informationReleaseCode": "I",
"placeOfServiceCode": "11",
"providerAcceptAssignmentCode": "A",
"serviceFromDate": "2016-07-22",
"serviceLines": [{
"amount": "0.01",
"diagnosisCodePointer1": "1",
"procedureCode": "D0120",
"treatmentStartDate": "2016-07-22"
}]
}
}' https://api.availity.com/demo/v1/dental-claims
HTTP/1.1 400 Bad Request
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json
Date: Fri, 14 Oct 2016 18:19:16 GMT
x-api-id: c1585584-5d6f-472e-9e8e-f4300b6f237c
X-Session-ID: c1585584-5d6f-472e-9e8e-f4300b6f237c
Connection: close
{
"userMessage": "Your request was invalid.",
"developerMessage": "The request was invalid. See the 'errors' property for details.",
"reasonCode": 0,
"statusCode": 400,
"errors": [
{
"field": "subscriber.memberId",
"errorMessage": "Enter a valid alphanumeric Member ID. Punctuation and special characters are not allowed.",
"index": 0
}
]
}
If your request is valid, we will respond with a status code of 202 and a location header where you can check back for your response. We will continue to respond in this way until we have completed processing the request.
$ curl -i -H "x-api-key: $API_KEY" -H "Content-Type: application/json" -X POST -d ' {
"requestTypeCode": "CLAIM",
"submitter": {
"lastName": "AVAILITY",
"id": "111222333",
"phone": "9045556666"
},
"payer": {
"id": "00611",
"claimFilingIndicatorCode": "BL"
},
"billingProvider": {
"ein": "111222333",
"lastName": "ASDF",
"npi": "1234567893",
"addressLine1": "123 main st",
"city": "Jacksonville",
"stateCode": "FL",
"zipCode": "322231234",
"countryCode": "US",
"specialtyCode": "282N00000X"
},
"subscriber": {
"memberId": "ABC1234"
},
"patient": {
"lastName": "smith",
"firstName": "bob",
"addressLine1": "123 main st",
"city": "Jacksonville",
"stateCode": "FL",
"zipCode": "322231234",
"genderCode": "M",
"birthDate": "2001-01-01"
},
"claimInformation": {
"diagnoses": [{
"qualifierCode": "ABK",
"code": "J3089"
}],
"providerSignatureOnFile": true,
"frequencyTypeCode": "1",
"informationReleaseCode": "I",
"placeOfServiceCode": "11",
"providerAcceptAssignmentCode": "A",
"serviceFromDate": "2016-07-22",
"serviceLines": [{
"amount": "0.01",
"diagnosisCodePointer1": "1",
"procedureCode": "D0120",
"treatmentStartDate": "2016-07-22"
}]
}
}' https://api.availity.com/demo/v1/dental-claims
->
HTTP/1.1 202 Accepted
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json;charset=utf-8
Date: Fri, 14 Oct 2016 18:20:32 GMT
Location: https://api.availity.com/demo/v1/dental-claims/12345
x-api-id: d9cf9b22-a0f6-4179-89f3-14a3909b40f7
X-Session-ID: d9cf9b22-a0f6-4179-89f3-14a3909b40f7
X-Status-Message: We are processing your request.
Connection: close
GET /V1/DENTAL-CLAIMS/:ID
You can retrieve a dental claim using this endpoint.
RESPONSES
HTTP Status Code | Description |
---|---|
200 | We are done processing your request and the response body contains the result. |
202 | We are currently processing your request. We may be retrying it. |
404 | We did not find a ProfessionalClaim with the id that you sent. |
EXAMPLES
You can request the URI that was returned in the Location response header during from your POST request. If the resource is found but we have not received a response from the health plan, we will respond with a status code of 202 and a Location header where you can check back for your response. We will continue to respond in this way until we have heard back from the health plan.
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/dental-claims/12345
->
HTTP/1.1 202 Accepted
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json;charset=utf-8
Date: Mon, 06 Jun 2016 18:11:34 GMT
Location: https://api.availity.com/demo/v1/dental-claims/12345
x-api-id: 1cea8eb0-35fa-4c32-bfa5-5aade9d46ef6
X-Session-ID: 1cea8eb0-35fa-4c32-bfa5-5aade9d46ef6
X-Status-Message: We are processing your request.
Connection: close
Once we have completed processing the dental claim we'll sumbit it to the health plan, we will respond with a status code of 200 and a resource letting you know the claim was accepted.
$ curl -H "x-api-key: $API_KEY" -X GET -i https://api.availity.com/demo/v1/professional-claims/12345
->
HTTP/1.1 200 OK
Cache-Control: private,no-store,max-age=0,must-revalidate
Content-Type: application/json;charset=utf-8
Date: Mon, 06 Jun 2016 18:35:19 GMT
x-api-id: ae25a482-1954-4725-b72b-7a686f03f27c
X-Availity-Transaction-ID: 1613032
X-Session-ID: ae25a482-1954-4725-b72b-7a686f03f27c
Connection: close
{
"links": {
"self": {
"href": "https://api.availity.com/demo/v1/dental-claims/12345"
}
},
"id": "12345",
"createdDate": "2016-10-10T12:29:19.000+0000",
"updatedDate": "2016-10-10T12:29:19.000+0000",
"expirationDate": "2016-10-11T12:29:19.000+0000",
"message": "Your claim has been accepted for processing. Check your EDI files."
}
Availity Payer List
The Availity Payer List service allows you to see which payers and transactions for each type of data submission are available to you based on your Availity contract. You can also see when changes to availability or costs are coming up.
The Resource
Parameter | Type | Description |
name | String | The common name identifying the health plan |
payerId | String | A unique identifier used to communicate with the payer |
displayName | String | The name displayed on Availity Essentials for the payer |
shortName | String | A shortened name for the payer used in the file naming convention for batch transactions. |
processingRoutes | Object | A list of the routes available for communication from Availity to the payer |
transactionDescription | String | Describes the type of transaction for the route (ex. Eligibility and Benefits) |
submissionMode | String | Describes how the data is submitted to Availity (ex. Portal, Batch). |
effectiveDate | String | The date the transaction became available. |
availability | String | Indicates whether the transaction is available to the user under their current contract or requires an additional Availity contract. Note this refers to the Availity contract not the payer. |
enrollmentRequired | Boolean | Indicates whether enrollment with Availity is required in order to submit the transaction. |
enrollmentMode | String | Indicates what type of enrollment is required with Availity (ex. Paper enrollment mode indicates additional paperwork must be submitted to the payer to complete the enrollment process). |
additionalInfo | String | Additional information about the transaction if any. |
rebateTier | String | The cost tier of the route |
passThroughRate | String | The pass through rate of the route. |
newTierNotice | String | The notice of upcoming tier change. |
gateway | String | The designation if Availity is the gateway for this payer. |
recentlyAdded | String | The date when the route was added. |
GET v1/availity-payer-list
You can search for payer information using this endpoint. The following optional parameters allow you to filter the list of payers to those or support at least one route that meets the given route filters.
Parameters
Parameter | Type | Description |
payerID | String | ID that identifies the payer at Availity (e.g. 00590) |
transactionType | String | HIPAA identifier for a transaction.
Accepted Values:
|
submissionMode | String | Describes how the data is submitted to Availity (ex. Portal, Batch).
Accepted Values:
|
enrollmentRequired | Boolean | Indicates whether enrollment with Availity is required in order to submit the transaction. |
contractRequired | String | Indicates whether an additional Availity contract is required to submit a transaction.
Accepted Values:
|