Resources

Review all resources and construct a context map to ensure seamless mapping during integration.
Some objects can be modified via the Docplanner interface. Monitor the state of mapped resources regularly.

Introduction
API resources in Docplanner serve as the foundation for integrating with our system. While resource identifiers are generally stable, they can change over time due to actions performed either via the API or the Docplanner interface. For example, if a doctor modifies services on their profile (e.g., deletes a service and adds an identical one), the identifier will change even if this is not reflected visually in the interface.
Monitor resource states
To maintain integration stability, consistently monitor the status of all mapped resources.
We recommend building a context map using our template to gain clear understanding of object relationships within the platform. You can also preview a visual representation below:

This article details all resources available via API, including both business and technical contexts.
Facilities
A facility is the primary object in the API, representing a clinic profile on the Docplanner marketplace. To access our API, a customer must have a valid clinic profile. Each facility has a unique identifier (facility ID), which is required for every API call involving this entity.
After successful authorization (learn more), you will be able to access the facilities connected to your API client. These facilities are assigned manually by the Docplanner team upon a written request from the customer.
API access is limited to authorized Docplanner customers
Currently, our API does not provide global access to resources across the entire marketplace. Each partner is granted access only to resources for clinics or customers who have provided express authorization.
There is no restriction on the number of facilities per API client—one client can manage one, several, or a network/chain of facilities. Although a facility may have multiple locations, this detail is abstracted in the API to a single facility ID; the distinction between locations occurs at the doctor's address level.
For more on addresses, see the doctor addresses section >>.
Facilities in Docplanner represent the organizational structure of medical entities such as hospitals, clinics, or offices, and serve as aggregators for doctors displayed on the clinic's profile.
You can preview a sample clinic profile here >>.
To retrieve all your facilities, use the getFacilities
endpoint. Technical documentation can be found here.
Doctors
A doctor entity represents a healthcare professional working at a clinic.
Once you have the facility_id, you can obtain further details necessary for the integration, starting with fetching the list of doctors associated with the facility. Note the following restrictions:
- The doctor must be a commercial (paid) Docplanner client. Non-paid professionals are not returned via the API.
- The doctor must be linked to the facility.
If you notice fewer doctors returned than expected, refer to the FAQ for troubleshooting.
To retrieve all available doctors, use the getDoctors
endpoint as documented here.
Addresses
An address acts as a unique identifier for a specific doctor's presence at a facility and is one of the most granular entities in the Docplanner API. A single doctor can be linked to multiple addresses, each represented by a unique address_id, allowing differentiation between various locations.
Mapping addresses to external systems
Addresses are frequently mapped to schedules in third-party software for more effective integration.
In the Docplanner interface, each address is shown as a distinct location under the doctor's profile.

Addresses play a crucial role in the integration mapping process, as they aggregate all resources used for bookings, including:
- Slots
- Services
- Insurances
- Bookings
Details for each are provided in the sections below.
Calendars
Each address may have an associated calendar, letting patients book appointments with a specific specialist online. In the Docplanner API, calendars are represented by the address_id and do not have a standalone object identifier.
A calendar is automatically created for an address when slots are added or when the enableCalendar
endpoint is invoked for the first time. Calendar status can be managed via dedicated API endpoints.
Slots are independent of calendar status
Slots can be added to a calendar even if it is disabled. Once enabled, all pre-existing slots will become available.
To manage calendar status, use the calendar endpoints:
- enableCalendar: Sets the calendar status to
active
, making all slots visible for booking. - disableCalendar: Sets the calendar status to
deactivated
, hiding all slots on the doctor's profile.
Services
Services define the types of visits (activities) that a specialist can perform. They serve as both a price list and a configuration element for slots, determining the options available to patients during booking.
There are two types of services described in the API:
- Services (dictionary services): These are standardized and reusable IDs which can be used for mapping.
- Address Services: Unique to a specific address. Each address_service_id can only be used for the relevant address; using it elsewhere will result in an error.
Here’s how to work with services:
Retrieve the Services List:
Fetch the full dictionary of available services using the getServices endpoint:www.{domain}/api/v3/integration/services
Example response:
{ "_items": [ { "id": "1", "name": "ablacja" }, { "id": "3", "name": "ablacja serca" }, { "id": "5", "name": "akupresura" }, { "id": "7", "name": "akupunktura" } ] }
These service_ids are unique and can be mapped to your software, but are not directly used for slot creation.
Missing required service?
If you do not find a matching service, contact us at integrations@docplanner.com. We can assist with adding missing services or recommend existing alternatives.
Assign Services to a Doctor's Address:
Once you have mapped the dictionary, you can create new services for a specific address using the addAddressService endpoint:www.{domain}/api/v3/integration/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/services
A typical request body:
{ "service_id": "2", "is_price_from": true, "price": 200, "description": "Address service description", "is_visible": true }
Descriptions of parameters:
service_id
: Reference to the dictionary service.is_price_from
: Indicates if the price is a starting price or fixed.price
: The price assigned to the address service.description
: Additional details visible to patients.is_visible
: If set to false, the service is hidden from patients but can still be used internally.
About the
is_visible
parameterServices with
is_visible
set tofalse
are only available for internal bookings. They will not appear to patients and must be used cautiously.A successful request returns an address_service_id unique to the address:
Content-Type: application/vnd.docplanner+json; charset=UTF-8 Location: https://www.znanylekarz.pl/api/v3/integration/facilities/111/doctors/222/addresses/333/services/444
Address Services must be tracked per address
Always retain each
address_service_id
received. They are required for all further operations such as managing slots or handling bookings, and cannot be reused for different doctors or addresses.Related operations include:
- GET: List all address services for a given address.
- DELETE: Remove a specific address service.
- PATCH: Modify properties such as
price
oris_price_from
.
Slots
Slots define the time intervals during which patients can book appointments with a specific doctor for a given service.
Before adding slots, ensure your mapping is complete. Use the replaceSlots endpoint to add or replace slots for a specified date range:
www.{domain}/api/v3/integration/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/slots
The request body:
{
"slots": [
{
"address_services": [
{ "address_service_id": 12345, "duration": 30 }
],
"end": "2020-11-10T15:00:00+0200",
"start": "2020-11-10T07:00:00+0200"
},
{
"address_services": [
{ "address_service_id": 67890, "duration": 20 },
{ "address_service_id": 45678, "duration": 60 }
],
"end": "2020-11-14T19:00:00+0200",
"start": "2020-11-14T16:00:00+0200"
}
]
}
Add work periods, not individual slots
Submit work periods (start/end spans with durations) rather than each slot individually. Docplanner will automatically divide them into bookable slots.
Prevent duplicate requests
Duplicate slot addition requests will result in a 429 Too Many Requests error.
In the examples provided, start
and end
delineate periods of availability, and associated address_service_id
determines which services are bookable during those times. Docplanner calculates the optimal slot segmentation.
Slot calculation logic
The system uses the greatest common divisor to optimize slot intervals based on durations provided.
Note that only services with is_visible=true
are available for booking.
Unable to view added slots in the interface?
Ensure that all services referenced by slots are visible (is_visible = true
). Verify using the getAddressServices
endpoint.
Advanced Calendar Configuration
You can enhance slot configurations by adding insurance-specific booking options. By including insurance_accepted
and insurance_providers
within each work period, you control insurance-based availability:
"with-insurance-only"
: Only patients with selected insurance can book."with-and-without-insurance"
: Open to both private and insured bookings."without-insurance-only"
: Only private bookings allowed.
The insurance_providers
array specifies which providers are available for a slot.
Example:
{
"slots": [
{
"address_services": [
{ "address_service_id": "111", "duration": 30 },
{ "address_service_id": "112", "duration": 15 }
],
"start": "2021-05-16T14:00:00+01:00",
"end": "2021-05-16T15:00:00+01:00",
"insurance_accepted": "with-insurance-only",
"insurance_providers": [52, 67]
},
{
"address_services": [
{ "address_service_id": "112", "duration": 15 }
],
"start": "2021-05-16T15:00:00+01:00",
"end": "2021-05-16T16:00:00+01:00"
}
]
}
Are insurance filters mandatory?
No, using insurance-related parameters is optional.
Where are advanced filters available?
Currently, advanced filters are available in Brazil, Spain, and Mexico. Check for updates as all locales will be supported in the future.
Calendar Breaks
To create breaks (e.g., lunch breaks, holidays), use the calendar_breaks resource. Adding a break hides all slots during the specified period, making new bookings unavailable.
Add a break using a POST request:
www.{domain}/api/v3/integration/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/breaks
Required parameters:
since
: Break start datetimetill
: Break end datetime
Example:
{
"since": "2018-11-10T13:00:00+0200",
"till": "2018-11-10T14:00:00+0200"
}
After a successful operation, the returned breakID
should be stored for future modifications.
You can also:
- GET: Retrieve a list of breaks (optionally filtered by
since
/till
) - GET: Retrieve a specific break
- PATCH: Modify the date/time range of a break
- DELETE: Remove a break
Endpoint for individual break operations:
www.{domain}/api/v3/integration/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/breaks/{break_id}
Overlapping breaks
Breaks can overlap. However, duplicating a break for the exact same time range will result in a 409 conflict error.
If a break is modified via the Docplanner interface, callback notifications will be sent:
- break-created
- break-removed
- break-moved
Examples:
Break created:
{
"name": "break-created",
"data": { /* ... */ },
"created_at": "2021-05-14T15:46:34+01:00"
}
Break removed:
{
"name": "break-removed",
"data": { /* ... */ },
"created_at": "2021-05-14T15:46:34+01:00"
}
Break moved:
{
"name": "break-moved",
"data": { /* ... */ },
"created_at": "2021-05-14T15:46:34+01:00"
}
Insurances
Insurances define which providers are accepted by a particular professional. Note that currently this is not connected to the main booking flow in all locales.
Insurances are not supported everywhere
Insurance functionality is not available in every market. Consult your local specialist or email integrations@docplanner.com for further information.
To synchronize available insurance providers, use getInsuranceProviders:
https://www.{domain}/api/v3/integration/insurance-providers
You can then GET, POST, or DELETE insurances on a doctor’s profile using the related endpoints. Insurances do not use address-specific IDs and only require mapping the provider dictionary.
Add an insurance provider:
https://www.{domain}/api/v3/integration/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/insurance-providers
With payload:
{
"insurance_provider_id": 3
}
You can also:
- GET the list of linked insurance providers
- DELETE a specific provider
Insurance providers are displayed in the Docplanner interface as part of the address information.

Bookings
Bookings represent all appointments reserved by patients, either directly in the clinic or through the Docplanner marketplace. Bookings can be created by both Docplanner or external (partner) systems.
Booking from the Clinic System
When a booking is added in the clinic system, trigger a request to the bookSlot endpoint:
https://www.{domain}/api/v3/integration/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/slots/{start}/book
Required request body:
{
"address_service_id": 123,
"duration": 10,
"is_returning": false,
"patient": {
"name": "Abraham",
"surname": "Lincoln",
"email": "example@example.com",
"phone": 48123123123,
"birth_date": "1985-01-01", // optional
"nin": 894237492, // optional
"gender": "m" // optional
}
}
address_service_id
: Service selected by the patient (if not mapped, use the default or first available)duration
: Duration of the visitis_returning
: Whether the patient is a returning visitor- Patient details
Bookings should be created as soon as possible to block the slot and prevent double booking via Docplanner.
A successful booking returns all details:
{
"id": "2134124",
"status": "booked",
"start_at": "2021-05-16T14:00:00+01:00",
"end_at": "2021-05-16T14:30:00+01:00",
"duration": 30,
"booked_by": "user",
"canceled_by": "",
"booked_at": "2021-05-12T12:00:00+01:00",
"canceled_at": "2021-05-16T14:30:00+01:00",
"patient": { /* ... */ },
"presence": "present"
}
With the id
(or visit_booking_id), you can:
DELETE (cancel) the booking:
https://www.{domain}/api/v3/integration/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/bookings/{booking_id}
Include a cancellation reason if desired:
{ "reason": "Doctor will not be present on that day in the clinic" }
moveBooking: Update or move a booking to a new time or service.
https://www.{domain}/api/v3/integration/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/bookings/{booking_id}/move
With body:
{ "address_service_id": 12345, "duration": 10, "start": "2020-11-26T16:00:00+01:00" }
Booking from Docplanner
When patients book via Docplanner, the process is straightforward. The system collects required information and dispatches a slot-booked
notification asynchronously, either via pull notifications or by pushing to a configured endpoint. (See Callbacks for details.)
Sample notification:
{
"name": "slot-booked",
"data": {
"facility": { /* ... */ },
"doctor": { /* ... */ },
"address": { /* ... */ },
"visit_booking": {
"id": "6263715",
"status": "booked",
"start_at": "2020-11-18T16:00:00+01:00",
"end_at": "2020-11-18T16:30:00+01:00",
"duration": "30",
"booked_by": "user", // or "doctor" or "integration"
"canceled_by": "",
"booked_at": "2018-11-14T14:38:19+02:00",
"address_service": {
"id": "243665",
"name": "USG",
"price": 50,
"is_price_from": false
},
"patient": { /* ... */ },
"comment": "Additional information about the visit"
}
},
"created_at": "2020-11-14T14:38:32+02:00"
}
You'll receive complete information on the booking, patient, and relevant entities.
Moving Bookings Between Addresses
The API supports moving bookings between different schedules/addresses (address_id). To do so, use the moveBooking endpoint with the target address_id and address_service_id:
{
"address_id": 12345,
"address_service_id": 112,
"duration": 10,
"start": "2021-05-26T16:00:00+01:00"
}
Updating service identifiers when moving bookings
Because address_service_id
is address-specific, always update this value when moving a booking to a new address.
Restrictions on moving bookings
Bookings may only be moved between addresses associated with the same doctor via the getAddresses
endpoint. Moving to a different doctor or outside of your integration's scope is not permitted.
When a booking is moved, patients are notified (unless configured otherwise). If a booking is moved between doctors in Docplanner, a booking-moved
notification is sent and both doctor_id, address_id, and address_service_id will be updated.
Example booking-moved
notification:
{
"name":"booking-moved",
"data":{ /* ... */ },
"created_at":"2021-09-27T14:03:05+02:00"
}
Note: Always ensure your integration updates all relevant identifiers (doctor, address, service) upon a booking move.