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.

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.

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.

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.

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:

1. 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.

2. 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 parameter

   Services with is_visible set to false 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 or is_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"
    }
  ]
}

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.

Note that only services with is_visible=true are available for booking.

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"
    }
  ]
}

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 datetime
• till: 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}

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.

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 visit
• is_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"
}

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.