# Availity

> Availity is a US healthcare information network and clearinghouse. Its public REST APIs wrap ASC
> X12N HIPAA EDI transactions — eligibility and benefits (270/271), claim status (276/277), prior
> authorization / service reviews (278), claim attachments (275), dental and professional claim
> predeterminations, and patient cost estimation — across every major health plan nationwide.
> Authentication is OAuth 2.0 client credentials with a 300-second token; production access is
> gated by a signed trading-partner agreement and a BAA. Availity publishes eleven first-party
> Swagger 2.0 documents from its developer portal; it publishes no llms.txt, no MCP server, no
> A2A agent card, no AsyncAPI and no webhooks.

Generated by API Evangelist on 2026-08-15 from the API Evangelist catalog entry for Availity and
the artifacts in https://github.com/api-evangelist/availity. Availity does not serve an llms.txt of
its own: https://developer.availity.com/llms.txt returns HTTP 200 but the body is the developer
portal's single-page-app shell, the same 10,700-byte HTML the portal returns for every path that
does not exist.

## Getting started

- [Availity Developer Portal](https://developer.availity.com/): register, create an organization, register an application, subscribe to a product and plan.
- [Getting Started](https://developer.availity.com/partner/gettingstarted): account, MFA, organization, application, subscription.
- [Availity API Guide](https://developer.availity.com/blog/2025/3/25/availity-api-guide): the authoritative cross-cutting reference — authentication, status codes, error envelope, pagination, headers, demo environment.
- [Healthcare HIPAA Transactions product](https://developer.availity.com/portal/catalogue-products/healthcare-hipaa-transactions-1): the product page carrying the machine-readable Swagger documents and the Standard plan quota.
- [Contact / support](https://developer.availity.com/partner/contact-us)

## Authentication

- Flow: OAuth 2.0 Client Credentials Grant, application-only. There is no user identity layer and no OIDC discovery document.
- Token endpoint: `POST https://api.availity.com/v1/token`, `application/x-www-form-urlencoded`, parameters `grant_type=client_credentials`, `client_id`, `client_secret`, `scope`. Parameter names and values are case sensitive.
- Token lifetime: 300 seconds. No refresh token — re-run the grant.
- Call pattern: `Authorization: Bearer <access_token>` over HTTPS only.
- Scopes are not permission verbs. They are a product identifier plus a plan identifier, sent space-separated, e.g. `healthcare-hipaa-transactions healthcare-hipaa-transactions-demo`.
- Profile: [authentication/availity-authentication.yml](https://github.com/api-evangelist/availity/blob/main/authentication/availity-authentication.yml) · [scopes/availity-scopes.yml](https://github.com/api-evangelist/availity/blob/main/scopes/availity-scopes.yml)

## APIs

Base host `https://api.availity.com`. All eleven documents below are Availity's own published
Swagger 2.0, harvested verbatim.

- Coverages — eligibility and benefits, X12 270/271. `POST /v1/coverages` (createCoverage), `GET /v1/coverages/{id}` (getCoverageById), `DELETE /v1/coverages/{id}` (deleteCoverageById).
- Claim Statuses — X12 276/277. `POST /v1/claim-statuses` (findClaimStatus), `GET /v1/claim-statuses/{id}` (getClaimStatusById).
- Service Reviews — prior authorization, X12 278. `GET|POST|PUT /v2/service-reviews` (findServiceReviews, createServiceReview, updateServiceReview), `DELETE /v2/service-reviews/{id}` (voidServiceReview), `GET /v2/service-reviews/{id}` (getServiceReviewById).
- Payer List — `GET /v1/availity-payer-list` (getCustomPayerList): which payers support which transactions under your contract.
- AWS Payer List — the same operation on a separately-subscribed product at `/epdm-payer-list-aws/v1`.
- Configurations — `GET /v1/configurations` (findConfigurations): payer-specific field requirements and validation rules. Call this BEFORE submitting.
- Patient Cost Estimator 1.0.0 Institutional — `POST /v1/institutional-claims` (createInstitutionalClaim), `GET /v1/institutional-claims/{id}` (getInstitutionalClaim).
- Patient Cost Estimator 1.0.0 Professional — `POST /v1/professional-claims` (createProfessionalClaim), `GET /v1/professional-claims/{id}` (getProfessionalClaim).
- Patient Cost Estimator 2.0.0 Professional — `POST /v2/patient-cost-estimates/prof` (submitProfPredetermination), `GET /v2/patient-cost-estimates/prof/{id}` (getProfessionalClaim).
- Dental Claims — `POST /v1/dental-claims` (createDentalClaim), `GET /v1/dental-claims/{id}` (getDentalClaim).
- Dfs — `GET /sdk/v1/dfs/{id}` (download): retrieve a stored file via an encrypted URL.

A SOAP surface conforming to the CAQH CORE connectivity rule is offered alongside REST for Claim
Statuses, Dental Claims, Service Reviews and Care Cost Estimator.

## How to call it correctly

- ASYNC: most writes answer `202 Accepted` with a `Location` header. The follow-up GET ALSO answers `202` while the payer response is pending, and `200` when it is ready. Treat `202` on the poll as "not finished", never as success. This is the most common integration bug against Availity.
- NO IDEMPOTENCY KEY: Availity publishes no idempotency header. Do not blind-retry a submit — re-poll the same id. On `504 Gateway Timeout` specifically, re-poll rather than re-submit, or you risk duplicate adjudication.
- Pagination: `offset` (min 0, default 0) and `limit` (min 1, max 50, default 50). Response carries `links`, `offset`, `limit`, `count`, `totalCount` and an array named for the PLURAL RESOURCE (`payers`, `coverages`, `claimStatuses`) — not `data` or `results`. Unavailable link relations are `null`, not omitted.
- Errors: a custom envelope `{statusCode, reasonCode, userMessage, developerMessage, url, errors[]}` served as `application/json`. This is NOT RFC 9457 problem+json.
- Rate limits: Standard plan 100,000 calls/day and 100 calls/second; AWS Payer List Standard 1,000,000 calls/day and 100 calls/second. Exhaustion is `429`. NO rate-limit response headers and no documented `Retry-After` — back off blind with jitter.
- Tracing: quote the `X-Availity-Transaction-ID` response header on any support ticket.
- Rendering: response contextual encoding is OPT-IN via `X-Response-Encoding-Context`. Escape PHI yourself before putting it in a page.

## Testing

- The Demo environment is free, self-serve and PHI-free, selected by requesting the `-demo` plan scope. Same host, same token format as production.
- Send `X-Api-Mock-Scenario-ID` to choose a canned scenario; assert `X-Api-Mock-Response: true` on every response to prove you are not hitting live payers.
- Details: [sandbox/availity-sandbox.yml](https://github.com/api-evangelist/availity/blob/main/sandbox/availity-sandbox.yml)

## SDKs and packages

Availity's npm estate under `@availity` is browser/portal tooling — axios wrappers, session and
analytics plumbing, resumable upload, form validation, and the Availity Element design system. There
is NO first-party server-side SDK for these REST APIs in any language; the API Guide teaches raw
cURL. See [packages/availity-packages.yml](https://github.com/api-evangelist/availity/blob/main/packages/availity-packages.yml).

## Machine-readable artifacts

- OpenAPI (Availity's own Swagger 2.0, verbatim): https://github.com/api-evangelist/availity/tree/main/openapi/_harvested
- Authentication: https://github.com/api-evangelist/availity/blob/main/authentication/availity-authentication.yml
- OAuth scopes: https://github.com/api-evangelist/availity/blob/main/scopes/availity-scopes.yml
- Conventions: https://github.com/api-evangelist/availity/blob/main/conventions/availity-conventions.yml
- Errors: https://github.com/api-evangelist/availity/blob/main/errors/availity-problem-types.yml
- Rate limits: https://github.com/api-evangelist/availity/blob/main/rate-limits/availity-rate-limits.yml
- Plans: https://github.com/api-evangelist/availity/blob/main/plans/availity-plans-pricing.yml
- Lifecycle: https://github.com/api-evangelist/availity/blob/main/lifecycle/availity-lifecycle.yml
- Conformance: https://github.com/api-evangelist/availity/blob/main/conformance/availity-conformance.yml
- Data model: https://github.com/api-evangelist/availity/blob/main/data-model/availity-data-model.yml
- Agent skills: https://github.com/api-evangelist/availity/tree/main/skills
- Arazzo workflows: https://github.com/api-evangelist/availity/tree/main/arazzo
- Candidate MCP tool surface (no server exists): https://github.com/api-evangelist/availity/blob/main/mcp/availity-mcp.yml

## What Availity does not publish

- No llms.txt, no /.well-known documents on any host, no security.txt.
- No MCP server, no A2A agent card, no agentic access guidance.
- No AsyncAPI and no webhooks — the asynchronous model is HTTP polling.
- No FHIR surface on the public developer portal.
- No public status page content (status.availity.com exists but requires a login), no SLA, no deprecation policy, no Sunset/Deprecation headers, no dated API changelog.
- No public trust center, no published SOC 2 / HITRUST / ISO certificate, no vulnerability disclosure policy or bug bounty.