Before starting the mapping process, carefully review our Resources section, which explains all relevant contexts in detail.

The general mapping workflow is illustrated in the following diagram:

Step 1: Retrieve and Store Resources

Begin by retrieving and storing all relevant resources for your API client. The primary entities requiring mapping on the partner side are:

• Facilities
• Doctors
• Addresses (both dictionary and address-specific)
• Services
• Insurances

To ensure proper synchronization, each Docplanner entity should be mapped to a corresponding object in the partner system’s database.

Step 2: Manage and Maintain Mappings

We highly recommend providing partners and clients with an interface to manage mappings independently, as configurations may change frequently. Below is an example of a mapping interface:

Step 3: Monitor Resource Changes

Maintaining up-to-date mappings is essential, as certain resources can change within the Docplanner interface. Resources particularly subject to change include:

• Services
• Insurances

Services require special attention. For example, deleting a service that is actively used for slot synchronization will cause calendar updates to fail. To ensure accuracy, we advise running a regular synchronization process that fetches the latest services for each mapped resource using the getAddressServices endpoint:

https://www.{domain}/api/v3/integration/facilities/{facility_id}/doctors/{doctor_id}/addresses/{address_id}/services

Sample response:

{
  "_items": [
    {
      "id": 101,
      "name": "USG",
      "is_default": true,
      "is_price_from": false,
      "price": 100,
      "description": "Description of service",
      "service_id": 1
    },
    {
      "id": 103,
      "name": "EEG",
      "is_default": true,
      "is_price_from": false,
      "price": null,
      "description": "Description of service",
      "service_id": 3
    }
  ]
}

Any address services in your local mapping that are no longer returned by this call should be unmapped, as maintaining obsolete mappings can cause issues during calendar updates.