aid: amerihealth-caritas name: AmeriHealth Caritas Rules description: >- Operational rules and Spectral-style guardrails for working with the AmeriHealth Caritas FHIR R4 Patient Access, Provider Directory, and Drug Formulary APIs. Codifies the CMS-9115-F regulatory frame, SMART on FHIR authentication, HIPAA handling, per-plan endpoint routing conventions, and read-only safety posture expected from agents and integrations. modified: '2026-05-23' rules: - id: ahc-fhir-r4-conformance name: FHIR R4 (4.0.1) Conformance description: >- All three AmeriHealth Caritas APIs (Patient Access, Provider Directory, Drug Formulary) implement HL7 FHIR 4.0.1. Discover the live supported resources, search parameters, and operations from the per-plan CapabilityStatement at `/{planCode}/{patient-api|provider-api}/metadata` before issuing any query. applies_to: - amerihealth-caritas:patient-access-api - amerihealth-caritas:provider-directory-api - amerihealth-caritas:formulary-api severity: required - id: ahc-plan-code-routing name: Per-Plan FHIR Endpoint Routing description: >- FHIR endpoints are routed per state plan via a four-digit plan code path segment on `api-ext.amerihealthcaritas.com`. Confirmed public Patient Access codes include 0100, 0500, 0900, 2400, 2600; confirmed Provider Directory codes include 0100, 0500, 0900, 1200, 2100, 2400, 2600. Pick the right plan code for the member's state plan; do not assume codes are reusable across plans. applies_to: - amerihealth-caritas:patient-access-api - amerihealth-caritas:provider-directory-api severity: required - id: ahc-smart-on-fhir-oauth name: SMART on FHIR OAuth 2.0 Authentication description: >- Patient Access requires SMART App Launch 1.0.0 / OAuth 2.0 with OIDC. Register the app on `https://developer.amerihealthcaritas.com/`, store the Client Secret only on a secured server, and use PKCE (code_challenge / code_challenge_method=S256) for mobile or single-page apps that cannot keep a secret. Authorize at `https://member.amerihealthcaritas.com/patientaccesssvc/oauth2/v1/authorize` and exchange at `https://eapics.amerihealthcaritas.com/oauth2/v1/token`. applies_to: - amerihealth-caritas:patient-access-api severity: required - id: ahc-fhir-smart-scopes name: Minimum SMART Scope Set description: >- Request only the SMART scopes the app needs. The default approved scopes are `openid`, `fhirUser`, `launch/patient`, `patient/*.read`, and `offline_access`. Avoid asking for wildcard write scopes; the Patient Access surface is read-only for members. applies_to: - amerihealth-caritas:patient-access-api severity: required - id: ahc-provider-directory-public name: Provider Directory & Formulary Are Public description: >- The Provider Directory and Drug Formulary FHIR APIs do not require OAuth. Do not attach member bearer tokens or PHI when calling these endpoints. Treat them as cache-friendly reference data sources. applies_to: - amerihealth-caritas:provider-directory-api - amerihealth-caritas:formulary-api severity: required - id: ahc-hipaa-phi-handling name: HIPAA / PHI Handling description: >- Patient Access responses contain Protected Health Information. Encrypt in transit and at rest, narrow retention windows, restrict access via least privilege, and never log raw FHIR bodies in shared observability sinks. Members can revoke consent at any time; honor revocations immediately. applies_to: - amerihealth-caritas:patient-access-api severity: required - id: ahc-read-only-posture name: Read-Only Agent Posture description: >- AmeriHealth Caritas APIs surfaced through Naftiko capabilities are read-only. Agents must not attempt POST/PUT/PATCH/DELETE against patient, claim, or coverage resources. Treat them as reporting and decision-support inputs only. applies_to: - amerihealth-caritas:patient-access-api - amerihealth-caritas:provider-directory-api - amerihealth-caritas:formulary-api severity: required - id: ahc-cms-9115-attestation name: CMS-9115-F Attestation Required description: >- Production access for Patient Access apps requires completing the AmeriHealth Caritas attestation that confirms alignment with CMS privacy and data-use expectations. Sandbox testing may proceed with the developer-portal sandbox credentials prior to attestation. applies_to: - amerihealth-caritas:patient-access-api severity: required - id: ahc-carin-pdex-uscdi-alignment name: CARIN Blue Button, Da Vinci PDex, USCDI Alignment description: >- Model Patient Access consumption against the CARIN Blue Button IG for ExplanationOfBenefit, the Da Vinci PDex IG for clinical payer-to-payer exchange, and USCDI v1 elements. The developer portal explicitly references all three guides as best-practice anchors. applies_to: - amerihealth-caritas:patient-access-api severity: recommended - id: ahc-fhir-bundle-pagination name: FHIR Bundle Pagination description: >- FHIR search responses are paginated Bundles. Follow the `next` link relation to walk full result sets; do not assume single-page responses for any clinical, claim, or directory query. applies_to: - amerihealth-caritas:patient-access-api - amerihealth-caritas:provider-directory-api severity: required - id: ahc-no-public-rate-limits name: Reasonable-Use Rate Limits description: >- AmeriHealth Caritas does not publish numeric rate limits for its FHIR APIs. Implement exponential backoff, honor `Retry-After` headers, cache public Provider Directory and Formulary responses aggressively, and pace member-token traffic conservatively. applies_to: - amerihealth-caritas:patient-access-api - amerihealth-caritas:provider-directory-api - amerihealth-caritas:formulary-api severity: recommended - id: ahc-prefer-summary-elements name: Use _summary and _elements to Limit Payload description: >- For directory and reference queries where full FHIR bodies are unnecessary, request `_summary=true` or use `_elements` to reduce payload size and downstream egress cost. applies_to: - amerihealth-caritas:provider-directory-api - amerihealth-caritas:formulary-api severity: recommended maintainers: - FN: Kin Lane email: kin@apievangelist.com