● Introduction

DocMeIn API enables developers and integrators to build applications and application extensions to interact with the DocMeIn platform. Although we make no assumptions about the nature of your application and its use of the DocMeIn platform, the primary use cases targeted by the API are as follows:

• scheduling of appointments by patients with their providers;
• management of patient data by patients and by their providers;
• management of appointments by providers.

With these use cases, we provide coverage for the vast majority of requests we received to date, including from vendors of PHR, EHR, EMR, PMS, e-Rx and various other packaged systems, Web and mobile applications. Our API is still a work in progress and we look forward to your feedback and suggestions.

---

● Protocol

● Authentication

DocMeIn API endpoints support authentication via HTTP’s basic authentication scheme as per RFC 2617. Users’ DocMeIn credentials are thus required in order to access the API. In the future, DocMeIn may support other authentication methods, which do not require the users’ DocMeIn credentials to be known by API clients. Authentication is required for all calls involving account access, but not for the calls exposing published provider data and designated scheduling availability.

● Messaging

DocMeIn API makes extensive use of HTTP protocol features, including various HTTP response codes and headers. API clients must be configured to auto-follow all redirects, correctly processing authentication challenges, media type ("application/json") selection, payload compression and caching-related headers.

● Formats

All DocMeIn requests and responses are based on the JSON encoding notation. Date values are represented as strings in YYYY-MM-DD format. Time values are represented in epoch form (seconds since 1/1/1970 midnight UTC). In addition, relevant timezone is often supplied alongside the time value.

● Error Reporting

DocMeIn API produces HTTP status codes consistent with the HTTP 1.1 specification. Specific response codes that the API client must be prepared to process are 200, 201, 204, 302, 401, 404, 405 and 500. The latter signals that an error occurred in processing an API request. Response body in this case contains an informational message to aid in the diagnostics of the error condition.

● Resources

● Patient

Example:

						
{
    "id": "1234567890987654321",

    "name": "Nicole Mary Kidman",
    "email": "nickid@gmail.com",
    "address": "65536 Santa Monica Blvd, Beverly Hills, CA 90035, USA",
    "phones": [
		{
		"type": "mobile",
		"number": "(650) 555-1212"
		}
	]
}
						
						

● Provider

Example:

						
{
    "id": "1234567890987654321",
    "name": "Dr. Sanjay Gupta",
    "description": "Dr. Gupta is Bay Area’s #1 optometrist serving the community since 1976.",
    "location": {
	"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
	"lat": 37.4219720,
	"lng": -122.0841430,
	"phone": "(650) 555-1212",
	"timezone": "America/Pacific",        // Olson database key
    },
    "gender": "male",
    "languages": ["English", "Hindi"],
    "training": [
        {
            "school": "Southern California College of Optometry",
            "concentrations": ["Optometry"],
            "class_year": 1976
        }
    ],
    "accepting_new_patients": true,
    "services":
	[
        {
            "id": "123456",
            "name": "Comprehensive Eye Exam",
            "uri": "https://api.docmein.com/services/123456"
        },
        {
            "id": "456789",
            "name": "Contact Lens Check",
            "uri": "https://api.docmein.com/services/456789"
        }
	],
    "insurance_options": ["Aetna", "BCBS", "CIGNA", "VSP"],
    "brands": ["Carrera", "Emporio Armani", "GUCCI", "Georgio Armani", "Juicy Couture", "Theory", "Valentino"],
    "html": "http://www.docmein.com/app/page/13772936973016",
    "schedule": "http://www.docmein.com/13772936973016/schedule",
    "hours": "https://api.docmein.com/13772936973016/hours",
    "availability": "https://api.docmein.com/13772936973016/availability",
    "appointments": "https://api.docmein.com/appointments",
    "patients": "https://api.docmein.com/patients"
}
						
						

● Appointment

Example:

						
{
    "when": 1315249200,        // epoch time
    "duration": 1800000,        // 30 minutes
    "service": {
		"id": "123456",
		"name": "Contact Lens Check",
		"uri": "https://api.docmein.com/services/123456"
	},
    "provider": {
		"id": "1234567890987654321",
		"name": "Dr. Sanjay Gupta",
		"uri": "https://api.docmein.com/providers/1234567890987654321"
	},
    "patient": {
		"id": "1234567890987654321",
		"name": "Nicole Mary Kidman",
		"uri": "https://api.docmein.com/patients/1234567890987654321"
	},
	"status": "created"
}
						
						

Valid values of appointment status are:

• "created"
• "confirmed"
• "requested"
• "accepted"
• "rejected"
• "canceled"
• "canceled-late"
• "noshow"
• "passed"
• "checked-in"
• "checked-out"

If omitted on input, appointment status defaults to "created".

● Service

Example:

						
{
	"id": "123456",
	"uri": "https://api.docmein.com/services/123456",
	"name": "Contact Lens Check",
	"duration": 1800000,        // 30 minutes
	"prePad": 600000,                // 10 minutes
	"postPad": 900000                // 20 minutes
}
						
						

● Schedule

The representation of the provider’s schedule, including the repeating pattern of days on and off and the hours for the days on, as well as any exceptions to this repeating pattern.

Example:

						
{
 "recurring": [
   {
     "date": "2014-04-01",
     "hours": [
                {
                  "from": "9:00AM",
                  "to": "1:00PM"
                },
                {
                  "from": "2:00PM",
                  "to": "6:00PM"
                }
          ]
        },
        {
          "date": "2014-04-02",
         "hours": [
                {
                  "from": "9:00AM",
                  "to": "1:00PM"
                },
                {
                  "from": "2:00PM",
                  "to": "6:00PM"
                }
          ]
        },
        {...},{...},{...},{...},{...}
 ],
 "nonrecurring": [
         {
          "date": "2014-04-01",
          "hours": []
        },
        {
          "date": "2015-04-01",
          "hours": [
            {
              "from": "1:00PM",
              "to": "4:00PM"
            },
            {
              "from": "4:30PM",
              "to": "7:00PM"
            }
          ]
        }
 ]
}						
						

The entity contains two major properties: recurring and nonrecurring. Each of them contains a date property and an hours array, specifying the provider's scheduled time for "date" as ordered time intervals.

The intervals under recurring repeat every recurring.length() number of days. The schedule on recurring[i]+recurring.length()*n, where n is an arbitrary natural number, is therefore the same as it is on recurring[i]. In current API version, recurring.length() other than 7 is considered an error on input, but API clients should be prepared to accept any value of recurring.length(). All date properties in the recurring block appear in sequential order and constitute consecutive days.

The intervals under nonrecurring represent exceptions from the regular schedule. There may be an arbitrary number of such exceptions, including deviations from regular posted hours, no hours at all on a day would otherwise have hours scheduled or vice versa.
The format of hours is an array, designating consecutive time bounds via each of its element's from and to properties. They specify the start and the end time of the scheduled time interval in the provider's time zone. The precision and appropriate bounds at which time may be specified depends on account settings. The time designated by these from-to ranges can never overlap; all time that falls outside the from-to ranges is considered unavailable for appointment scheduling. If no hours are scheduled on a particular date, the hours array for the corresponding date is empty.

● Hours

JSON array of daily working hours for a provider. Each array element is as follows:

						
{
	"date": "2013-04-29",
	"from": "9:00AM",
	"to": "6:00PM"
}						
						

● Availability

JSON array of dates for which the provider has real-time scheduling availability. Each array element is as follows:

						
{
	"date": "2011-10-12"
	"inventory": "https://api.docmein.com/providers/1234567890987654321/inventory?date=2011-10-12"
}
						
						

● Inventory

JSON array of time values representing available appointment starting times.

---

● Operations

● Provider

Multi-Provider Self Discovery

Single-Provider Self Discovery

Add Provider

Update Provider

Remove Provider

Retrieve Provider’s Schedule

Update Provider’s Schedule

● Services

Retrieve Practice Services

Retrieve Service Details

Create Service

Update Service

Delete Service

● Appointments

Retrieve Appointments

Add Appointment

Update Appointment

● Patients

Retrieve Patients

Add Patient

Update Patient

● Patient Self-Scheduling

Obtain Schedule

Find Available Days

Find Available Appointments