Introduction

Scope

The purpose of this Availity API Guide is to communicate product overviews, documentation, and additional information about using Availity's REST APIs to build a custom healthcare data exchange application.

Overview

Availity, LLC, is a market leader in secure healthcare data exchange. The Availity® Health Information Network is operationally HIPAA compliant, accepting and processing in a secure environment all American National Standards Institute (ANSI) Accredited Standards Committee (ASC) X12N standard transactions mandated by the Health Insurance Portability and Accountability Act (HIPAA).

Availity's real-time REST APIs allow developers to write compelling healthcare applications with connectivity to every health plan nationwide and access to more than 8.8 million daily healthcare transactions. Your application can reach more than a million providers with robust tools that simplify transactions and translate complex data responses.

Benefits

Building your application with Availity's REST APIs offers the following benefits:

• Predictable, resource-oriented URLs that return JSON and XML representations, including errors using HTTP response codes.
• Trusted security through OAuth2, SHA256, or MD5 over HTTPS.
• Standard responses to HIPAA inquiries for eligibility, claim status, claim predeterminations, and other transactions.
• Web calls for real-time responses.
• Comprehensive documentation, including authentication and coding examples with sample responses.
• Ability to register online and get an API key to get started right away.

Supported EDI transactions

The table displays information about the healthcare electronic data interchange (EDI), also called HIPAA, transactions Availity supports.

Availity-supported HIPAA transactions

Rules for format, content, and data element values for each transaction are listed in the individual ASC X12 Technical Report Type 3 (TR3) implementation guides. For a cost, you can obtain TR3s from the publisher, Washington Publishing Company (WPC) (http://www.wpc-edi.com/). WPC offers implementation guides for each transaction type in a regular version and a combined version, which contains the addenda.

Notes on documentation in this guide

"createdDate": "2014-06-16T18:38:12.000+0000"
        
Text Copied!

Authentication

Availity REST APIs support the application-only authentication method, which is based on the Client Credentials Grant flow of the OAuth 2.0 spec. All Availity REST APIs support OAuth 2.0 over HTTPS for authentication, including requests to demo resources.

To make a REST API request to Availity, you must first follow the steps listed in the Get Started section. After you have created your API account, registered your application, and subscribed to an API product, you must take two steps to make an initial API request:

1. Get an OAuth 2.0 access token.

   Make a POST request to the Availity Partner OAuth2 Provider 1.0.0 API (endpoint: POST/v1/token). This request returns a response that contains an access_token, token_type, and expiration_time. The access token is only valid for five minutes:

   Token Request:

   curl -i -X POST "https://api.availity.com/v1/token" \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -d "grant_type=client_credentials&scope=$SCOPE_PERMISSION&client_id=$API_KEY&client_secret=$CLIENT_SECRET"
   Text Copied!

   Response Header:

   HTTP/2 200
   date: Tue, 28 Oct 2025 10:32:06 GMT
   content-type: application/json
   content-length: 860
   x-forgerock-transactionid: c1eb6d43-7422-496f-8bba-07e202686d8f
   x-tyk-trace-id: 3923b3a3f95b68349438482e99bf4e6b
   Text Copied!

   Token Response:

   {
   "access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjF2em5DYVZPMHNSZlRpV3htdU5yT1NaV2hQWSIsInR5cCI6IkpXVCJ9.eyJl...",
   "consented_on":1761647526,
   "expires_in":300,
   "scope":"$SCOPE_PERMISSION",
   "token_type":"Bearer"
   }
   Text Copied!

   Note: The request body parameters are case sensitive. Make sure grant_type=client_credentials, client_id=your_api_key, client_secret=your_client_secret, and scope=$SCOPE_PERMISSION match exactly as they are shown.

   • Enter the two scopes separated by single space.
   • Please refer to the image below for a better understanding.

   Access and Credentials Info:

   

   Scope Permission:

   

---

2. Call the API with the access token.

   Use the access token from Step #1 to make a request to an Availity REST API. The example below illustrates making a request to the Availity Payer List resource and includes the Availity demo endpoints.

   Sample Request:

   curl -i -X GET "https://api.availity.com/v1/availity-payer-list" \
   -H "Authorization: Bearer $ACCESS_TOKEN"
   Text Copied!

   Sample Response:

   {
       "totalCount": 1000,
       "count": 2,
       "offset": 0,
       "limit": 2,
       "payers": [
           {
               "name": "PAYER_ALPHA",
               "payerId": "PAY000001",
               "displayName": "INSURANCE TYPE A",
               "processingRoutes": [
                   {
                       "transactionDescription": "Professional Claims",
                       "submissionMode": "Batch",
                       "effectiveDate": "2025-01-01T00:00:00.000+00:00",
                       "availability": "Available",
                       "enrollmentRequired": false
                   },
                   {
                       "transactionDescription": "Facility Claims",
                       "submissionMode": "Portal",
                       "effectiveDate": "2025-01-01T00:00:00.000+00:00",
                       "availability": "Available",
                       "enrollmentRequired": true
                   }
               ]
           },
           {
               "name": "PAYER_BETA",
               "payerId": "PAY000002",
               "displayName": "INSURANCE TYPE B",
               "processingRoutes": [
                   {
                       "transactionDescription": "Pharmacy Claims",
                       "submissionMode": "EDI",
                       "effectiveDate": "2025-02-15T12:00:00.000+00:00",
                       "availability": "Pending",
                       "enrollmentRequired": false
                   },
                   {
                       "transactionDescription": "Dental Claims",
                       "submissionMode": "Portal",
                       "effectiveDate": "2025-02-15T12:00:00.000+00:00",
                       "availability": "Available",
                       "enrollmentRequired": true
                   }
               ]
           }
       ]
   }
   Text Copied!

curl -X "GET" "https://api.availity.com/v2/service-reviews" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Response-Encoding-Context: HTML"

Text Copied!

{
    "userMessage": "This system had an internal error.",
    "developerMessage": "API client account information missing for ApiKey ( 936108d4-e911-4bec-b3aa-b3ce1cfdfb3a )",
    "reasonCode": 0,
    "statusCode": 500
}

Text Copied!

{
    "userMessage": "This system had an internal error.",
    "developerMessage": "API client account information missing for ApiKey ( 936108d4-e911-4bec-b3aa-b3ce1cfdfb3a )",
    "reasonCode": 0,
    "statusCode": 500
}

Text Copied!

Collection resources

If you need to interact with multiple resources at once, you must do so with a collection resource. A collection is a first-class resource that contains additional resources and supports pagination, sorting, and searching.

Collection resource response fields

Pagination

When a collection resource contains a large number of resource instances, all of them may not be included in a single response. Instead, pagination breaks up the results into one or more pages of data. You can request additional pages as separate requests. Here's an example of a collection resource partial response:

Sample Request:

curl -i -X GET "https://api.availity.com/v1/availity-payer-list?offset=10&limit=2" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Text Copied!

Sample Response:

{
    "totalCount": 9999,
    "count": 2,
    "offset": 0,
    "limit": 2,
    "payers": [
        {
            "name": "PAYER_ALPHA",
            "payerId": "PAY000001",
            "displayName": "INSURANCE TYPE A",
            "processingRoutes": [
                {
                    "transactionDescription": "Professional Claims",
                    "submissionMode": "Batch",
                    "effectiveDate": "2025-01-01T00:00:00.000+00:00",
                    "availability": "Available",
                    "enrollmentRequired": false
                },
                {
                    "transactionDescription": "Facility Claims",
                    "submissionMode": "Portal",
                    "effectiveDate": "2025-01-01T00:00:00.000+00:00",
                    "availability": "Available",
                    "enrollmentRequired": true
                }
            ]
        },
        {
            "name": "PAYER_BETA",
            "payerId": "PAY000002",
            "displayName": "INSURANCE TYPE B",
            "processingRoutes": [
                {
                    "transactionDescription": "Pharmacy Claims",
                    "submissionMode": "EDI",
                    "effectiveDate": "2025-02-15T12:00:00.000+00:00",
                    "availability": "Pending",
                    "enrollmentRequired": false
                },
                {
                    "transactionDescription": "Dental Claims",
                    "submissionMode": "Portal",
                    "effectiveDate": "2025-02-15T12:00:00.000+00:00",
                    "availability": "Available",
                    "enrollmentRequired": true
                }
            ]
        }
    ]
}
Text Copied!

Query parameters

Availity APIs use cursor-based pagination with two optional query parameters:

• 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 field contains link relations depending on the page and the number of resources returned. When a link relation is not available, you will receive a null value when trying to access it.

Assume the API response contains a total of 102 records, with offset=10 and limit=2 (meaning the response returns 2 records starting from the 10th record).

{
"userMessage": "The requested resource does not exist.",
"developerMessage": "The requested resource does not exist. Please check that you're using the proper resource ID.",
"reasonCode": 0,
"statusCode": 404
}
Text Copied!

Demo services

Availity offers a trial package that allows you to begin exploring our APIs without completing a formal application process. Using demo data (without personal health information [PHI]), you'll get up to speed quickly, at no cost to you.

You can choose which demo response you want by sending a header with X-Api-Mock-Scenario-ID in your request. The value is the ID of the response scenario you want. For demo response confirmation, inspect the response header for X-Api-Mock-Response: true. You can find supported response scenarios in each applicable API's reference section.

Note: Not all Availity APIs support demo response scenarios.

Note:The Demo environment returns canned responses; therefore, the data you receive does not change based on the request.

Refer to the Get Started section for instructions on subscribing to the Demo environment.

Contact information

Availity Client Services

For questions, assistance, and support, log in to Availity Essentials and submit an online support ticket (24/7) by navigating to Help & Training > Availity Support on Availity Essentials.

Days of operation: Monday through Friday