How to integrate with Availity: Essentials portal and REST APIs

A customer asks for eligibility checks, and their payers point providers to Availity. You find two products with the same name. Availity Essentials is a portal that people log into. The Availity developer portal at developer.availity.com offers REST APIs for applications. The two need different access, different credentials and different code.

Essentials and the APIs are separate

Availity describes Essentials as a multi-payer provider portal. The page lists eligibility and benefits, member ID cards, cost estimates, prior authorizations with attachments, claim status, remittance, claim submission and appeals. A person signs in with a user ID and a second factor. Automating it follows the steps in how to automate a payer portal.

The APIs use application credentials. The Availity API guide states that the REST APIs support application-only authentication with the OAuth 2.0 client credentials grant. No user logs in, and no second factor applies to API calls.

The two still connect. The Remittance Data API requires enrollment for electronic remittance advice through Availity Essentials. The provider confirms in the Essentials payer list that the REST API shows "Available" for the payer.

The developer portal home page names Availity Extend at build.availity.com as its new developer experience and says general availability begins mid-November. It says the current portal stays available for existing applications and subscriptions. The public documentation does not state how Extend changes authentication, plans or endpoints.

Which APIs exist

The HIPAA Transactions reference and the API guide list these products. Paths are relative to https://api.availity.com/availity.

API	X12 equivalent	Endpoints
Coverages 1.0.0	270/271	POST /v1/coverages, GET and DELETE /v1/coverages/{id}
Claim Statuses 1.0.0	276/277	GET /v1/claim-statuses, GET and DELETE /v1/claim-statuses/{id}
Service Reviews 2.0.0	278	POST, GET and PUT /v2/service-reviews, GET and DELETE /v2/service-reviews/{id}
Payer List 1.0.4	None	GET /availity-payer-list
Configurations 1.0.0	None	GET /v1/configurations
Patient Cost Estimator, Institutional 1.0.0	837 fields, as a predetermination	POST /v1/institutional-claims, GET /v1/institutional-claims/{id}
Remittance Data API (beta)	835	POST /remittance-data-api/v1/checks/search, claims/search, checks/details, claims/details, checks/x12

The API guide also lists Patient Cost Estimator for professional claims, Enhanced Claim Status, and add-ons named IsAuthRequired, Auth Attachments, Care Reminders and Member ID Card. The developer portal lists a Claim Attachments API. The HIPAA Transactions reference lists no endpoint for 837 claim submission.

Call the Payer List first. It filters by payerId, transactionType and enrollmentRequired, so you learn whether a payer supports a transaction before you send one. Configurations returns the field rules for a transaction type and payer, for example type=270&payerId=BCBSF.

How to get access

The getting started page gives the steps.

1. Create an account on the developer portal and set up an authenticator app for the portal login.
2. Under My Apps, create an app. You receive a client ID and a client secret.
3. Under API Products, subscribe the app to the Demo plan. Availity approves Demo subscriptions automatically.
4. For production, request the Standard plan on the developer portal and through Contact Sales. The Trading Partner Management team completes a contract, and Availity approves the subscription after it verifies the contract.

Copy the client secret when you create the app. The API guide says this is the only time you see it. A lost secret cannot be retrieved, only reset under the app's Client Secret section.

The Demo plan

The Demo plan is the sandbox. It returns canned responses that do not change with the request and contains no PHI. The API guide states that it does not allow end-to-end testing or testing with live data. It uses the same base URL as production.

Select a canned response with the X-Api-Mock-Scenario-ID header, for example Coverages-Complete-i. The response carries X-Api-Mock-Response: true. The guide notes that not all APIs support scenarios.

The API guide sets the limits per plan. Demo allows 5 transactions per second and 500 per day. Standard allows 100 per second and 100,000 per day. Token requests and polling requests count toward the limits. A 429 for the per-second limit clears after one second, and the daily limit resets at midnight UTC.

Authentication

Request a token with the client credentials grant and the hipaa scope. The API guide says the parameters are case sensitive.

POST /availity/v1/token HTTP/1.1
Host: api.availity.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET&scope=hipaa

The access token is valid for five minutes. Cache it and request a new one shortly before it expires. Token calls count against the daily limit, so request one per five minutes, not one per call.

Send a request and poll

Eligibility is asynchronous. The HIPAA Transactions reference says the coverages request body must be form encoded. It also states that Availity no longer supports GET /v1/coverages, although a sample in the API guide still shows a GET.

POST /availity/v1/coverages HTTP/1.1
Host: api.availity.com
Authorization: Bearer ACCESS_TOKEN
Accept: application/json
Content-Type: application/x-www-form-urlencoded

payerId=BCBSF&providerNpi=1234567893&memberId=XYZ123456789&patientBirthDate=1980-01-01&serviceType=30

The response carries an ID, a status and a status code. The Location header holds the full URL to poll. Status code 0 means in progress, and 4 means complete. Any other code is an error to read from the body. The API guide suggests a pause of about 2 seconds between polls. Claim Statuses returns HTTP 202 while the health plan has not answered and 504 when it does not answer in time.

The public documentation does not state a maximum time to wait for a payer response. Set your own limit per payer and record the payer and transaction for each timeout.