Reading Patient Data via Open Dental API

If you need to pull patient information from your practice management software into a custom dashboard, third-party reporting tool, or internal application, you need to use the open dental API read patient data functionality. This allows you to securely retrieve patient demographics, contact information, and status directly from your database without manual exports.

Prerequisites

Before you can begin, you must ensure your practice is set up for API communication.

1. Developer Portal Access: You or your developer must have an account in the Open Dental Developer Portal. Contact vendor.relations@opendental.com to request access.
2. API Keys: You need two keys: a Developer API Key (provided by the portal) and a Customer API Key (generated in the portal and entered into the practice's Open Dental software).
3. eConnector: The practice must have the eConnector service installed and running. This service acts as the bridge between the Open Dental cloud and your local server.
4. Enable API: In Open Dental, go to Setup > Advanced Setup > API. Ensure the Enabled checkbox is checked and your Customer API Key is added.
5. Permissions: Ensure your API key has the necessary permissions to read patient data.

Implementation

The Open Dental API uses Basic Authentication. You will pass your Developer Key as the username and your Customer Key as the password in the Authorization header.

The base URL for the API is https://api.opendental.com/api/v1/.

Here is a simple example using Node.js to fetch a list of patients:

const axios = require('axios');

// Replace with your actual keys
const developerKey = 'YOUR_DEVELOPER_KEY';
const customerKey = 'YOUR_CUSTOMER_KEY';

const auth = Buffer.from(`${developerKey}:${customerKey}`).toString('base64');

async function getPatients() {
  try {
    const response = await axios.get('https://api.opendental.com/api/v1/patients', {
      headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error('Error fetching patients:', error.message);
  }
}

getPatients();

Fetching a Single Patient

To get details for a specific patient, append their PatNum to the URL:
GET https://api.opendental.com/api/v1/patients/123

Common Errors

• 401 Unauthorized: This usually means your API keys are incorrect, or the Customer API Key has been disabled in the Setup > Advanced Setup > API window.
• 400 BadRequest: Often indicates the eConnector is not running or is unable to communicate with the Open Dental server. Check the eConnector status in the Manage Module or via the Windows Service Manager.
• 504 Gateway Time-out: The request took longer than 60 seconds to process. This can happen if you are requesting a very large dataset. Try using pagination (the Offset and Limit parameters) to break the request into smaller chunks.

Limitations

• Rate Limits: Requests are throttled. If you only have "Read All" permissions, you are limited to 1 request every 5 seconds. Higher tiers (like those including ApiComm) allow for 1 request per second.
• Data Restrictions: You cannot delete patients via the API.
• Pagination: When requesting lists, the API returns a maximum of 100 items per request. You must use the Offset parameter to retrieve subsequent pages of data.

Don't want to build your own dashboard? DentalCanvas already connects to your Open Dental data and shows you everything in a visual interface.

This article is provided by opendentalsupport.com, an independent community resource. We are not affiliated with Open Dental Software, Inc.