Doctofam API 1.0.0
Public REST API for Doctofam. Authenticate with an API key created in the Doctofam dashboard: send the base64-encoded key secret with HTTP Basic auth. Each key carries per-resource scopes like patients:read or appointments:write.
https://api.doctofam.com
apiKey— HTTP Basic auth carrying only the API key secret:Authorization: Basic base64(<key secret>).accessToken— Operator session token issued by the Doctofam dashboard:Authorization: Token <access token>.
Appointments
GET/api/appointments
List appointments
Lists the appointments of your clinic. Requires the appointments:read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
clinicId |
query | string | |
patientId |
query | string | |
startTime |
query | string | |
endTime |
query | string | |
fields |
query | string | Comma-separated projection of fields to return |
Responses
| Status | Meaning |
|---|---|
200 | Array of appointments |
401 | Missing or invalid credentials |
403 | API key is missing the appointments:read scope |
429 | API key rate limit exceeded |
POST/api/appointments
Create an appointment
Creates an appointment in your clinic and emits appointment.created to your webhook subscriptions. Requires the appointments:write scope.
Responses
| Status | Meaning |
|---|---|
200 | The created appointment |
403 | API key is missing the appointments:write scope |
GET/api/appointments/{appointmentId}
Get an appointment by id
Returns a single appointment owned by your clinic. Requires the appointments:read scope. Answers 404 for an appointment in another organization so ids cannot be probed.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
appointmentId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The appointment |
403 | API key is missing the appointments:read scope |
404 | No such appointment in your organization |
Clinics
GET/api/clinics
List clinics
Lists the clinics of your organization. Requires the clinics:read scope.
Responses
| Status | Meaning |
|---|---|
200 | Array of clinics |
401 | Missing or invalid credentials |
403 | API key is missing the clinics:read scope |
429 | API key rate limit exceeded |
GET/api/clinics/{clinicId}
Get a clinic by id
Returns a single clinic. Credentials are optional: the clinic's public website already serves every field, so an anonymous caller gets the same record. An authenticated caller needs the clinics:read scope and gets 404 for a clinic in another organization so ids cannot be probed.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
clinicId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The clinic |
403 | API key is missing the clinics:read scope |
404 | No such clinic in your organization |
Invoices
GET/api/invoices
List invoices
Lists the invoices of your clinic. Requires the invoices:read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
clinicId |
query | string | |
patientId |
query | string | |
fields |
query | string | Comma-separated projection of fields to return |
Responses
| Status | Meaning |
|---|---|
200 | Array of invoices |
401 | Missing or invalid credentials |
403 | API key is missing the invoices:read scope |
429 | API key rate limit exceeded |
POST/api/invoices
Create an invoice
Creates an invoice in your clinic and emits invoice.created to your webhook subscriptions. Requires the invoices:write scope.
Responses
| Status | Meaning |
|---|---|
200 | The created invoice |
403 | API key is missing the invoices:write scope |
GET/api/invoices/{invoiceId}
Get an invoice by id
Returns a single invoice owned by your clinic. Requires the invoices:read scope. Answers 404 for an invoice in another organization so ids cannot be probed.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
invoiceId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The invoice |
403 | API key is missing the invoices:read scope |
404 | No such invoice in your organization |
Patients
GET/api/patients
List patients
Lists the patients of your clinic. Requires the patients:read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
clinicId |
query | string | |
email |
query | string | |
fields |
query | string | Comma-separated projection of fields to return |
Responses
| Status | Meaning |
|---|---|
200 | Array of patients |
401 | Missing or invalid credentials |
403 | API key is missing the patients:read scope |
429 | API key rate limit exceeded |
POST/api/patients
Create a patient
Creates a patient in your clinic and emits patient.created to your webhook subscriptions. Requires the patients:write scope.
Responses
| Status | Meaning |
|---|---|
200 | The created patient |
403 | API key is missing the patients:write scope |
GET/api/patients/{patientId}
Get a patient by id
Returns a single patient owned by your clinic. Requires the patients:read scope. Answers 404 for a patient in another organization so ids cannot be probed.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
patientId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The patient |
403 | API key is missing the patients:read scope |
404 | No such patient in your organization |
Payments
GET/api/payments
List payments
Lists the payments of your clinic. Requires the payments:read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
clinicId |
query | string | |
patientId |
query | string | |
fields |
query | string | Comma-separated projection of fields to return |
Responses
| Status | Meaning |
|---|---|
200 | Array of payments |
401 | Missing or invalid credentials |
403 | API key is missing the payments:read scope |
429 | API key rate limit exceeded |
POST/api/payments
Create a payment
Records a payment in your clinic and emits payment.created to your webhook subscriptions. Requires the payments:write scope.
Responses
| Status | Meaning |
|---|---|
200 | The created payment |
403 | API key is missing the payments:write scope |
GET/api/payments/{paymentId}
Get a payment by id
Returns a single payment owned by your clinic. Requires the payments:read scope. Answers 404 for a payment in another organization so ids cannot be probed.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
paymentId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The payment |
403 | API key is missing the payments:read scope |
404 | No such payment in your organization |
Procedures
GET/api/procedures
List procedures
Lists your clinic's procedure/treatment catalog. Requires the procedures:read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
clinicId |
query | string | |
fields |
query | string | Comma-separated projection of fields to return |
Responses
| Status | Meaning |
|---|---|
200 | Array of procedures |
401 | Missing or invalid credentials |
403 | API key is missing the procedures:read scope |
429 | API key rate limit exceeded |
POST/api/procedures
Create a procedure
Adds a procedure to your clinic's catalog. Requires the procedures:write scope.
Responses
| Status | Meaning |
|---|---|
200 | The created procedure |
403 | API key is missing the procedures:write scope |
GET/api/procedures/{procedureId}
Get a procedure by id
Returns a single procedure owned by your clinic. Requires the procedures:read scope. Answers 404 for a procedure in another organization so ids cannot be probed.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
procedureId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The procedure |
403 | API key is missing the procedures:read scope |
404 | No such procedure in your organization |
Webhook subscriptions
GET/api/webhooksubscriptions
List webhook subscriptions
Webhook subscriptions deliver patient.created, appointment.created, invoice.created and payment.created events (and their .updated / .deleted variants) to your server as signed POST requests (X-Doctofam-Signature: t=<timestamp>,v1=<hex HMAC-SHA256 of "timestamp.body">). An endpoint failing 20 times in a row is disabled automatically. Subscriptions are managed with an operator access token; the secret is only returned once, on create.
Responses
| Status | Meaning |
|---|---|
200 | Array of webhook subscriptions (without secrets) |
POST/api/webhooksubscriptions
Create a webhook subscription
The response includes the signing secret exactly once — store it; it cannot be retrieved again.
Request body application/json
| Field | Type | Description |
|---|---|---|
clinicId required |
string | |
url required |
string | |
events |
array | Empty array subscribes to all events |
Responses
| Status | Meaning |
|---|---|
200 | The created subscription, including its secret |
PUT/api/webhooksubscriptions/{webhookSubscriptionId}
Update a webhook subscription
url, events and active are editable; the secret and clinic are immutable. Re-enabling an auto-disabled endpoint is done by setting active back to true.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhookSubscriptionId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The updated subscription (without secret) |
DELETE/api/webhooksubscriptions/{webhookSubscriptionId}
Delete a webhook subscription
Delete a webhook subscription
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhookSubscriptionId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | Deleted |