Book an appointment
curl --request POST \
--url https://api.maxcare.ai/v4/appointments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Organization-Id: <x-organization-id>' \
--data '
{
"patientId": "<string>",
"providerId": "<string>",
"facilityId": "<string>",
"appointmentTypeId": "<string>",
"startsAt": "2026-08-03T08:00:00-04:00",
"durationMinutes": 15,
"newPatient": true,
"visitReasonId": "<string>",
"holdId": "<string>",
"templateId": "<string>",
"notes": "Patient comment text",
"reasonForVisit": "Changing mole on left forearm, referred for evaluation",
"referringProviderNpi": "1255374757"
}
'import requests
url = "https://api.maxcare.ai/v4/appointments"
payload = {
"patientId": "<string>",
"providerId": "<string>",
"facilityId": "<string>",
"appointmentTypeId": "<string>",
"startsAt": "2026-08-03T08:00:00-04:00",
"durationMinutes": 15,
"newPatient": True,
"visitReasonId": "<string>",
"holdId": "<string>",
"templateId": "<string>",
"notes": "Patient comment text",
"reasonForVisit": "Changing mole on left forearm, referred for evaluation",
"referringProviderNpi": "1255374757"
}
headers = {
"X-Organization-Id": "<x-organization-id>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Organization-Id': '<x-organization-id>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
patientId: '<string>',
providerId: '<string>',
facilityId: '<string>',
appointmentTypeId: '<string>',
startsAt: '2026-08-03T08:00:00-04:00',
durationMinutes: 15,
newPatient: true,
visitReasonId: '<string>',
holdId: '<string>',
templateId: '<string>',
notes: 'Patient comment text',
reasonForVisit: 'Changing mole on left forearm, referred for evaluation',
referringProviderNpi: '1255374757'
})
};
fetch('https://api.maxcare.ai/v4/appointments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.maxcare.ai/v4/appointments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'patientId' => '<string>',
'providerId' => '<string>',
'facilityId' => '<string>',
'appointmentTypeId' => '<string>',
'startsAt' => '2026-08-03T08:00:00-04:00',
'durationMinutes' => 15,
'newPatient' => true,
'visitReasonId' => '<string>',
'holdId' => '<string>',
'templateId' => '<string>',
'notes' => 'Patient comment text',
'reasonForVisit' => 'Changing mole on left forearm, referred for evaluation',
'referringProviderNpi' => '1255374757'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Organization-Id: <x-organization-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.maxcare.ai/v4/appointments"
payload := strings.NewReader("{\n \"patientId\": \"<string>\",\n \"providerId\": \"<string>\",\n \"facilityId\": \"<string>\",\n \"appointmentTypeId\": \"<string>\",\n \"startsAt\": \"2026-08-03T08:00:00-04:00\",\n \"durationMinutes\": 15,\n \"newPatient\": true,\n \"visitReasonId\": \"<string>\",\n \"holdId\": \"<string>\",\n \"templateId\": \"<string>\",\n \"notes\": \"Patient comment text\",\n \"reasonForVisit\": \"Changing mole on left forearm, referred for evaluation\",\n \"referringProviderNpi\": \"1255374757\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Organization-Id", "<x-organization-id>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.maxcare.ai/v4/appointments")
.header("X-Organization-Id", "<x-organization-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"patientId\": \"<string>\",\n \"providerId\": \"<string>\",\n \"facilityId\": \"<string>\",\n \"appointmentTypeId\": \"<string>\",\n \"startsAt\": \"2026-08-03T08:00:00-04:00\",\n \"durationMinutes\": 15,\n \"newPatient\": true,\n \"visitReasonId\": \"<string>\",\n \"holdId\": \"<string>\",\n \"templateId\": \"<string>\",\n \"notes\": \"Patient comment text\",\n \"reasonForVisit\": \"Changing mole on left forearm, referred for evaluation\",\n \"referringProviderNpi\": \"1255374757\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.maxcare.ai/v4/appointments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"patientId\": \"<string>\",\n \"providerId\": \"<string>\",\n \"facilityId\": \"<string>\",\n \"appointmentTypeId\": \"<string>\",\n \"startsAt\": \"2026-08-03T08:00:00-04:00\",\n \"durationMinutes\": 15,\n \"newPatient\": true,\n \"visitReasonId\": \"<string>\",\n \"holdId\": \"<string>\",\n \"templateId\": \"<string>\",\n \"notes\": \"Patient comment text\",\n \"reasonForVisit\": \"Changing mole on left forearm, referred for evaluation\",\n \"referringProviderNpi\": \"1255374757\"\n}"
response = http.request(request)
puts response.read_body{
"code": "success",
"data": {
"appointment": {
"id": "apt_e5f6a7b8c9d04e1f2a3b4c5d6e7f8a9b",
"externalId": null,
"patientId": "pat_c56103bcd39c46d39f3138dd2b5e05f6",
"providerId": "prv_35103413aaaa4bbbccccddddeeeeffff",
"facilityId": "fac_2706aaaa4bbbccccddddeeeeffff1111",
"appointmentTypeId": "atp_1c0f8a2b4d5e4f6a8b9c0d1e2f3a4b5c",
"visitReasonId": "<string>",
"startsAt": "2026-08-03T08:00:00-04:00",
"durationMinutes": 15,
"status": "scheduled",
"syncStatus": "pending",
"newPatient": true,
"notes": "<string>",
"reasonForVisit": "<string>",
"referringProviderNpi": "<string>",
"source": {
"system": "dcc-online-booking",
"bookingReference": "BK-2026-000123",
"campaignId": "google-gbp-flint",
"url": "https://book.dccderm.com/l/flint?utm_source=gbp"
},
"createdAt": "2026-07-26T13:00:00.000Z",
"writtenBy": {
"resolvedBy": "personal_connector"
}
},
"idempotentReplay": true,
"meta": {
"actingAs": "user",
"resolvedBy": "personal_connector"
}
}
}{
"code": "success",
"data": {
"appointment": {
"id": "apt_e5f6a7b8c9d04e1f2a3b4c5d6e7f8a9b",
"externalId": null,
"patientId": "pat_c56103bcd39c46d39f3138dd2b5e05f6",
"providerId": "prv_35103413aaaa4bbbccccddddeeeeffff",
"facilityId": "fac_2706aaaa4bbbccccddddeeeeffff1111",
"appointmentTypeId": "atp_1c0f8a2b4d5e4f6a8b9c0d1e2f3a4b5c",
"visitReasonId": "<string>",
"startsAt": "2026-08-03T08:00:00-04:00",
"durationMinutes": 15,
"status": "scheduled",
"syncStatus": "pending",
"newPatient": true,
"notes": "<string>",
"reasonForVisit": "<string>",
"referringProviderNpi": "<string>",
"source": {
"system": "dcc-online-booking",
"bookingReference": "BK-2026-000123",
"campaignId": "google-gbp-flint",
"url": "https://book.dccderm.com/l/flint?utm_source=gbp"
},
"createdAt": "2026-07-26T13:00:00.000Z",
"writtenBy": {
"resolvedBy": "personal_connector"
}
},
"idempotentReplay": true,
"meta": {
"actingAs": "user",
"resolvedBy": "personal_connector"
}
}
}{
"code": "bad_request",
"message": "'id' must be a valid UUID",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "unauthorized",
"message": "Invalid or missing API key",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "forbidden",
"message": "Insufficient scope",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "not_found",
"message": "Resource not found",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "conflict",
"message": "Cannot edit a signed note",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "unexpected_integration_error",
"message": "EHR sync failed",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "server_unresponsive",
"message": "EHR integration is not available for this note",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}Appointments
Book an appointment
Accepts a booking. The EHR write is asynchronous (changed deliberately — see below): a 202 with syncStatus: "pending" means the slot is RESERVED against everyone else booking through Max AI and the appointment is durably recorded, but it is NOT on the practice’s calendar yet and externalId is null. Completion is reported by webhook: appointment.confirmed (written; externalId now known), appointment.rejected (the slot went away — the event carries suggestedSlots, so offer those rather than restarting the flow), or appointment.write_failed (could not be written after retries). Polling GET /appointments/{id} works too. Do not tell a patient they are booked on this response alone. This previously returned 201 after a synchronous write, which made a slow tenant a slow booking form and a vendor outage a booking outage. Booking now succeeds while the EHR is unreachable. Send an Idempotency-Key header — it is honoured for 24 hours per app+organization, and a completed request replays its result with idempotentReplay: true. If acceptance could not be confirmed, the same key remains protected for that period and returns 409 ehr_write_uncertain with requiresReconciliation: true; verify the booking before creating another. The guarantee FAILS CLOSED: if the idempotency store is unreachable the request is refused with 503 idempotency_unavailable and nothing is sent to the EHR, rather than proceeding with the guarantee silently withdrawn. That response is safe to retry without checking for a duplicate first. To accept at-least-once delivery instead, omit the header. Returns 409 slot_unavailable when capacity went away, 409 hold_expired when the supplied hold lapsed, and 503 no_booking_identity when the organization has no system connector for unattended writes.
POST
/
appointments
Book an appointment
curl --request POST \
--url https://api.maxcare.ai/v4/appointments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Organization-Id: <x-organization-id>' \
--data '
{
"patientId": "<string>",
"providerId": "<string>",
"facilityId": "<string>",
"appointmentTypeId": "<string>",
"startsAt": "2026-08-03T08:00:00-04:00",
"durationMinutes": 15,
"newPatient": true,
"visitReasonId": "<string>",
"holdId": "<string>",
"templateId": "<string>",
"notes": "Patient comment text",
"reasonForVisit": "Changing mole on left forearm, referred for evaluation",
"referringProviderNpi": "1255374757"
}
'import requests
url = "https://api.maxcare.ai/v4/appointments"
payload = {
"patientId": "<string>",
"providerId": "<string>",
"facilityId": "<string>",
"appointmentTypeId": "<string>",
"startsAt": "2026-08-03T08:00:00-04:00",
"durationMinutes": 15,
"newPatient": True,
"visitReasonId": "<string>",
"holdId": "<string>",
"templateId": "<string>",
"notes": "Patient comment text",
"reasonForVisit": "Changing mole on left forearm, referred for evaluation",
"referringProviderNpi": "1255374757"
}
headers = {
"X-Organization-Id": "<x-organization-id>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Organization-Id': '<x-organization-id>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
patientId: '<string>',
providerId: '<string>',
facilityId: '<string>',
appointmentTypeId: '<string>',
startsAt: '2026-08-03T08:00:00-04:00',
durationMinutes: 15,
newPatient: true,
visitReasonId: '<string>',
holdId: '<string>',
templateId: '<string>',
notes: 'Patient comment text',
reasonForVisit: 'Changing mole on left forearm, referred for evaluation',
referringProviderNpi: '1255374757'
})
};
fetch('https://api.maxcare.ai/v4/appointments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.maxcare.ai/v4/appointments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'patientId' => '<string>',
'providerId' => '<string>',
'facilityId' => '<string>',
'appointmentTypeId' => '<string>',
'startsAt' => '2026-08-03T08:00:00-04:00',
'durationMinutes' => 15,
'newPatient' => true,
'visitReasonId' => '<string>',
'holdId' => '<string>',
'templateId' => '<string>',
'notes' => 'Patient comment text',
'reasonForVisit' => 'Changing mole on left forearm, referred for evaluation',
'referringProviderNpi' => '1255374757'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Organization-Id: <x-organization-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.maxcare.ai/v4/appointments"
payload := strings.NewReader("{\n \"patientId\": \"<string>\",\n \"providerId\": \"<string>\",\n \"facilityId\": \"<string>\",\n \"appointmentTypeId\": \"<string>\",\n \"startsAt\": \"2026-08-03T08:00:00-04:00\",\n \"durationMinutes\": 15,\n \"newPatient\": true,\n \"visitReasonId\": \"<string>\",\n \"holdId\": \"<string>\",\n \"templateId\": \"<string>\",\n \"notes\": \"Patient comment text\",\n \"reasonForVisit\": \"Changing mole on left forearm, referred for evaluation\",\n \"referringProviderNpi\": \"1255374757\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Organization-Id", "<x-organization-id>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.maxcare.ai/v4/appointments")
.header("X-Organization-Id", "<x-organization-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"patientId\": \"<string>\",\n \"providerId\": \"<string>\",\n \"facilityId\": \"<string>\",\n \"appointmentTypeId\": \"<string>\",\n \"startsAt\": \"2026-08-03T08:00:00-04:00\",\n \"durationMinutes\": 15,\n \"newPatient\": true,\n \"visitReasonId\": \"<string>\",\n \"holdId\": \"<string>\",\n \"templateId\": \"<string>\",\n \"notes\": \"Patient comment text\",\n \"reasonForVisit\": \"Changing mole on left forearm, referred for evaluation\",\n \"referringProviderNpi\": \"1255374757\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.maxcare.ai/v4/appointments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"patientId\": \"<string>\",\n \"providerId\": \"<string>\",\n \"facilityId\": \"<string>\",\n \"appointmentTypeId\": \"<string>\",\n \"startsAt\": \"2026-08-03T08:00:00-04:00\",\n \"durationMinutes\": 15,\n \"newPatient\": true,\n \"visitReasonId\": \"<string>\",\n \"holdId\": \"<string>\",\n \"templateId\": \"<string>\",\n \"notes\": \"Patient comment text\",\n \"reasonForVisit\": \"Changing mole on left forearm, referred for evaluation\",\n \"referringProviderNpi\": \"1255374757\"\n}"
response = http.request(request)
puts response.read_body{
"code": "success",
"data": {
"appointment": {
"id": "apt_e5f6a7b8c9d04e1f2a3b4c5d6e7f8a9b",
"externalId": null,
"patientId": "pat_c56103bcd39c46d39f3138dd2b5e05f6",
"providerId": "prv_35103413aaaa4bbbccccddddeeeeffff",
"facilityId": "fac_2706aaaa4bbbccccddddeeeeffff1111",
"appointmentTypeId": "atp_1c0f8a2b4d5e4f6a8b9c0d1e2f3a4b5c",
"visitReasonId": "<string>",
"startsAt": "2026-08-03T08:00:00-04:00",
"durationMinutes": 15,
"status": "scheduled",
"syncStatus": "pending",
"newPatient": true,
"notes": "<string>",
"reasonForVisit": "<string>",
"referringProviderNpi": "<string>",
"source": {
"system": "dcc-online-booking",
"bookingReference": "BK-2026-000123",
"campaignId": "google-gbp-flint",
"url": "https://book.dccderm.com/l/flint?utm_source=gbp"
},
"createdAt": "2026-07-26T13:00:00.000Z",
"writtenBy": {
"resolvedBy": "personal_connector"
}
},
"idempotentReplay": true,
"meta": {
"actingAs": "user",
"resolvedBy": "personal_connector"
}
}
}{
"code": "success",
"data": {
"appointment": {
"id": "apt_e5f6a7b8c9d04e1f2a3b4c5d6e7f8a9b",
"externalId": null,
"patientId": "pat_c56103bcd39c46d39f3138dd2b5e05f6",
"providerId": "prv_35103413aaaa4bbbccccddddeeeeffff",
"facilityId": "fac_2706aaaa4bbbccccddddeeeeffff1111",
"appointmentTypeId": "atp_1c0f8a2b4d5e4f6a8b9c0d1e2f3a4b5c",
"visitReasonId": "<string>",
"startsAt": "2026-08-03T08:00:00-04:00",
"durationMinutes": 15,
"status": "scheduled",
"syncStatus": "pending",
"newPatient": true,
"notes": "<string>",
"reasonForVisit": "<string>",
"referringProviderNpi": "<string>",
"source": {
"system": "dcc-online-booking",
"bookingReference": "BK-2026-000123",
"campaignId": "google-gbp-flint",
"url": "https://book.dccderm.com/l/flint?utm_source=gbp"
},
"createdAt": "2026-07-26T13:00:00.000Z",
"writtenBy": {
"resolvedBy": "personal_connector"
}
},
"idempotentReplay": true,
"meta": {
"actingAs": "user",
"resolvedBy": "personal_connector"
}
}
}{
"code": "bad_request",
"message": "'id' must be a valid UUID",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "unauthorized",
"message": "Invalid or missing API key",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "forbidden",
"message": "Insufficient scope",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "not_found",
"message": "Resource not found",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "conflict",
"message": "Cannot edit a signed note",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "unexpected_integration_error",
"message": "EHR sync failed",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "server_unresponsive",
"message": "EHR integration is not available for this note",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}Authorizations
Marketplace API key
Headers
Client-generated UUID. Strongly recommended: on a live calendar a duplicate appointment is worse than a slow response. Sending it is also a request for exactly-once — if that cannot be honoured the write is refused (503 idempotency_unavailable) rather than downgraded.
The App Bridge token of the logged-in user (maxcare.appToken()), verified for this app and organization. With it the change is made through that user's own EHR login when they have a usable one; without it, through the organization's system login (meta.resolvedBy says which). A token that does not verify is 401 authorizer_unverified. Sent as a header so it stays out of URLs.
Target clinic organization ID
Body
application/json
Patient ID (pat_…)
Provider ID (prv_…)
Facility ID (fac_…)
Appointment type ID (atp_…)
Start instant, ISO-8601 with an explicit offset
Example:
"2026-08-03T08:00:00-04:00"
Appointment length in minutes
Example:
15
Whether this is a new-patient visit. Both EHRs distinguish it, and it changes the EHR-side workflow.
Example:
true
Visit reason ID (vrs_…). Only meaningful on EHRs where /visit-reasons reports supported: true.
Hold ID (hld_…) taken from POST /schedule/holds
Availability template ID (avt_…) from the chosen slot's templateIds. On ModMed this pins the appointment to that calendar preference so it consumes the right window's capacity.
Patient-supplied comment
Example:
"Patient comment text"
Why the patient is being seen, written to the EHR's own reason-for-visit field (never to notes). ModMed only: check reasonForVisit on GET /schedule/capabilities; other EHRs refuse it with capability_unsupported.
Maximum string length:
2000Example:
"Changing mole on left forearm, referred for evaluation"
NPI of the referring provider, attached to the appointment as its referral. ModMed only (see referringProviderNpi on GET /schedule/capabilities). On ModMed the NPI is added to the practice's referral directory from the NPI registry when missing; an NPI that cannot be resolved does not fail the booking, it is booked without one.
Pattern:
^\d{10}$Example:
"1255374757"
Booking attribution, echoed back on read. Use this instead of prefixing appointment notes — notes are a clinical field and get read aloud at check-in.
Show child attributes
Show child attributes