Supergood | Surescripts API
Programmatically access e-prescribing, real-time prescription benefit (RTPB), medication history, and electronic prior authorization (ePA) workflows in Surescripts with a stable REST API. Supergood builds and operates production-grade, unofficial Surescripts integrations so your team can automate prescribing, coverage checks, and prior auth pipelines without heavy custom engineering.
Surescripts is a nationwide health information network used by providers, pharmacies, PBMs, and health plans to route prescriptions, retrieve medication histories, check formularies and costs, and process prior authorizations. With an unofficial API, you could send and cancel e-prescriptions, run real-time benefit checks, submit and track ePAs, receive fill notifications, and synchronize medication history into your EHR, practice management, or billing stack.
If you’re a clinic, provider group, or revenue cycle team, integrating your tech stack with Surescripts unlocks concrete data flows and features:
- Pull: Patient medication histories, RTPB coverage and cost results, ePA statuses and question sets, pharmacy fill notifications (RxFill), prescriber and pharmacy directory metadata
- Push: New e-prescriptions, CancelRx and RxChange messages, ePA submissions with attachments, formulary-aware alternatives, updated patient demographics
- Build: Cost transparency at the point of care, automated prior authorization initiation and tracking, adherence workflows using fill data, billing rules aligned to coverage and prior auth statuses
What is Surescripts?
Surescripts provides the e-prescribing and clinical interoperability rails that connect prescribers, pharmacies, PBMs, and health plans across the United States. Through standardized messaging and services, Surescripts enables prescribers to transmit prescriptions electronically, access medication histories, check patient-specific coverage and costs in real time, and complete electronic prior authorizations.
Core product areas include:
- E-Prescribing (NewRx, RxChange, CancelRx, RxFill notifications)
- Real-Time Prescription Benefit (patient-specific formulary, copay, alternatives)
- Medication History (dispense records from pharmacies and PBMs)
- Electronic Prior Authorization (ePA for specialty and traditional medications)
- Provider and Pharmacy Directory services
Common data entities:
- Patients (demographics, identifiers, coverage)
- Prescribers (NPI, DEA, practice locations)
- Pharmacies (NCPDP ID, location, services)
- Prescriptions (drug, SIG, quantity, refills, DAW/substitution)
- Medication History entries (dispense dates, NDC/RxNorm, quantity, days supply)
- Benefit/Formulary results (copays, restrictions, alternatives)
- Prior Authorizations (status, questions, attachments, payer/PBM)
- Messages/Transactions (NCPDP SCRIPT types and delivery statuses)
The Surescripts Integration Challenge
Organizations rely on Surescripts daily, but turning portal- and network-based workflows into automated pipelines is hard:
- Standards complexity: NCPDP SCRIPT versions, RTPB nuances, payer- and PBM-specific formulary rules, and evolving ePA question sets
- Strong enterprise security: SSO/MFA and network controls complicate headless automation
- Mixed delivery channels: Some events are real-time (e.g., NewRx), others are asynchronous (e.g., RxFill, ePA updates) or delivered via exports
- Compliance and auditability: CancelRx and RxChange require precise audit trails, and PHI access must align to licensure, role, and consent
- Entitlements and certification: Access depends on organizational licensing and the specific Surescripts services you’re entitled to use
How Supergood Creates Surescripts APIs
Supergood reverse-engineers authenticated browser flows, standards-based messaging, and batch interfaces to deliver a resilient API endpoint layer.
- Handles username/password, SSO/OAuth, and MFA (SMS, email, TOTP) securely
- Maintains session continuity with automated refresh and change detection
- Normalizes NCPDP SCRIPT, medication history, RTPB, and ePA objects into consistent JSON
- Aligns with customer entitlements and licensing constraints to ensure compliant access
- Bridges asynchronous events and batch artifacts with signed URL retrieval and delivery
Use Cases
EHR-to-Pharmacy E-Prescribing
- Push NewRx from your EHR into the patient’s preferred pharmacy
- Manage CancelRx and RxChange with clear audit trails
- Maintain consistent patient demographics and prescriber credentials
Benefit, Eligibility, and Cost Transparency
- Run RTPB to display patient-specific copays and restrictions at order entry
- Suggest covered alternatives with lower out-of-pocket costs
- Reduce rework and claim denials tied to step therapy or prior auth requirements
Prior Authorization Automation
- Submit ePA requests directly and track statuses
- Pre-fill clinical questions from the chart; attach labs or notes
- Notify staff when approvals arrive to release prescriptions promptly
Medication History and Adherence
- Pull medication dispense history to verify adherence and reconcile lists
- Use RxFill events to drive outreach for non-adherence or failed fills
- Support care plans and billing rules linked to medication compliance
Audit and Compliance
- Export complete message logs for NewRx, CancelRx, and RxChange
- Preserve evidence of coverage checks and ePA decisions
- Maintain machine-readable audit trails aligned to organizational policies
Available Endpoints
Authentication
POST /sessions: Establish a session using credentials. Supergood manages MFA (SMS, email, TOTP) and SSO/OAuth when enabled. Returns a short-lived auth token maintained by the platform.
curl --request POST \
--url https://api.supergood.ai/integrations/<integration_id>/sessions \
--header 'Authorization: Basic <Base64 encoded token>' \
--header 'Content-Type: application/json' \
--data '{
"username": "[email protected]",
"password": "<password>",
"mfa": {
"type": "totp",
"code": "123456"
}
}'
Example response
{
"authToken": "eyJhbGciOi...",
"expiresIn": 3600,
"user": {
"id": "u_71de9a",
"name": "Prescribing Admin",
"entitlements": ["erx", "rtpb", "med_history", "epa"]
}
}
Medication History
GET /patients/{patientId}/medication-history: Retrieve dispensed medications for a patient from connected pharmacies/PBMs. Use this to reconcile medication lists and drive adherence workflows.
Query parameters
- rangeStart: ISO 8601 date
- rangeEnd: ISO 8601 date
- pharmacyNcpdpId: string (optional filter)
Example response
{
"items": [
{
"entryId": "mh_4f91c2",
"drugName": "Atorvastatin 20 mg",
"rxNorm": "617314",
"ndc": "00093-7424-56",
"dispenseDate": "2026-01-10",
"quantity": 30,
"daysSupply": 30,
"sig": "Take 1 tablet by mouth once daily",
"prescriberNpi": "1234567890",
"pharmacyNcpdpId": "1234567",
"fillStatus": "filled"
},
{
"entryId": "mh_7b21d0",
"drugName": "Metformin 500 mg",
"rxNorm": "860975",
"ndc": "54868-5677-00",
"dispenseDate": "2025-12-15",
"quantity": 60,
"daysSupply": 30,
"sig": "Take 1 tablet by mouth twice daily",
"prescriberNpi": "1234567890",
"pharmacyNcpdpId": "1234567",
"fillStatus": "partial"
}
],
"page": 1,
"pageSize": 50,
"total": 2
}
E-Prescriptions
POST /e-prescriptions: Create and transmit a NewRx message to the selected pharmacy. Supports DAW/substitution flags, notes, and reference IDs for EHR cross-linking.
curl --request POST \
--url https://api.supergood.ai/integrations/<integration_id>/e-prescriptions \
--header 'Authorization: Bearer <authToken>' \
--header 'Content-Type: application/json' \
--data '{
"patient": {
"id": "pt_9aa231",
"name": "Jordan Patel",
"dob": "1982-07-22",
"sex": "M",
"identifiers": {
"memberId": "M123456",
"bin": "012345",
"pcn": "987654",
"group": "ACMEPLAN"
}
},
"prescriber": {
"npi": "1234567890",
"dea": "AB1234567",
"practice": "Downtown Clinic",
"address": {
"line1": "100 Health Way",
"city": "Columbus",
"region": "OH",
"postalCode": "43215"
}
},
"pharmacy": {
"ncpdpId": "1234567",
"name": "Main Street Pharmacy"
},
"medication": {
"drugName": "Atorvastatin 20 mg",
"rxNorm": "617314",
"ndc": "00093-7424-56",
"quantity": 30,
"daysSupply": 30,
"refills": 2,
"daw": false,
"sig": "Take 1 tablet by mouth once daily"
},
"notes": "Patient prefers 90-day supply if covered.",
"referenceId": "ehr-order-8241"
}'
Example response
{
"erxId": "erx_58d3e0",
"status": "queued",
"messageType": "NewRx",
"pharmacyNcpdpId": "1234567",
"createdAt": "2026-01-19T15:02:02Z",
"referenceId": "ehr-order-8241"
}
Real-Time Prescription Benefit
POST /benefits/rtpb: Request patient-specific coverage, copay, and alternatives for a proposed medication and pharmacy. Use this to present cost and coverage at order entry.
curl --request POST \
--url https://api.supergood.ai/integrations/<integration_id>/benefits/rtpb \
--header 'Authorization: Bearer <authToken>' \
--header 'Content-Type: application/json' \
--data '{
"patient": {
"id": "pt_9aa231",
"identifiers": {"memberId": "M123456", "bin": "012345", "pcn": "987654", "group": "ACMEPLAN"}
},
"pharmacy": {"ncpdpId": "1234567"},
"candidate": {
"rxNorm": "617314",
"drugName": "Atorvastatin 20 mg",
"quantity": 30,
"daysSupply": 30
}
}'
Example response
{
"candidate": {
"drugName": "Atorvastatin 20 mg",
"copay": 10.0,
"priorAuthRequired": false,
"stepTherapy": false,
"quantityLimit": null
},
"alternatives": [
{"drugName": "Atorvastatin 40 mg", "copay": 12.0, "priorAuthRequired": false, "stepTherapy": false},
{"drugName": "Rosuvastatin 10 mg", "copay": 8.0, "priorAuthRequired": true, "stepTherapy": true}
],
"pharmacy": {"ncpdpId": "1234567", "inNetwork": true},
"payer": {"id": "pbm_acme", "name": "ACME PBM"},
"requestedAt": "2026-01-19T15:10:33Z"
}
Prior Authorizations
POST /prior-authorizations: Create an ePA request referencing a proposed prescription. Include diagnosis codes and optional attachments.
curl --request POST \
--url https://api.supergood.ai/integrations/<integration_id>/prior-authorizations \
--header 'Authorization: Bearer <authToken>' \
--header 'Content-Type: application/json' \
--data '{
"patientId": "pt_9aa231",
"prescriberNpi": "1234567890",
"payerId": "pbm_acme",
"medication": {"rxNorm": "617314", "drugName": "Rosuvastatin 10 mg"},
"diagnoses": ["E78.5"],
"clinicalAnswers": {"statinIntolerance": true, "triedAndFailed": ["Atorvastatin"]},
"attachments": [{"type": "labs", "url": "https://download.example/signed/abc123"}],
"referenceId": "ehr-epa-9912"
}'
Example response
{
"paId": "pa_71af2b",
"status": "submitted",
"createdAt": "2026-01-19T16:05:42Z",
"nextSteps": ["await_payer_questions"],
"reviewUrl": "https://download.surescripts.example/signed/def456...",
"referenceId": "ehr-epa-9912"
}
GET /prior-authorizations: List ePA requests with filters for status, patient, and payer.
Query parameters
- status: string (submitted, pending_questions, approved, denied)
- patientId: string
- payerId: string
Example response
{
"items": [
{"paId": "pa_71af2b", "status": "submitted", "patientId": "pt_9aa231", "payerId": "pbm_acme", "drugName": "Rosuvastatin 10 mg", "createdAt": "2026-01-19T16:05:42Z"}
],
"page": 1,
"pageSize": 50,
"total": 1
}
Technical Specifications
- Authentication: Username/password with MFA (SMS, email, TOTP) and SSO/OAuth where enabled; supports service accounts or customer-managed credentials
- Response format: JSON with consistent resource schemas and pagination
- Rate limits: Tuned for enterprise throughput while honoring licensing and usage controls
- Session management: Automatic reauth and cookie/session rotation with health checks
- Data freshness: Near real-time retrieval of eRx, RTPB, ePA, and medication history artifacts
- Security: Encrypted transport, scoped tokens, and audit logging; respects Surescripts entitlements and compliance requirements
- Webhooks: Optional asynchronous delivery for RxFill updates, ePA status changes, and pharmacy acknowledgments
Performance Characteristics
- Latency: Sub-second responses for list/detail queries under normal load
- Throughput: Designed for high-volume e-prescribing and prior auth pipelines
- Reliability: Retry logic, backoff, and idempotency keys minimize duplicate actions
- Adaptation: Continuous monitoring for UI/API changes with rapid adapter updates
Getting Started
- Schedule Integration Assessment
Book a 30-minute session to confirm your Surescripts service mix, licensing, and authentication model.
- Supergood Builds and Validates Your API
We deliver a hardened Surescripts adapter tailored to your workflows and entitlements.
- Deploy with Monitoring
Go live with continuous monitoring and automatic adjustments as Surescripts evolves.
Frequently Asked Questions
Q: Which Surescripts services can this integration cover?
Supergood supports workflows across commonly used Surescripts offerings, subject to your licensing and entitlements. We scope coverage (e.g., NewRx, CancelRx, RxFill, RTPB, Medication History, ePA) during integration assessment.
Q: How are MFA, SSO, and asynchronous events handled for automation?
We support username/password + MFA (SMS, email, TOTP) and can operate behind SSO/OAuth when enabled. For asynchronous flows, we provide webhooks, signed URL retrieval, and reliable polling to consolidate statuses and artifacts.
Q: Can I trigger prior authorizations directly from prescribing?
Yes. You can submit ePA requests referencing proposed prescriptions, attach clinical documentation, and receive payer questions and decisions programmatically.
Related Integrations
Intralinks API - Programmatically access the Intralinks VDR with Supergood
Ready to automate your Surescripts workflows?
Supergood can have your Surescripts integration live in days with no ongoing engineering maintenance.
