# Aetna (a CVS Health company)

> Aetna is a major U.S. health insurer and a CVS Health company. Its public API surface is a set of
> federally mandated HL7 FHIR R4 interfaces published under the CMS Interoperability and Patient
> Access Final Rule (CMS-9115-F) and the Advancing Interoperability and Improving Prior Authorization
> Final Rule (CMS-0057-F): Patient Access, Payer to Payer, Provider Directory, Provider Access, Prior
> Authorization (Da Vinci CRD / PAS / CDex) and Realtime Pharmacy Benefit Check. Everything is
> read-only GET on the surface captured here, everything requires OAuth 2.0 under SMART App Launch,
> and everything is free — Aetna publishes no API plans and no pricing.

This file was GENERATED by API Evangelist from Aetna's own published artifacts on 2026-08-30.
Aetna does not serve an llms.txt: https://www.aetna.com/llms.txt returns 404.
(https://www.cvshealth.com/llms.txt does exist and is CVS Health's, not Aetna's — it is a corporate
site map with no API content, and is deliberately not reproduced here.)

## Start here

- [Aetna Developer Portal](https://developerportal.aetna.com/): registration, API library, application
  and credential management. Angular single-page app; every route returns the same HTML shell.
- [Machine-readable API catalog](https://developerportal.aetna.com/assets/Data/Fhir.json): 139
  operations with environment, description, implementation-guide version and the filename of each
  operation's Swagger document. This is the most useful single URL on the whole surface.
- [Swagger documents](https://developerportal.aetna.com/managedcontent/yaml/): one Swagger 2.0
  document per operation, named by the `SwagerFile` field in the catalog above.
- [Previous Releases (PDF)](https://developerportal.aetna.com/managedcontent/pdfs/Previous_Releases.pdf):
  the dated changelog, Production and Sandbox sections, back to 2021-01-07.
- [Common error codes](https://eaintegrationgovernance.github.io/APIC-Common-Error-Codes.github.io/):
  the gateway error reference Aetna links from every spec's externalDocs.

## Live machine-readable endpoints

- Production FHIR base: `https://apif1.aetna.com/fhir`
- Sandbox FHIR base: `https://vteapif1.aetna.com/fhirdemo`
- [SMART configuration, production](https://apif1.aetna.com/fhir/.well-known/smart-configuration)
- [SMART configuration, sandbox](https://vteapif1.aetna.com/fhirdemo/.well-known/smart-configuration)
- [Patient Access CapabilityStatement](https://apif1.aetna.com/fhir/v2/patientaccess/metadata) — 29 resource types
- [Provider Directory CapabilityStatement](https://apif1.aetna.com/fhir/v1/providerdirectory/metadata) — 6 resource types
- Note: a subset of production products (Prior Authorization Support, CDex, CRD, Realtime Pharmacy
  Benefit Check) moved to `https://apix.cvshealth.com` on 2026-03-04 per Aetna's release notes.

## APIs

- **Patient Access API** (`/fhir/v2/patientaccess/...`) — member-authorized claims, coverage and
  clinical data. CARIN Blue Button v1.0.0/v2.0.0 + US Core 3.1.1/5.0.1/6.1.0. 40 operations captured.
- **Payer to Payer API** — the same Patient Access operations, subscribed to by another payer for
  member-directed data exchange. POST is not yet implemented (Aetna, 2025-12-05).
- **Provider Directory API** (`/fhir/v1/providerdirectory` and `/fhir/v1/providerdirectorydata`) —
  Da Vinci PDex Plan Net 1.2.0. Practitioner, PractitionerRole, Organization, OrganizationAffiliation,
  InsurancePlan, Location, HealthcareService, plus Bulk FHIR `$export`. 20 operations captured.
- **Provider Access API** (`/provideraccess/v1/Group`) — attributed member groups and bulk data export
  for treatment purposes. Da Vinci PDex STU 2.1.0 + Bulk Data Access STU 3.0.0.
- **Prior Authorization API** — Da Vinci CRD (`/coveragerequirementsdiscovery/v1/cds-services/{id}`),
  PAS (`/priorauthorizationsupport/v1/Claim/$submit`, `/$inquire`) and CDex
  (`/clinicaldataexchange/v1/$submit-attachment`).
- **Realtime Pharmacy Benefit Check API** (`/v1/realtimepharmacybenefitcheck/$process-message`) —
  prescription cost and coverage, built for California AB 2352 and Texas HB 0662H.

## Authentication

OAuth 2.0 authorization code with PKCE (S256), profiled as SMART App Launch 1.0.0.

- authorize: `https://apif1.aetna.com/fhir/prod/v1/fhirserver_auth/oauth2/authorize`
- token: `https://apif1.aetna.com/fhir/prod/v1/fhirserver_auth/oauth2/token`
- client auth: `client_secret_basic`
- scopes: `openid fhirUser profile launch/patient patient/*.read`, plus per-resource
  `patient/{Resource}.read` and `patient/{Resource}.*`
- The provider directory is NOT anonymous — it also requires OAuth.
- An application must be SUBSCRIBED in the portal to the product containing an API, or the call 401s.

## Calling conventions

- Send `Accept: application/json` — Aetna declares `application/json`, not `application/fhir+json`.
- Paginate by following `Bundle.link` where `relation == "next"`; `_page_token` is opaque and
  server-issued. Some directory operations use a numeric `page` instead.
- Unknown query parameters are rejected with 400 — only send parameters the CapabilityStatement lists.
- Errors are FHIR `OperationOutcome` (not RFC 9457 problem+json). 429 means source-IP throttling; no
  `Retry-After` and no `RateLimit-*` headers are published, so choose your own backoff.
- `x-clientrefid` is an optional correlation UUID, declared only on the `/v1/providerdirectorydata` family.

## What Aetna does not publish

- No llms.txt, no `/.well-known/security.txt`, no OIDC discovery document, no `/.well-known/api-catalog`.
- No A2A agent card and no MCP server (probed 2026-08-30, 404 on every host).
- No SDKs, no CLI, no Postman collection, no public GitHub repositories.
- No status page, no SLA, no numeric rate limits, no pricing or plans.
- No webhooks, no events, no AsyncAPI. Integration is poll-only.

## API Evangelist artifacts for Aetna

- [apis.yml](https://raw.githubusercontent.com/api-evangelist/aetna/refs/heads/main/apis.yml)
- Assembled OpenAPI 3.0.3: `openapi/aetna-patient-access-api-openapi.yml`,
  `openapi/aetna-provider-directory-api-openapi.yml`, `openapi/aetna-patient-access-api-sandbox-openapi.yml`
- Aetna's unmodified Swagger 2.0 sources: `openapi/_original/` (95 documents)
- FHIR CapabilityStatements: `fhir/`
- `authentication/`, `scopes/`, `conformance/`, `conventions/`, `errors/`, `lifecycle/`,
  `changelog/`, `sandbox/`, `data-model/`, `rate-limits/`, `plans/`, `packages/`, `well-known/`,
  `mcp/`, `skills/`, `examples/`