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.

Try an API:

Get an API Key

All requests to the Availity REST APIs must be authenticated with an Client ID (API Key) including demo endpoints.

Plans require verification, contracting and approval prior to use.

Get an Account

1. Sign up at Register. Enter the required information and click Create New Account at the bottom of the page.
2. Logon to the Availity Developer Portal, using the email address and password from the previous step.

Register an Application

3. Once logged in successfully, click Apps in the top menu.
4. 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.
5. Take note of your Client Secret right away. You will not see it again.

Select a Plan

6. See API Products in top menu.
7. Drill down to view specific details about API Product.
8. Select Demo Rate Plan for Mock data response and Standard Rate plan for Live data response.
9. 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:

1. 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.
2. 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.
3. 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:

1. Input validation and sanitization.
2. 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:

1. Signed up for an account on the Availity developer portal.
2. 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,client_id=your_client_id,client_secret=your_client_secret and scope=hipaa 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

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

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.

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

Supported Health Plans

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.

Payer can return the following errors:

GET /V1/COVERAGES

You can retrieve a snapshot of a member's health plan coverage by querying the coverages resource with the following parameters:

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:

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:

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" : "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",
    "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" : "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",
    "coordinationOfBenefitsDate" : "2017-01-01T00:00:00.000+0000",
    "coordinationOfBenefitsBeginDate" : "2017-01-01T00:00:00.000+0000",
    "coordinationOfBenefitsEndDate" : "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",
    "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",
    "benefitBeginDate" : "2017-01-01T00:00:00.000+0000",
    "benefitEndDate" : "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",
    "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:

The following are possible values for subscriberRelationshipCode and subscriberRelationship fields:

The following are possible values for levelCode and level fields:

The following are possible values for timePeriodCode and timePeriod fields:

The following are possible values for statusCode and status fields for plans and benefits:

The following are possible values for quantityQualifierCode and quantityQualifier fields:

The following are possible values for categoryCode and category fields for various contacts and Coverages.requestingProvider and Coverages.plans.primaryCareProvider:

The following are possible values for placeOfServiceCode and placeOfService fields:

The following are possible values for typeCode and code fields:

Note: In addition to the following list, type could also be a procedureCode.

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

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

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

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: "{}"

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

SERVICE REVIEW STATUSES

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

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

EXAMPLES

$ curl -i -X GET -i https://api.availity.com/availity/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.

RESPONSE STATUSES

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

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

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

Statuses

GET /V1/CLAIM-STATUSES

You can search the collection of claim statuses using this endpoint.

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/availity/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 -i -X GET -i https://api.availity.com/availity/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/availity/v1/claim-statuses?id=-6444806312330895858&id=-1437397854912689422"
        }
    },
    "claimStatuses": [
        {
            "links": {
                "self": {
                    "href": "https://api.availity.com/availity/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/availity/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 -i -X GET https://api.availity.com/availity/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/availity/v1/claim-statuses?q=&providers.npi=1234567893"
        }
    },
    "claimStatuses": [
        {
            "links": {
                "self": {
                    "href": "https://api.availity.com/availity/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/availity/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/availity/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/availity/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/availity/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 -i -X GET https://api.availity.com/availity/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 -i -X GET https://api.availity.com/availity/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/availity/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/availity/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 -i -X GET https://api.availity.com/availity/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 -i -X GET https://api.availity.com/availity/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 -i -X GET https://api.availity.com/availity/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/availity/v1/claim-statuses?id=-1437397854912689422
        }
    },
    "claimStatuses": [
        {
            "links": {
                "self": {
                    "href": "https://api.availity.com/availity/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 -i -X GET https://api.availity.com/availity/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/availity/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

DELETE /V1/CLAIM-STATUSES/:ID

You can delete a claim status using this endpoint.

Example

$ curl -i -X DELETE https://api.availity.com/availity/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

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: "{}"

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 -i -X GET https://api.availity.com/availity/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

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

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 "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/availity/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 "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/availity/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/availity/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

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 -i -X GET https://api.availity.com/availity/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/availity/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 -i -X GET https://api.availity.com/availity/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

{
  "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: "{}"

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 -i -X GET https://api.availity.com/availity/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

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

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 "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/availity/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 "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/availity/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/availity/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

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 -i -X GET https://api.availity.com/availity/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/availity/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 -i -X GET https://api.availity.com/availity/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

{
  "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"
    }
  }
}

Dental Claims

This resource allows you to submit dental claims for payment.

Working with the DEMO endpoints

Availity allows you to specify the type of response you want when interacting with our Dental Claims 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: "{}"

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

Configuration Service Subtype

The type name for the dental-claims service is: dental-claims Use the subtypeId name of CLAIM for settings to submit a claim, ENCOUNTER for settings to submit an encounter, or PRE_DETERMINATION to submit a pre-determination claim.

Example usage:

$ curl -i -X GET https://api.availity.com/availity/v1/configurations?type=dental-claims&payerId=BCBSF&subtypeId=CLAIM

The Resource

The following fields are under the claimInformation object - shortened for breveity