Open Dental recall list automation: building the cascade
Pull the Open Dental recall list through the API and send a reminder cascade from it. ODFHIR auth, the permission tiers and prices, and the BAA step.
What you get from this guide
- The six recall endpoints Open Dental documents, and the one list call that does most of the work
- ODFHIR authentication: Developer Key, Customer Key, and who has to enable what
- Open Dental's published API permission tiers and monthly prices as of August 2026
- A reminder cascade that uses NumRemind and LastRemind instead of guessing
- Writing every attempt back as a commlog so the front desk can see it
Why build this rather than buy it
Almost everything written about the Open Dental API is written by Open Dental. That is unusual, and it is why practices with a real developer relationship end up piecing this together from forum threads.
The case for building rather than buying a patient-communication product is narrower than vendors suggest, and it is worth being straight about it. If you want a full communications suite - two-way messaging, reviews, forms, payments - buy one. Building that is a bad use of money. What custom work is genuinely good at is the specific thing your practice does that no product models: a recall cascade that treats a six-week-overdue prophy patient differently from a two-year-lapsed perio patient, that suppresses anyone with an outstanding balance, that routes a particular provider's recalls to a particular team member, or that feeds your own reporting.
The API supports that, and the surface is better documented than its reputation suggests. Everything below is taken from Open Dental's published documentation as of August 2026, with the gaps called out where they exist.
What the API exposes for recalls
Open Dental documents six recall operations:
| Operation | What Open Dental says it does |
|---|---|
| Recalls GET | Gets a list of recalls. |
| Recalls GET List | Gets the Recall List similar to how it's shown in the Appointment Module. |
| Recalls POST | Creates a recall for a patient. |
| Recalls PUT | Updates a recall. |
| Recalls PUT Status | Updates the RecallStatus on a patient's recall. |
| Recalls PUT SwitchType | Switches a Recall's type. |
The one that matters for reminders is Recalls GET List, documented as added in version 22.1. It is the closest thing to a purpose-built endpoint for this job, because it returns the same view the front desk already works from. Its documented query parameters:
| Parameter | Documented behaviour |
|---|---|
| DateStart | Due date range. String in 'yyyy-mm-dd' format. Default is based on RecallDaysPast preference. |
| DateEnd | Due date range. String in 'yyyy-mm-dd' format. Default is based on RecallDaysFuture preference. |
| ProvNum | Provider. Default is all providers. Will consider PriProv and SecProv. |
| ClinicNum | Clinic. Default is all clinics. Use 0 for 'Unassigned'. |
| RecallType | Typically either 'Prophy' or 'Perio'. Default is all RecallTypes stored in the preference. |
| IncludeReminded | Show patients that have already received reminders. Either 'true' or 'false'. Default is false. |
The response carries DueDate, PatNum, Patient, Age, Type, Interval, NumRemind, LastRemind, Contact, Status, ClinicNum and Note. Three of those fields are the whole reason this build works well: NumRemind and LastRemind mean you never have to keep your own reminder counter and never accidentally send a fourth text, and Contact gives you the destination without a second lookup.
One recall per type, per patient
Authentication, keys and the throttle
Authentication is two keys in one header, and the format is specific. Open Dental documents it as Authorization: ODFHIR {DeveloperKey}/{CustomerKey}. Both must be present on every request. The base URL is https://api.opendental.com/api/v1, responses are JSON, and a Content-Type header of application/json is required.
A minimal authenticated request
GET /api/v1/recalls/List?DateStart=2026-08-01&DateEnd=2026-08-31
Host: api.opendental.com
Authorization: ODFHIR {DeveloperKey}/{CustomerKey}
Content-Type: application/json
# 200 OK -> array of due recalls
# 401 -> key wrong, or not enabled by the practice
# 429 -> throttled; honour the Retry-After headerThe two keys do different jobs, and confusing them is the usual first-day problem:
- The Developer Key is unique per developer and obtained through Open Dental's Developer Portal. To get access, developers contact vendor relations with company name, contact details and a description of the intended application. It identifies you, not the practice.
- The Customer Key is unique to each customer and developer pair and is generated by the developer within the portal. The practice then enables or disables the assigned key from inside Open Dental - so the practice retains the off switch, and nothing works until they flip it on.
Open Dental states the API web service is hosted at Open Dental headquarters, with an eConnector routing requests from api.opendental.com through to the dental office. It also documents a Local API variant that runs at office workstations without routing through Open Dental servers, with credentials still verified remotely - relevant if the practice has a policy against clinical data traversing a third party unnecessarily, though it changes where your automation has to run.
On throttling: Open Dental documents one request per five seconds for keys with only ApiReadAll permission, and one request per one second with additional permissions, returning 429 with a Retry-After header when requests queue up. Local API requests bypass throttling. One request per second shapes the design more than anything else on this page - the list endpoint is your friend precisely because it avoids a per-patient loop. Documented status codes are 200, 201, 400, 401, 404, 410, 429 and 504. See rate limit and retry and backoff for the handling pattern.
Permission tiers and what they cost
Open Dental scopes API access by permission rather than granting all or nothing, and it publishes prices against those scopes. Documented scopes include Read All, AllOthers, Comm, Documents, Queries, Appointments, InsuranceSimple, Insurance, Patients, Payments, PayPlans, ProcedureLogs, Setup, and the special TextingASAP and Enterprise permissions.
The published general monthly pricing, quoted as of August 2026:
| Monthly | Scope | Throttle |
|---|---|---|
| Free | Read All (GET methods only) | 1 request per 5 seconds |
| $15 | Comm, Documents, InsuranceSimple, Setup, and Queries | 1 request per 1 second |
| $30 | All except Payments, PayPlans, and Special | 1 request per 1 second |
| $35 | All except Special | 1 request per 1 second |
Open Dental states that pricing applies per location and that a key must be assigned and enabled before charges apply. For a recall reminder build the relevant tier is the $15 one, because reading the recall list is a GET and writing commlogs falls under Comm. That is a genuinely low number, and it is worth setting against the per-seat monthly cost of a patient-communication suite when you are deciding whether a targeted custom build is worth commissioning. Our AI automation cost page covers the rest of the arithmetic, and what a build costs covers the one-off side.
Building the reminder cascade
With the list endpoint and NumRemind, the cascade is mostly a segmentation problem rather than an engineering one.
Pull the due list on a schedule, not per patient
One call each morning with a DateStart and DateEnd window covering what you consider due, filtered by ClinicNum if the practice has more than one location. Leave IncludeReminded at its documented default of false so patients already reminded drop out of the set automatically.
Segment by how overdue, not by how many days since the last text
A patient three weeks past due and a patient two years lapsed need different messages. Use DueDate against today to bucket them - recently due, months overdue, long lapsed - and write a different message for each bucket. This single distinction does more for response rate than any amount of send-time optimisation.
Cap the sequence using NumRemind and LastRemind
Decide with the practice how many contacts a patient may receive and over what period, then enforce it from the fields the API already gives you rather than a counter you maintain. If NumRemind is at the cap, or LastRemind is within your minimum gap, the patient is skipped. No local state, nothing to drift.
Suppress the patients who should not be contacted
The recall record carries IsDisabled, DisableUntilDate and DisableUntilBalance. Honour all three. Add whatever practice-specific suppressions exist - a patient in active treatment, a family the office is handling personally, anyone who has asked not to be texted - and make the suppression list something a staff member can edit without a developer.
Vary the ask across the sequence
A cascade of three identical messages is one message sent three times. The shape that works is a short factual nudge first, then a message that gives a reason - the interval, the last visit date - and finally a lighter touch that makes it easy to say not now, which is itself useful information for the front desk.
Stop on any sign of human contact
Before each subsequent step, re-check the recall status and whether the patient has a scheduled appointment. If they have booked or replied, end the sequence. This is the difference between an automation the front desk trusts and one they ask you to turn off.
The mechanics of two-way replies, confirmations and rescheduling are the same as any appointment reminder system, and our AI appointment reminders guide covers the cadence and reply handling in detail. See also STOP handling, which is not optional.
Writing the outcome back with commlogs
An automation that sends messages the practice cannot see inside Open Dental is a liability. The commlog endpoints are how you avoid that, and using them is the difference between a tool the office trusts and a black box.
Open Dental documents four commlog operations: GET a single commlog by CommlogNum (version 25.1.13 and later), GET multiple with optional filtering (21.1 and later), POST to create (21.1 and later), and PUT to update (25.2.21 and later). Optional filters on the list include PatNum and DateTStamp.
| Field | Documented behaviour |
|---|---|
| PatNum | Mandatory on POST. The patient the communication belongs to. |
| Note | Required on POST. On PUT, overwrites the existing note. |
| Mode_ | Either 'None', 'Email', 'Mail', 'Phone', 'In Person', 'Text', 'Email and Text', or 'Phone and Text'. Default 'Phone'. |
| SentOrReceived | Either 'Neither', 'Sent', or 'Received'. Default 'Sent'. |
| CommDateTime | Optional. String in 'yyyy-mm-dd HH:mm:ss' format. Default now. |
| CommType | Optional. definition.DefNum where definition.Category=27. Default Miscellaneous. |
Commlog write after a reminder goes out
POST /api/v1/commlogs
Authorization: ODFHIR {DeveloperKey}/{CustomerKey}
{
"PatNum": 1042,
"Note": "Automated recall reminder 2 of 3 sent by SMS.
Prophy due 2026-06-14. No reply yet.",
"Mode_": "Text",
"SentOrReceived": "Sent",
"CommDateTime": "2026-08-05 09:14:00"
}Write the commlog on every attempt, including failures, and make the Note readable by a human rather than a machine. When a patient rings back annoyed, the front desk should be able to open the chart and see exactly what was sent and when, without calling you. Set Mode_ honestly - Text for SMS, Email for email - so the office can filter on it later.
HIPAA, BAAs and what we are not telling you
This is a page about an API that touches patient records, so the compliance section needs to be factual and appropriately humble.
What Open Dental publishes: its API specification states that API developers should have a Business Associate Agreement (BAA) in place with their clients. That is the vendor's stated expectation, and it applies to whoever writes and runs the integration. The pages we checked did not carry further HIPAA guidance, and we are not going to fill that silence with invented specifics.
The practical things a build like this should get right, stated as design practice rather than legal advice:
- A BAA with every party that touches the data - the developer, the automation platform if it is hosted, and the SMS or email provider that delivers the message. If a vendor will not sign one, that is your answer about that vendor.
- Minimum necessary in the message body. A reminder can say a check-up is due without naming a procedure or a diagnosis. Assume the message will be read on a lock screen by someone other than the patient.
- Minimum necessary in the permission tier. Open Dental's scoped permissions exist so a recall workflow does not need Payments or Insurance access. Take the narrowest scope that works.
- Deliberate retention. Decide how long execution logs holding patient data are kept, and enforce it, rather than letting a platform's default retention decide for you.
- Access control and revocation. The practice can disable the Customer Key from inside Open Dental. Make sure they know that, and make sure someone at the practice knows who holds the developer credentials.
Where our expertise stops
If you are weighing this against the wider question of what to automate in a practice first, the dental practice automation page sets out the workflows in the order they usually pay back. Before you send anything by SMS, read the A2P 10DLC guide - registration is the first task, not the last. If the same practice wants the reporting side, our Housecall Pro to Google Sheets build shows the reconciliation pattern that keeps any API-to-spreadsheet sync honest, and n8n self-hosted vs cloud matters here because where the workflow runs is a compliance decision as much as a cost one. Terms like DPA and data residency come up in that conversation.
FAQ
- How do I pull the Open Dental recall list through the API?
- Call Recalls GET List (GET /api/v1/recalls/List) with a DateStart and DateEnd window, optionally filtered by ClinicNum, ProvNum and RecallType. Leave IncludeReminded at its default of false so patients who have already been reminded drop out. It returns the Recall List the way the Appointment Module shows it, including DueDate, Patient, NumRemind, LastRemind, Contact and Status, which is everything a reminder cascade needs to decide who to contact next and how many times they have been asked already.
- What does the Open Dental API expose for recalls?
- Open Dental documents six recall operations: Recalls GET, which gets a list of recalls; Recalls GET List, which returns the Recall List similar to how it is shown in the Appointment Module; Recalls POST to create a recall for a patient; Recalls PUT to update one; Recalls PUT Status to update the RecallStatus; and Recalls PUT SwitchType to switch a recall's type. The recall record exposes RecallNum, PatNum, DateDue, DatePrevious, RecallInterval, RecallStatus, Note, IsDisabled, DateTStamp, RecallTypeNum, DisableUntilBalance, DisableUntilDate, DateScheduled, Priority and TimePatternOverride. The list view adds DueDate, Patient, Age, Type, Interval, NumRemind, LastRemind, Contact, Status and ClinicNum.
- How does Open Dental API authentication work?
- Two keys, both in one header. Open Dental documents the format as Authorization: ODFHIR {DeveloperKey}/{CustomerKey}. The Developer Key is unique per developer and comes from the Developer Portal after contacting vendor relations with your company details and a description of the application. Customer Keys are unique to each customer and developer pair, generated by the developer in the portal, and the practice enables or disables them from within Open Dental. The base URL is https://api.opendental.com/api/v1, and Open Dental states that the API web service is hosted at Open Dental headquarters, with an eConnector routing requests through to the office. All figures and details here are as of August 2026.
- Is there a rate limit?
- Yes, and it is tied to your permission tier. Open Dental documents customer-specific throttling: developers with only ApiReadAll permission are limited to one request per five seconds, while those with additional permissions get one request per one second. If too many requests queue the API may return 429 Too Many Requests with a Retry-After header. Open Dental also documents a Local API variant that runs at the dental office workstations without routing through Open Dental servers and bypasses throttling entirely, though credentials are still verified remotely. One request per second is not much, so design the recall pull as one paged list call rather than a per-patient loop.
- Does the Open Dental API cost money?
- Open Dental publishes what it calls general monthly pricing for API access by permission scope, as of August 2026: free for Read All with a one request per five seconds throttle, $15 for Comm, Documents, InsuranceSimple, Setup and Queries with a one request per second throttle, $30 for all except Payments, PayPlans and Special, and $35 for all except Special. It states pricing applies per location and that a key must be assigned and enabled before charges apply. A recall reminder build that reads the recall list and writes commlogs needs the Comm scope, so the $15 tier is the relevant one. Confirm current pricing with Open Dental before budgeting - this is their published guidance rather than a quote.
- Do I need a Business Associate Agreement?
- Open Dental's own API specification states that API developers should have a Business Associate Agreement (BAA) in place with their clients. That is the vendor's stated expectation and we are repeating it rather than interpreting it. Beyond that, whether your specific build, your messaging provider, your hosting and your data retention meet your obligations under HIPAA is a question for a compliance advisor or attorney who knows your practice. We are automation builders, not your compliance counsel, and we will not pretend a web page can substitute for that advice.
- How many reminders should the cascade send?
- There is no vendor-published number and we are not going to invent one. What the API gives you is better than a rule of thumb: NumRemind and LastRemind on the recall list tell you how many reminders a patient has already had and when, so you can cap the sequence at whatever your practice decides and enforce it in code. The design principle that holds regardless of the number is that each touch should be different from the last - a nudge, then a reason, then an easy way out - and that the sequence must stop the moment the patient books, replies, or a staff member speaks to them.
- Can I book the appointment automatically?
- Technically, in part. Open Dental publishes an Appointments permission scope covering appointment creation and scheduling, so the API surface exists. Whether you should is a different question. Recall booking depends on provider availability, appointment length, hygiene versus doctor time and patient preference, and an automation that books the wrong slot creates more front-desk work than it saves. The pattern we would defend is that the automation surfaces the patient and the intent, and a human or a properly configured online-booking product closes it. If you do automate booking, start with a single recall type and one provider.
- What about SMS registration for the reminders themselves?
- If you send the reminders yourself from a US ten-digit number, they are application-to-person traffic and carriers expect them registered under A2P 10DLC. That is a separate project with its own approval wait, and unregistered traffic fails silently rather than erroring, which means your recall campaign can look healthy while reaching nobody. Read our A2P 10DLC guide before you pick a send date, and treat registration as the first task rather than the last.
Done for you
Want a recall cascade built against the Open Dental API, with the commlog write-back?
We build recall and reminder automations on the Open Dental API: scoped permissions, segmentation by how overdue the patient is, a cap enforced from NumRemind, and every attempt written back as a commlog the front desk can read. Compliance sign-off stays with your advisors, and we build to their requirements.
The consult is free, and you keep whatever we build.
Keep building
The rest of the cluster
AI Appointment Reminders That Cut No-Shows
Two-way confirm and reschedule, waitlist backfill, cadence, and SMS compliance basics.
Read the guideA2P 10DLC Guide for SMS Automation Builds
Brand then campaign, the sole proprietor route and its caps, published fees, and the real rejection reasons.
Read the guideHousecall Pro to Google Sheets, For Real
The MAX plan gate, the webhook events worth syncing, an upsert-safe sheet, and what breaks at scale.
Read the guideFree AI Automation Audit Template
Score every recurring task and rank the top three worth automating before you build anything.
