Frequently asked questions about working with Availity's REST APIs

An Application (App) is the link between your organization, and our authentication system and API Subscription plans.

When you create an application you are provided with a client ID and client secret for the application.  Please make note of both items, but especially the Client secret - this is the only time you will see the Client Secret.

You must supply the client ID and client secret when you call our OAuth 2 authentication API.  An authentication token will then be returned to you which is valid for 5 minutes.  Use that authentication (bearer) token to make subsequent calls to our API endpoints.

What are Availity's API subscriptions, and how do I use them?

In order to use Availity's APIs, you must subscribe to a plan from your Application.  

There are generally two types of subscriptions - A demo plan and and standard plan.

The Demo plan is the preferred starting point.  Subscribing to the Demo plan will allow access to our sandbox environment, which provides canned responses for each of the API endpoints.  Subscriptions to the Demo plan are automatically approved, so you can start testing right away.  The purpose of the Demo plan is for users to test and establish connectivity with our API endpoints, understand the flow of API calls, and generally get aquainted with our system.  You will not be able to do end-to-end testing on the Demo plan, or test with any live data.  The Documentation sections covers the scenarios provided in the Demo plan.

Once you have explored the Demo system, and wish to proceed further, you can work with your Trading Partner Manager and get your contract set up, and upgrade to the Standard Plan.  The Standared plan gives full access to the REST APIs and data.

Both subscriptions are subject to rate limits:

The Demo plan is limited to 3 transactions per second, and 500 per day.

The Standard plan is limited to 100 transactions per second, and 100,000 per day.

Why am I getting a '429' response code to all my API requests?

Each type of subscription has two different transaction limits:  a maximum allowed per second, and a maximum allowed per day.

Demo plan subscriptions are limited to a maximum of 3 transactions per second, and 500 transactions per day.

Standard plan subscriptions are limited to a maximum of 100 transactions per second, and 100,000 transactions per day.

*Please note that every REST API call is counted in your transaction limits.  This includes the OAuth token call, and each initial request and subsequent polling requests.

If you start receiving a '429' response code, you have exceeded one of the transaction limits.

If it's the per second limit, you will be able to successfully send transactions the next second.

If it's the per day limit, the counter will reset at midnight EST, and you will be able to successfully send transactions immediately the next day.

Availity does not have the capability to override these limits manually on an as needed basis.  If you are consistently exceeding your transactions limits on a standard plan, please contact your Availity Trading Partner Manager about ways to resolve this.

It is possible to test an API directly from this Developer Portal.

When looking at the details of an API you will see a table of the operations contained in the API. This will show what method they are (GET, POST, PUT, DELETE, PATCH, HEAD or OPTIONS) and what path the Resource uses.

If you click on the Resource you will see more information about it, what parameters it might take, what it returns, what possible return codes it might use and what they mean.

There is also a 'Try' button which enables you to try the Resource out direct from the Developer Portal.

If the API requires a client ID or a client secret for identification then you can specify these at the top of the 'Try' section.

What happens if I can't find my Client Secret, or can't remember it?

Your application client secret is stored as an encrypted value, so Availity cannot retrieve the unencrypted version to tell you the value if you forget it.

Solution:

You can reset the Client Secret for your App, which will update the stored value and return the new value to you.

To do that click 'Apps' in the main menu, click on the application in question and then you can click the 'Reset' link in the 'Client Secret' section.

Your new secret will be displayed at the top of the page.  Please make a note of the new Client Secret, and use the new value to Authenticate from that point on.

How do I use the various endpoints for an API in the Healthcare HIPAA Transactions product to obtain the most complete data?

Most of the APIs in the Healthcare HIPAA Transactions product follow the same pattern to obtain the complete response from the payer:  

1. Initial Request ---> 2. Initial Response ---> 3. Polling Request --> 4. Polling Response --? (repeat steps 3 and 4 until final status code)

Details:

1.  Initial request - this is the intial API request to the API endpoint containing all the parameter information needed to retreive the data.

2. Initial response - the response to your intial request contains three key pieces of information:

a. Response id - this is the unique id of your request, which is used as the 'key' to any followup requests.

b. Status - this is the description of the status of your API request

c. Status code - this is the alphanumeric status code of your API request. *Note - this is NOT the claim status code when using the Claim Status API

 Response

{
"totalCount": 1,
"count": 1,
"offset": 0,
"limit": 1,
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/coverages?payerId=101&providerNpi=xxxxxxx&asOfDate=2021-01-01&serviceType=35"
}
},
"coverages": [
{
"links": {
"self": {
"href": "https://api.availity.com/availity/v1/coverages/7276849100383928590"
}
},
"id": "7276849100383928590",
"customerId": "22032",
"status": "In Progress",
"statusCode": "0",
"createdDate": "2021-10-19T15:01:53.000+0000",
"updatedDate": "2021-10-19T15:01:53.000+0000",
"expirationDate": "2021-10-20T15:01:53.000+0000",
"etaDate": "2021-10-19T15:01:55.353+0000",
"asOfDate": "2021-01-01T05:00:00.000+0000",

The status code and description values vary sliightly by API, but they are documented in the Documentation tab on this site.  The two common status codes are '0' - In Process - your request is in process, and you'll need to perform a followup (polling) request to get the complete response from the payer, and '4' - Complete - this is the completed response from the payer.  Any other error codes indicate some form of error, and the response body should be examined for details.

If the status code is '0' - in Process on your intiial response, you will need to execute a polling request.

3. Polling request - this request uses the response id in the URL of the API endpoint (no parameters) to 'poll' the API and see if we have received the complete information from the payer.  ex: api.availity.com/availity/v1/coverages/7276849100383928590

4.  Polling response - check the status code contained in the response from the polling request.  If it indicates the response is still in process, repeat the polling request after a brief pause (2 seconds).

"id": "7276849100383928590",
"customerId": "22032",
"controlNumber": "38729508730",
"status": "Complete",
"statusCode": "4",
"createdDate": "2021-10-19T15:01:53.000+0000",
"updatedDate": "2021-10-19T15:01:53.000+0000",
"expirationDate": "2021-10-20T15:01:53.000+0000",
"asOfDate": "2021-01-01T05:00:00.000+0000",                                               

What are the valid values for the Configurations API?

The Configurations API accepts three parameters.  The table below describes the expected results with the valid values for the request parameters

type