Surescripts Integration: The Complete Guide to the API, NCPDP SCRIPT, EPCS and Certification (2026)
CTO & Co-Founder
CTO & Co-Founder at Nirmitee.io. Architects healthcare integrations across FHIR, SMART on FHIR, ABDM and NHCX, writing from production experience taking hospital software from sandbox to go-live.
Updated November 2026
Short answer. Surescripts integration connects your EHR, telehealth product or prescribing app to the Surescripts network, so prescriptions reach US pharmacies through a pharmacy integration and replies come back. There is no public, self-serve Surescripts API. You either certify your own software with Surescripts, or you connect through a certified e-prescribing partner that already has the connection. Messages use the NCPDP SCRIPT standard. Controlled substances add DEA rules for identity, signing and audits.
This guide covers the whole job from start to finish. It explains what Surescripts offers, how to choose a route and which messages to support. It then covers version dates, controlled substances, certification, the build, testing, go-live and upkeep. It replaces our earlier Surescripts guide and keeps everything that guide covered.
Key takeaways
- Surescripts is a network you join. You do not get an API key and a sandbox from a website.
- Choose your route first. A certified partner is faster when prescribing is one feature. Direct certification fits when prescribing is your product.
- E-prescribing is a conversation. Renewals, changes, cancels and fill notices matter as much as the first prescription.
- SCRIPT 2023011 becomes the only version allowed for Medicare Part D on January 1, 2028. Build new work on it.
- Controlled substances need identity proofing, two-factor signing and a third-party audit under 21 CFR Part 1311. Plan them first.
- Certification and contracts usually set the date you go live, not the code.
What is Surescripts?
Surescripts runs the main US network for electronic prescriptions. It connects prescribers, pharmacies, pharmacy benefit managers (PBMs, the companies that run drug benefits for health plans) and health systems. You connect once and reach the pharmacies on the network.
The reach is large by the company's own figures: Surescripts reports 1.39 million prescribers and 98.3% of pharmacies actively e-prescribing through it at the end of 2025. The FTC said in 2023 that "virtually everyone" who fills a prescription electronically does so through Surescripts.
What you can connect to through Surescripts
| Service | What it does | Who uses it |
|---|---|---|
| E-prescribing | New prescriptions, renewals, changes, cancels and fill notices between prescriber and pharmacy | EHRs, telehealth, prescribing apps, pharmacies |
| Medication history | A patient's filled prescriptions, for reconciliation and safety checks | EHRs, hospitals, care managers |
| Eligibility and formulary | The patient's drug coverage and the plan's formulary while the prescriber writes | EHRs and prescribing apps |
| Real-time prescription benefit | The patient's cost for a drug and lower-cost options, at the time of prescribing | EHRs and prescribing apps |
| Electronic prior authorization (ePA) | Prior authorization requests and answers between prescriber and payer, in SCRIPT messages | EHRs, PBMs, payers |
| Clinical direct messaging | Secure messages between care teams | Health systems, care managers |
Most products start with e-prescribing and add the others later. Design your data model with room for them from the start.
Who needs a Surescripts integration?
- EHR and practice management vendors whose users prescribe.
- Telehealth and virtual care companies that prescribe after a visit.
- Digital pharmacies and pharmacy software that receive prescriptions.
- Health systems with their own clinical software.
- Payer and PBM technology vendors that need medication or benefit data.
Is there a Surescripts API?
No. We found no public developer portal, self-serve key or simple stand-alone Surescripts API. Access runs through a commercial agreement and certification of your software, or through a partner that already has them.
Developers searching for a "simple Surescripts API" usually want one of two things:
- A direct connection to the network. Surescripts says EHR vendors certify their EHR or stand-alone application with the network. Product access starts with a sales contact.
- An e-prescribing API from a certified vendor. Vendors such as DoseSpot, DrFirst, DAW Systems (ScriptSure), Bravado Health and LogiCoy sell APIs or embedded prescribing. Some describe themselves as Surescripts certified. These are their own descriptions. We have not tested them. Ask each vendor for current proof of certification for the transactions you need.
Why is Surescripts so hard to integrate with?
The message code is only one of five jobs, and the other four depend on contracts, audits and outside parties. That ranking is our planning judgment. Surescripts and the DEA publish the requirements and do not rank them.
- Access is gated. You need an agreement and certified software before live traffic moves.
- It is a conversation. Renewals, changes, cancels and fill notices arrive later, and someone in your product must act on them.
- Controlled substances bring federal rules. Identity proofing, two-factor signing and a third-party audit sit outside the message format.
- The standard is changing. SCRIPT 2017071 and 2023011 are both allowed until the end of 2027.
- Your product needs supporting data. Pharmacy lookup, drug coding, prescriber identity and patient matching must all be right before a message is valid.
Choose your route: direct certification or a certified partner
Choose a certified partner when prescribing is one feature of a wider product. Choose direct certification when prescribing is the product. Switching late is expensive. The comparison is our planning judgment.
| Direct Surescripts certification | Certified partner | |
|---|---|---|
| Best fit | A stand-alone prescribing product or a large EHR | A feature inside a wider clinical product |
| Who holds certification | You | The partner, for what it supports |
| Control over workflow | Most | Limited by the partner's API and roadmap |
| EPCS audit | Yours to arrange and repeat | Depends on the partner. Confirm who is responsible |
| Version upgrades | Yours to build, test and schedule | Mostly the partner's, on its timetable |
| Main risk | Time and ongoing compliance cost | Lock-in, pricing and missing transactions |
If you start with a partner, keep your own internal prescription model and put the partner behind one adapter. It costs little at the start and makes a later move much easier.
How to choose an e-prescribing partner
Ask every partner the same questions, in writing:
- Which SCRIPT transactions do you support today: NewRx, renewal, change, cancel, fill, medication history, ePA?
- Are you certified on SCRIPT 2023011, and if not, when?
- Do you support controlled substances, and who holds the EPCS audit?
- Do we get an API, an embedded screen, or both? Can we keep our own user interface?
- How do you price: per prescriber, per transaction or flat?
- Who owns the prescription data, and how do we export it if we leave?
- What uptime and support do you commit to, and how do you tell us about network outages?
NCPDP SCRIPT: the language prescriptions are written in
NCPDP SCRIPT is the e-prescribing standard from the National Council for Prescription Drug Programs. It plays the role HL7 v2 plays for hospital interfaces. Any Surescripts integration has to handle a set of messages in both directions.
The names below come from the Medicare Part D rule at 42 CFR 423.160 and Surescripts' e-prescribing page. Older guides shorten some of them to RxRenewal and RxChange. Check the directions against the guide for your version.
| Transaction | What it does | Usual direction |
|---|---|---|
| NewRx | Sends a new prescription | Prescriber to pharmacy |
| NewRxRequest, NewRxResponseDenied | Pharmacy asks for a new prescription. Prescriber can deny it | Pharmacy to prescriber, then back |
| RxRenewalRequest, RxRenewalResponse | Asks for more refills. Prescriber answers | Pharmacy to prescriber, then back |
| RxChangeRequest, RxChangeResponse | Asks to change a prescription, for example for formulary or prior authorization reasons | Pharmacy to prescriber, then back |
| CancelRx, CancelRxResponse | Cancels a prescription already sent. Pharmacy answers | Prescriber to pharmacy, then back |
| RxFill, RxFillIndicatorChange | Reports fill status. Prescriber changes which fill notices it wants | Pharmacy to prescriber, and back |
| RxTransfer and related messages | Moves a prescription between pharmacies | Pharmacy to pharmacy |
| RxHistoryRequest, RxHistoryResponse | Asks for medication history | Requester to network, then back |
| PAInitiationRequest, PARequest and related messages | Runs electronic prior authorization | Prescriber and payer, both ways |
| Status, Error, Verify | Confirms delivery or reports a failure | Both ways |
If you only implement NewRx, you have built a one-way fax with extra steps. Renewals, changes and cancels make the integration usable for clinicians, and in our experience they produce the most edge cases in testing.
What a new prescription carries
| Part | What goes in it | Where it comes from in your product |
|---|---|---|
| Header | Sender and receiver identifiers, message ID, time | Your network setup and the pharmacy directory |
| Patient | Name, date of birth, sex, address | The patient record |
| Prescriber | Name, NPI, DEA number for controlled substances, practice address and phone | The prescriber profile |
| Pharmacy | The chosen pharmacy's identifier and address | The pharmacy directory search |
| Medication | Drug name, RxNorm code, NDC where used, strength and form | Your drug database |
| Directions | Sig text, quantity, days' supply, refills, substitution allowed or not | The prescribing screen |
| Clinical notes | Diagnosis where required, note to the pharmacist | The prescribing screen |
| Controlled substance data | Schedule and the digital signature record | Your EPCS signing flow |
The implementation guide for your SCRIPT version is the source of truth for element names and rules. Use it, not this table, when you write code.
The SCRIPT version dates that apply now
SCRIPT 2023011 becomes the only allowed version for Part D e-prescribing on January 1, 2028. Until then, CMS allows either 2017071 or 2023011. Plan anything new on 2023011.
| Version or standard | Date | What happened | Source |
|---|---|---|---|
| SCRIPT 10.6 | December 31, 2019 | CMS sunset date for Part D | Surescripts |
| SCRIPT 2017071 | January 1, 2020 | Required for Part D under the April 2018 CMS final rule | CMS |
| SCRIPT 10.6 | September 1, 2021 | Surescripts sunset on its network, after moving from December 1, 2020 | Surescripts |
| SCRIPT 2023011 | July 17, 2024 | Allowed from this date when the June 2024 CMS final rule took effect | CMS |
| Formulary and Benefit v60, Real-Time Prescription Benefit v13 | January 1, 2027 | Part D compliance date | Surescripts, 42 CFR 423.160 |
| SCRIPT 2023011 only | January 1, 2028 | Part D must use it alone. 2017071 expires | CMS |
Health IT certification follows the same line. Under the HTI-4 rule, the certified e-prescribing criterion at 45 CFR 170.315(b)(3) allows either version until December 31, 2027. Modules certified to it must also be certified to the new real-time prescription benefit criterion at (b)(4).
Three things stay open, so check them at the start:
- The network date. We found no separate public Surescripts cutoff for 2017071. Ask Surescripts or your partner.
- Backward compatibility. NCPDP told CMS in 2023 that 2023011 is backward compatible with 2017071. Drummond Group's developer guide says it is not and suggests treating it as a new integration. Plan the upgrade as separate build and test work until the implementation guide settles it for you.
- The EPCS audit. Drummond says the upgrade counts as a change to controlled substance functions, which can trigger an audit. The DEA text requires a new audit when that functionality changes, so ask your auditor.
Surescripts also offers a self-service Certification Tester for the 2023011 upgrade, so vendors can check requirements before formal certification.
EPCS: controlled substances
Electronic Prescribing of Controlled Substances (EPCS) covers Schedule II to V drugs. The DEA regulates it under 21 CFR Part 1311. A controlled substance NewRx is still a SCRIPT message. The hard part is the set of controls around it.
| Requirement | What the rule says | Section |
|---|---|---|
| Identity proofing | Credential from a GSA-approved provider at NIST SP 800-63-1 Assurance Level 3 or above, or a certification authority cross-certified with the Federal Bridge. Institutions can proof their own practitioners | 1311.105, 1311.110 |
| Two-factor authentication | Two of: something known, something held (a hard token separate from the computer, at least FIPS 140-2 Security Level 1), something the prescriber is | 1311.115 |
| Access control | At least two people manage access to the application at each registered location | 1311.125 |
| Signing | The prescriber marks each order ready, then signs with two factors. An unsigned order cannot be sent | 1311.120 |
| Digital signature | The application signs the required data with a FIPS-validated module and archives the record | 1311.120 |
| Audit trail | Logged events, internal reports, protection from changes, and two years of retention | 1311.120 |
| Third-party audit | Before first use, then every two years or when controlled substance functions change, whichever comes first. DEA-approved certification is an alternative | 1311.300 |
Surescripts adds its own gate. Applications must prove they passed a third-party audit under DEA requirements before they can send EPCS messages on the network. Surescripts also says it enforces NIST IAL2 for identity, which uses newer NIST terms than the DEA text. Confirm which your identity provider must meet.
Medicare adds demand. Under the SUPPORT Act, the CMS EPCS program covers Schedule II to V drugs under Part D, with compliance at 70% or more. Prescribers with 100 or fewer qualifying prescriptions get an automatic exception.
If controlled substances are in scope, design EPCS first. It shapes your sign-in, your user setup and your audit log, and it is hard to add later.
How to integrate with Surescripts, step by step
- List what you need. Which transactions, which users, which states, and whether controlled substances are in scope.
- Choose the route. Direct certification or a certified partner, using the questions above.
- Sign the agreements. With Surescripts for a direct route, or with the partner. Add a business associate agreement (BAA) where patient data flows.
- Get the implementation guides. The SCRIPT version guide, Surescripts' guides and, for a partner, its API documentation.
- Build the supporting data. Prescriber profiles with NPI and DEA numbers, pharmacy directory search, drug database with RxNorm, and patient matching.
- Build the prescribing screen. Drug search, directions, quantity, refills, substitution, pharmacy choice, and drug and allergy checks.
- Build the conversation. NewRx first, then renewals, changes, cancels, fill notices and errors, each with an inbox that a person owns.
- Build EPCS if needed. Identity proofing, two-factor signing, digital signature, access control and the audit log, then the third-party audit.
- Test every conversation. Use the test cases from Surescripts or your partner, plus the checklist below.
- Certify. Pass Surescripts certification for each transaction, or the partner's acceptance tests.
- Go live in stages. Turn on one practice or a few prescribers first, watch every message, then widen.
- Run it. Monitor messages, refresh the pharmacy directory and drug data, plan version upgrades and repeat the EPCS audit on time.
How to integrate Surescripts into a custom EHR
Build the prescribing workflow and supporting data first, then connect it through your chosen route. Partner APIs hide some of this work, so check what yours covers.
| What you need | Why it matters |
|---|---|
| Prescriber records | Identity, NPI, DEA details where relevant, and the location they prescribe from |
| Pharmacy lookup | Prescribers must find and select the right pharmacy from the directory |
| Drug data | RxNorm and NDC coding, as the certification criterion references |
| A clinical inbox | Renewal and change requests need an owner and a screen |
| Message tracking | Delivery status, errors and retries, because replies arrive later or not at all |
| Patient matching | Demographics good enough for medication history and benefit lookups |
| A FHIR bridge, if you use FHIR | Map FHIR MedicationRequest to SCRIPT and keep the mapping tested |
| An interface layer | An engine such as Mirth Connect, or your own service, to send, retry and log |
Testing checklist before go-live
- A NewRx for a common drug reaches the test pharmacy, and the status comes back
- A NewRx with a free-text note and a "no substitution" flag
- A renewal request answered with approve, deny and "new prescription to follow"
- A change request for a formulary reason and one for prior authorization
- A cancel for a prescription already sent, with the pharmacy's answer
- Fill notices turned on and off
- An error from the network, shown to a person with a clear next step
- A message that gets no reply within the expected time, with an alert
- A controlled substance prescription signed with two factors, and one blocked because signing failed
- Medication history for a patient with a similar name to another patient
- Every test repeated on SCRIPT 2023011
Go-live and monitoring
Watch these from the first day:
- Share of messages sent with a success status
- Errors by type, and how long each waited for a person
- Renewal and change requests waiting in the inbox, and their age
- Time from a pharmacy request to the prescriber's answer
- Failed or retried messages
- EPCS signing failures, and the date of the next audit
- Pharmacy directory and drug data refresh dates
What usually goes wrong
| Problem | What causes it | How to prevent it |
|---|---|---|
| Prescription goes to the wrong pharmacy | Similar names in the directory, or an old pharmacy saved on the patient | Show address and phone in search, and confirm the pharmacy at signing |
| Renewal requests pile up | No owner for the inbox | Route each request to a prescriber or a team, with an age alert |
| Pharmacy rejects the prescription | Missing or wrong fields, such as quantity units or directions | Validate before sending, and show the error in plain words |
| Controlled substance cannot be sent | Prescriber not proofed, token missing, or audit expired | Check EPCS readiness per prescriber before they need it |
| Duplicate prescriptions | Retry after a slow reply that did succeed | Use message IDs and check status before resending |
| Patient's cost surprises them | No benefit check at prescribing | Add real-time prescription benefit when the route supports it |
| Upgrade breaks things | SCRIPT version change treated as a small patch | Plan 2023011 as its own build and test project |
What drives the cost
We cannot give a fair price without your scope, and Surescripts and partners do not publish standard fees. These are the things that move the cost most:
- Direct certification versus a partner, and the partner's pricing model
- How many transactions you support beyond NewRx
- Whether controlled substances are in scope, which adds identity proofing, signing and audits
- Whether you need FHIR on one side and SCRIPT on the other
- How many prescribers and locations you roll out to
- Ongoing work: version upgrades, audits, directory and drug data refreshes, support
A plan for success
Split the work into parallel tracks, each with an owner. One estimate based on the coding alone is the mistake we see most. The track list is our planning judgment.
| Track | What it covers | Done when |
|---|---|---|
| Route | Direct or partner, transactions, contract | Decision signed off and transactions listed |
| Standards | 2023011 plan, NewRx, then renewal, change, cancel and fill | Every conversation passes in test |
| Certification | Surescripts or partner testing and agreements | Approved for each transaction |
| EPCS, if in scope | Identity proofing, two-factor signing, audit | Audit or certification report accepted |
| Product data | Pharmacy lookup, drug coding, inbox, tracking | A prescriber can finish the workflow end to end |
| Upkeep | Version dates, audit dates, directory refresh | Owner and calendar in place |
How Nirmitee helps
We scope and build pharmacy and EHR integrations, including the bridge between NCPDP SCRIPT and FHIR. Certification belongs to the software owner or the partner you connect through. We plan the route with you and do not offer our own shortcut onto the network.
Our background: we sign BAAs, we are ISO 27001:2022 certified, and we delivered 350+ Mirth Connect interfaces. See our pharmacy integration services and electronic prior authorization integration. You can also tell us about your product and prescribers. We will tell you which route fits and what to check first.
For the FHIR side, read why FHIR MedicationRequest is not enough for e-prescribing. For an interface engine build, read Mirth Connect NCPDP SCRIPT integration.
Sources
- Surescripts, NCPDP 2023 upgrade, checked 3 November 2026
- Surescripts, Network Alliance Partner Program
- ONC, 170.315(b)(3) Electronic prescribing test method
- eCFR, 42 CFR 423.160, standards for Part D electronic prescribing
- eCFR, 21 CFR Part 1311, requirements for electronic orders and prescriptions, including 1311.300 audits
- Federal Register, EPCS clarification, October 2011
- Prescriber and pharmacy counts are Surescripts' own reported figures for the end of 2025, as cited in our earlier guide
Connecting your product to e-prescribing?
Review the NCPDP SCRIPT workflow, network access and certification dependencies before building. Bring your prescribing use case and current Surescripts or intermediary access status.
Frequently Asked Questions
Is there a Surescripts API?
How do I get Surescripts certified?
How long does a Surescripts integration take?
What is the difference between Surescripts and NCPDP SCRIPT?
Which SCRIPT version should I build?
Do I need EPCS?
Can I use FHIR to send prescriptions through Surescripts?
Should we use a partner like DoseSpot or DrFirst, or certify directly?
