Contents
The List Nobody Works
Every general practice running an API-connected Open Dental install has the same quiet asset sitting in the database: procedures a dentist diagnosed, presented, and entered into a treatment plan, which were never scheduled. Not declined. Not completed. Just never booked, because the patient said "let me check with my husband" at the front desk and nobody called back.
In most practices this list is worked in one of two ways. Either somebody runs the Treatment Plan report on a slow afternoon and calls down it until the phone rings out, or nobody works it at all and the balance quietly ages until the diagnosis is stale enough that it has to be re-examined. The second outcome is far more common, and it is not a discipline failure. Working the list manually means opening a chart, reading the plan, deciding whether the case is still valid, checking whether the patient is already coming in, and then making a call that will mostly go to voicemail. That is five minutes per patient before anyone picks up.
This post is about turning that into a scheduled job. It is deliberately narrow: it is not about hygiene recall, which we cover in the Open Dental API recall automation guide, and it is not about reminding people about appointments they already have, which is appointment reminders. Unscheduled treatment is a different query against different tables, with a different message and a different failure mode, and conflating the three is the most common reason these builds annoy patients.
One framing note before the technical part. This is a good automation candidate precisely because the hard part is not judgement, it is retrieval. The dentist already made the clinical decision. The automation's job is to find that decision, check it is still current, and put a booking link in front of the right person. That keeps the model surface small, which is the argument we make at length in when not to use an AI agent.
What Open Dental Actually Stores
The thing that makes this build tractable is that Open Dental does not hide treatment plan state behind a computed report. It is a status field on the procedure record, and it is exposed through the API.
The relevant resource is procedurelogs. Open Dental's documentation for it lists these endpoints:
GET /procedurelogs/{ProcNum}- retrieve a single procedureGET /procedurelogs- retrieve multiple procedures with filtersGET /procedurelogs/InsuranceHistory- previous treatment datesGET /procedurelogs/GroupNotes- group notes for proceduresPOST /procedurelogs- create a procedurePUT /procedurelogs/{ProcNum}- update an existing procedureDELETE /procedurelogs/{ProcNum}- delete a procedure
For this build you only need the second one. The field that carries the meaning is ProcStatus, and Open Dental documents the following values:
| ProcStatus | Meaning | Relevant here? |
|---|---|---|
TP | Treatment Planned | Yes - this is the target |
TPi | Treatment Plan inactive | No - deliberately set aside |
C | Complete | No - already done |
EC | Existing, Current Provider | No - pre-existing work |
EO | Existing, Other Provider | No - pre-existing work |
R | Referred Out | No - someone else is doing it |
Cn | Condition | No - a finding, not planned work |
D | Deleted | No |
Two of these deserve emphasis because they are where naive builds go wrong. TPi - treatment plan inactive - exists precisely so a practice can park a plan without deleting it. If your query grabs everything that is not C, you will message patients about plans the practice consciously shelved. And Cn (condition) is a clinical finding rather than proposed work, so it has no business in a follow-up campaign at all.
The other useful detail Open Dental documents on this resource is a write restriction: the CodeNum, procCode, Discount, ToothNum, Surf and ToothRange fields cannot be updated on procedures with a ProcStatus of C. That is not directly relevant to a read-only follow-up job, but it tells you something about the system's shape: completed procedures are treated as close to immutable, which is the correct behaviour for a clinical record and a good reason not to design an automation that wants to rewrite history.
What we did not verify: the precise query-string filter names accepted by GET /procedurelogs for status and date ranges. Open Dental's resource page documents the endpoints and the status enum, and we have quoted those exactly, but you should confirm the exact filter parameter spelling in the live documentation for your API version before writing the call. We would rather flag that gap than invent a parameter name that looks plausible in a code block.
Auth, Access and the Paperwork That Gates It
Open Dental's API is refreshingly blunt about authentication. There is no OAuth flow, no token exchange and no refresh cycle. Requests carry a single header:
Authorization: ODFHIR {DeveloperKey}/{CustomerKey}
Open Dental's setup documentation publishes a sample credential in exactly that shape for testing purposes: Authorization: ODFHIR NFF6i0KrXrxDkZHt/VzkmZEaUWOjnQX2z. The structure tells you how the model works. The developer key identifies whoever built the integration; the customer key identifies the individual practice database. One integration, many practices, two halves of one header.
The base URL for the REST API is https://api.opendental.com/api/v1. Note that this is distinct from Open Dental's FHIR API, which is a separate interface - if you go looking for FHIR resource names in the REST docs you will have a confusing afternoon.
Getting a developer key is an application, not a signup form. Open Dental's setup page states that requests take one to three business days to process, and asks applicants to supply the product or integration owner company name, a contact phone number, a billing email, a mailing address, the API resources needed with the specific permissions required against each one (read, create, or update), and a description of the application you intend to build, including its type and purpose.
That "resources needed with specific permissions" line is worth reading carefully, because it has a direct consequence on runtime performance that we cover in the next section. You are asked up front to declare whether you need read, create or update on each resource. Ask for what the build genuinely needs. Asking for less than you need means reapplying; asking for sweeping write access on a clinical database because it seemed easier is a conversation you do not want to have with a practice's compliance officer.
There is also a hard prerequisite: Open Dental's API specification states that developers need a Business Associate Agreement in place with their clients. If you are an outside builder, that BAA is between you and the practice, and it should be signed before you hold a customer key, not after. See data processing agreements for the general shape of these, and note that a BAA under HIPAA is a specific instrument rather than a generic DPA.
Open Dental also notes that pricing tiers for API developers are available, referenced from its API permissions page. We did not verify the actual figures and are not going to quote numbers we have not read at source. Confirm current developer pricing with Open Dental directly before you budget the project.
The Throttle Shapes the Whole Build
This is the section that separates a build that works from one that gets a practice's IP address suspended. Open Dental documents its pacing explicitly, and the numbers are more restrictive than most people assume when they start.
The headline constraint, quoted from Open Dental's implementation documentation: API developers who only have the ApiReadAll permission have their customers' requests throttled to one request per five seconds. If the API user possesses any other API permission, that relaxes to one request per one second.
Read that twice, because the incentive is counterintuitive. The broad, convenient-sounding "read everything" permission is the slow one. A developer key scoped to specific resources runs five times faster than one holding blanket read access. If you are designing this integration, scoping permissions tightly is not just a security posture, it is a five-fold throughput difference.
Two more documented limits compound with that. First, paging: Open Dental states that the limit is usually not specified and defaults to a hard limit of 100 items for any request. Second, pacing is applied per customer key - Open Dental describes requests as subject to per-customer-key pacing to ensure fair and reliable performance for all users. And the consequence for ignoring this is not a soft warning. Open Dental states that for excessive requests they may temporarily suspend access from the offending IP address or network, and ultimately terminate access permanently.
What that means arithmetically
Take a practice with 2,400 procedures currently sitting at ProcStatus TP. At the default page size of 100 items, that is 24 requests to walk the full list.
- With only ApiReadAll (one request per five seconds): 24 x 5 = 120 seconds just to page the procedure list.
- With scoped permissions (one request per second): 24 x 1 = 24 seconds.
Two minutes sounds harmless, and for a nightly job it is. The problem is what people build next. The obvious follow-up step is "for each procedure, fetch the patient record to get their contact details and check whether they have an upcoming appointment." Do that naively, one patient at a time, and 2,400 procedures becomes 2,400 additional requests. At one request per five seconds that is 12,000 seconds - three hours and twenty minutes. At one per second it is 40 minutes. Either way you have built something that runs for hours to send a handful of texts, and that is before any retry and backoff on failures.
The fix is ordinary engineering, not cleverness. Deduplicate to unique patients before you enrich anything - 2,400 procedures across a practice is frequently 600 or 700 distinct people once you group by patient, because treatment plans routinely carry several procedures each. Filter aggressively before enrichment rather than after. Cache patient records between runs and only refresh what changed. And run the whole thing on a cron trigger overnight, where a slow job is invisible, rather than on demand where somebody is watching a spinner.
This is also the reason to prefer batch scheduled runs over anything event-driven here. There is no benefit to reacting within seconds to a treatment plan being entered - the patient is usually still in the chair. See polling vs webhook for when that trade-off runs the other way.
Filtering the List So You Do Not Embarrass the Practice
The raw TP list is not a campaign list. Sending to it unfiltered is how a practice ends up texting a patient about a filling they had placed six weeks ago at a different office, or about a plan the dentist withdrew after a re-examination. Every filter below exists because skipping it produces a specific, recognisable complaint at the front desk.
1. Exclude anyone already scheduled
The single most important filter. If a patient has a future appointment, they are not an unscheduled-treatment problem, they are an appointment-reminder problem, and messaging them about booking makes the practice look like it is not paying attention. The appointments resource supports GET /appointments for retrieving multiple appointments, with PatNum, AptDateTime and AptStatus among its documented fields - enough to determine whether a given patient has something on the books ahead of today.
2. Age the plan, in both directions
Very recent plans should be left alone. A patient who was presented a plan yesterday does not need an automated nudge today; the front desk is probably mid-conversation with them. Very old plans should also be excluded, because a diagnosis past a certain age needs re-examination before it can honestly be presented as current. Where those two boundaries sit is a clinical decision for the practice, not a default you should ship. Ask the dentist and write their answer into the config.
3. Respect TPi as the deliberate signal it is
Covered above, and worth repeating because it is the most common query bug: filter on ProcStatus == "TP" exactly, not on "anything not complete."
4. Set a value floor
Not because small cases do not matter clinically, but because message fatigue is a finite budget. A practice that texts every patient about every outstanding sealant will have its messages ignored by the time it needs to reach someone about a crown. Group by patient, sum the plan value, and set a threshold the practice is comfortable with.
5. Honour communication preferences and consent
Open Dental carries per-patient contact preferences, and they exist to be obeyed. On top of that, any SMS follow-up in the US sits under carrier rules that are entirely separate from the practice management system - see our A2P 10DLC guide for what registration actually involves, and STOP handling for the non-negotiable opt-out mechanics. A dental practice sending unregistered application-to-person traffic will find its messages filtered by carriers long before any patient complains.
6. Suppress on any open financial or clinical flag
Accounts in collections, patients flagged for a clinical reason, patients the practice has dismissed. The practice will have its own list. Ask for it, and put a manual suppression file in the pipeline that the front desk can edit without calling you.
Filters one through six typically take a raw list of a few thousand procedures down to a few dozen people worth contacting this week. That reduction is the product. The API access is just plumbing.
A Worked Example, With the Arithmetic Shown
Here is a single practice's numbers run end to end. These are illustrative inputs chosen to show the method - substitute your own, because the whole point is that nobody can tell you your conversion rate from the outside.
Starting position. A two-dentist general practice. The Open Dental database holds 2,400 procedures at ProcStatus TP.
Step 1 - group by patient. 2,400 procedures resolve to 680 distinct patients, because a typical plan carries three to four procedure lines.
Step 2 - exclude the already-scheduled. 190 of those patients have a future appointment. 680 - 190 = 490 remaining.
Step 3 - age filter. Exclude plans entered in the last 14 days (too fresh, front desk still working them) and older than 12 months (needs re-examination). That removes 205. 490 - 205 = 285 remaining.
Step 4 - value floor. The practice sets a floor of $300 in outstanding planned treatment per patient. 96 patients fall below it. 285 - 96 = 189 remaining.
Step 5 - consent and suppression. 22 patients have no mobile on file, have opted out, or sit on the practice's suppression list. 189 - 22 = 167 contactable patients.
So a 2,400-row report becomes 167 real conversations. Spread across a 12-week cadence to avoid flooding the front desk with returned calls, that is roughly 14 messages a week.
Now the part where honesty matters. The next line in most articles like this asserts a conversion rate and multiplies it by an average case value to produce an impressive number. We are not going to do that, because we have no defensible source for a treatment-plan-acceptance rate that would apply to your practice, and a fabricated one would be worse than useless - it would be the number you use to justify the project to your partner.
What you can do instead is bound it. Run the filtered list for one quarter. Record how many of the 167 book, and the produced value of what they book. That gives you a real conversion rate for your case mix, your fees and your patient base, and from the second quarter onward the forecast is arithmetic rather than hope. Track it as cost per booked job: total monthly cost of running the automation, divided by appointments it produced. If you want the general framework for that calculation before you have your own data, we set it out in AI agent ROI examples and in the broader AI automation cost breakdown.
One cost input you can pin down now: the messaging itself is cents per SMS, and the compute for a nightly paging job is trivial. The meaningful costs in this build are the developer key, the build time, and the front-desk time to handle the replies. That last one is real and routinely forgotten - 14 inbound calls a week is most of an hour.
The Build, Step by Step
The shape below assumes a scheduled workflow in something like n8n or equivalent. Nothing here requires an agent framework; it is a query, a filter and a send.
Step 1: Nightly trigger
A cron trigger at an hour when nobody is using the practice server. The throttle makes this a slow job by design, and overnight is where slow jobs belong.
Step 2: Page the procedure list
Call GET /procedurelogs filtered to ProcStatus TP. Remember the 100-item default hard limit and loop until you get a short page. Put a deliberate delay between requests sized to your permission tier - five seconds if you hold only ApiReadAll, one second otherwise. Do not rely on the API to pace you; pace yourself.
Step 3: Deduplicate to patients
Group by PatNum and sum planned value per patient. This is the step that saves you thousands of requests later, so do it before any enrichment.
Step 4: Check the appointment book
For the deduplicated patient set, call GET /appointments and drop anyone with a future booking. Cache this - it changes daily but not per-run.
Step 5: Apply the filter stack
Age, value floor, consent, suppression, in that order, cheapest filter first so you do less work downstream.
Step 6: Compose the message
This is the one place a language model earns a role, and only just. The message needs to reference the treatment in plain language without stating anything clinical that could be wrong, and without transmitting detail that does not need to travel over SMS. In practice the safest pattern is a template with a small number of variables and no free generation at all: the patient's first name, the practice name, a neutral phrase such as "treatment we discussed", and a booking link. If you do use a model to vary phrasing, constrain it to a fixed set of approved templates rather than letting it write from scratch, and keep a human in the loop for the first few weeks.
Step 7: Send, log, and handle replies
Send through your messaging provider, write a log row per patient with the date and the message ID, and route inbound replies to a real person. The log is what makes the run idempotent - without it, a job that crashes halfway and reruns will double-message the first half of your list. Suppress anyone contacted in the last N weeks by checking that log before sending, not after.
Step 8: Do not write back to the clinical record
Tempting, and almost always wrong for a first build. A note appended to a chart by an automation is a note a clinician has to read and trust. If the practice wants the contact history in Open Dental, agree the exact format with them first, and be aware that PUT /appointments/{AptNum}/Note appends to appointment notes rather than the clinical chart - a different thing with different expectations attached.
Robust error handling matters more here than in most builds, because the job runs unattended against a clinical system. A failed page should retry with backoff and then stop the run, not skip silently and send to a partial list.
Where This Goes Wrong
Five failure modes to plan for.
1. Messaging on the unfiltered list. Covered at length above. The symptom is a patient replying "I already had that done." The cause is almost always a missing already-scheduled check or a query that treated TPi as active.
2. Building it as a real-time integration. Somebody decides the automation should fire the moment a plan is entered. Now it runs during clinic hours, competes with the practice's own use of the system, hits the throttle, and messages patients who are still sitting in the car park. Batch it.
3. Requesting ApiReadAll because it is simpler. The five-second throttle is a documented, five-fold performance penalty for the convenient choice. Scope the permission request to the resources you actually named in your application.
4. Treating SMS compliance as someone else's problem. Carrier registration is not optional and not fast. Start it before the build, not after, and read the A2P 10DLC guide first.
5. No suppression file the practice controls. There will always be a patient who must not be contacted for a reason nobody wants to put in a database field. Give the front desk a spreadsheet they can add a name to, and read it on every run. Automations that cannot be overridden by the people who know the patients get switched off within a month.
There is a sixth, quieter one: building this and then not staffing the replies. The automation's output is inbound phone calls and texts to a front desk that is already busy. If nobody is assigned to them, the messages go out, the patients respond, and the practice looks worse than if it had never sent anything. Decide who owns the replies before you schedule the first run.
If you would rather have someone else own the throttle maths and the compliance paperwork, that is what our automation services engagements cover, and the free automation audit is the place to start if you want a scoped view of what is worth building in your practice before committing. For the wider picture of what else in a dental practice is automatable, the dental practice automation hub lays out the full set, and AI receptionist cost for a dental practice covers the adjacent phone-side build with market-typical ranges.
FAQ
- What ProcStatus value marks unscheduled treatment in Open Dental?
- Treatment-planned procedures carry a ProcStatus of "TP". Open Dental separately documents "TPi" for treatment plan inactive, "C" for complete, "EC" and "EO" for existing work by the current or another provider, "R" for referred out, "Cn" for a condition, and "D" for deleted. Filter on TP exactly - querying for anything that is not complete will pull in inactive plans and clinical findings.
- How does the Open Dental API authenticate?
- With a single header in the form `Authorization: ODFHIR {DeveloperKey}/{CustomerKey}`. The developer key identifies the integration, the customer key identifies the individual practice database. There is no OAuth flow or token refresh, which makes it simpler to build against than most practice management systems. The REST base URL is https://api.opendental.com/api/v1, which is separate from Open Dental's FHIR API.
- What is the Open Dental API rate limit?
- Open Dental documents that developers holding only the ApiReadAll permission have their customers' requests throttled to one request per five seconds. Holding any other API permission relaxes that to one request per second. Pacing is applied per customer key. Open Dental also states that excessive requests may lead to temporary suspension of access from the offending IP address or network, and ultimately permanent termination of access.
- How many records does the Open Dental API return per request?
- Open Dental's implementation documentation states that the limit is usually not specified and defaults to a hard limit of 100 items for any request. Any practice with a meaningful backlog of treatment-planned work therefore needs a paging loop, and that loop has to respect the throttle - which is what makes a full pass a slow, overnight job rather than an on-demand one.
- Do I need a BAA to build an Open Dental integration?
- Open Dental's API specification states that developers need a Business Associate Agreement in place with their clients. If you are an outside builder or agency, sign the BAA with the practice before you hold their customer key. A BAA under HIPAA is a specific instrument and is not interchangeable with a generic data processing agreement.
- How long does it take to get an Open Dental developer key?
- Open Dental's setup documentation says requests take one to three business days to process. The application asks for the integration owner's company name, contact phone, billing email, mailing address, a description of the application you intend to build, and the specific API resources you need along with the permission level on each one - read, create or update. Because permission scope affects your throttle tier, list resources deliberately rather than asking for blanket access.
- What does Open Dental charge for API access?
- Open Dental states on its API specification page that pricing tiers for API developers are available, referenced from its API permissions page. We have not verified the current figures and are not going to quote numbers we have not read at source - confirm pricing directly with Open Dental before budgeting, and treat any figure you find on a third-party blog, including a stale one on this site, as needing re-checking.
- Should an AI model write the follow-up messages?
- Mostly no. The safest pattern is a fixed template with a small number of variables - first name, practice name, a neutral reference to treatment previously discussed, and a booking link. Clinical detail should not be generated, and does not belong in an SMS anyway. If you do use a model, constrain it to selecting among approved templates rather than writing freely, and review output manually for the first several weeks.
If this resonated
Module 02 is the long version of this post.
Eval set, refusal pattern, kill switch. Build it in a weekend.
