Docplanner Tech
API docs by Redocly

Docplanner Integrations API (1.0.34)

Welcome to Docplanner Integrations REST API!

This API gives You the ability to build Your own application and integrate it with Docplanner services.

Fundamentals

Be sure to check out our General Guide for more descriptive definitions, example use cases, and the overall logic of this API.

Domain

Every API resource can be accessed via a URL of the structure given below:

https://www.{domain}/api/v3/integration/{resource}

NOTE! Every request has to be made using HTTPS connection!

Every request is based on a locale in which you want your integration in. The list of supported locales can be found below:

Country Locale {domain}
Argentina ar doctoraliar.com
Brazil br doctoralia.com.br
Chile cl doctoralia.cl
Colombia co doctoralia.co
Czech Republic cz znamylekar.cz
Spain es doctoralia.es
Italy it miodottore.it
Mexico mx doctoralia.mx
Peru pe doctoralia.pe
Portugal pt doctoralia.com.pt
Turkey tr doktortakvimi.com
Poland pl znanylekarz.pl

Http verbs

We use RESTful architecture therefore every HTTP method has a special meaning:

Verb Description
GET Retrieve resources
POST Creates resources or execute custom actions
PUT Replace resources
PATCH Partial update of resources
DELETE Delete resources

Expanding

When you need to load additional data or data related to the resource being requested, rather than making repeated calls, we allow related data to be returned and loaded alongside the original resource.

One or more resources can be included by using our standard with parameter. The with query parameter will take a list of one or more resources related to the primary resource and return those resources as well.

Consult an endpoint’s parameter description in order to verify which related resources are supported.

Body

We use architecture called HATEOAS to represent all data presented in the API.

HATEOAS defines how entity data is constructed and how relations are linked or embedded into the response.

We follow a few simple rules:

  • every key in the response is lowercase with optional underscores
  • every response can have _links section defining links to related entities or actions
  • every response can have _embedded section including related entities
  • all relational links are relative

Date and time

Every date and time has to be in ISO8601 format presented below:


    // format
    <year>-<month>-<day>T<hour>:<minute>:<second>+<timezone>

    // date
    2020 December 01, 00:00 CET +1

    // ISO8601
    2020-12-01T00:00:00+01:00

    // ISO8601 encoded in request
    2020-12-01T00%3A00%3A00%2B01%3A00

All request must have a desired timezone. We internally convert the timezone from a request to the timezone based on the locale the request is sent to.

Pagination

Paginated representations contain a few additional fields alongside fields belonging to returned data

Field Description
page Current page of results
limit Number of items in current page
pages Total number of pages
total Total number of items

Also, a few relations are defined in the _links section:

Relation Description
self Link to the current page of results
first Link to the first page of results
last Link to the last page of results
next Link to the next page of results
previous Link to the previous page of results

Here is a example of how a paginated response looks like:

{
    "results": [
        {
            "id": 1
        },
        {
            "id": 2
        },
        {
            "id": 3
        }
    ],
    "page": 1,
    "limit": 3,
    "pages": 1000,
    "total": 3000,
    "_links": {
        "self": {
            "href": "\/some-endpoint?&page=1&limit=3"
        },
        "first": {
            "href": "\/some-endpoint?&page=1&limit=3"
        },
        "last": {
            "href": "\/some-endpoint?&page=13310&limit=3"
        },
        "next": {
            "href": "\/some-endpoint?&page=2&limit=3"
        }
    }
}

Errors

API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP status code Description
200 - OK Everything worked as expected
400 - Bad Request Validation error message
403 - Forbidden You don't have the access rights to perform this action
404 - Not Found We couldn't find the resource you were asking for
409 - Conflict This response is sent when a request conflicts with the current state of the server
429 - Too many requests You have sent too many requests in a given amount of time
5XX - Server error An error occurred on our servers

Pro tip: Inside the error message you will have a more descriptive error message

Rate Limiting

To prevent DOS/DDOS attacks or API abuse, we have introduced rate limiting.

GET action limit is 8000 requests per hour.

PUT/POST/PATCH/DELETE actions are limited to 40 requests per minute (max 2400 requests per hour).

We can adjust limits on per-client basis, so if you are consistently running into the current limits, please let us know.

If your limits reaches zero, subsequent requests will receive the 429 Too Many Requests response code until the request reset time has been reached.

Rate Limiting Headers

We inform You of the state of rate limiter using HTTP headers.

RateLimit Header Description
X-RateLimit-Limit Request limit for the current time span
X-RateLimit-Reset Rate limiter reset date in in ISO8601 format
X-RateLimit-Used Number of requests made in current time span
X-RateLimit-Remaining Number of requests remaining in current time span

NOTE! No rate limiter specific headers in response means that the rate limiter is disabled

Facilities

More information on how we define what a Facility is, its use cases and more can be found here.

getFacilities

Get a list of facilities

Authorizations:
oauth2

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "_items": [
    • {
      • "id": "1",
      • "name": "Sample hospital"
      },
    • {
      • "id": "2",
      • "name": "Another sample hospital"
      }
    ]
}

getFacility

Get a single facility

Extensions:

  • facility.doctors - with this parameter in url, query results will return a list of all the doctors in a given facility
Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

query Parameters
with
Array of strings (FacilityScopes) unique
Items Value: "facility.doctors"

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "id": "1",
  • "name": "Sample hospital"
}

Doctors

More information on how we define what a Doctors is, its use cases and more can be found here.

getDoctors

Get a list of doctors in a facility

Extensions:

  • doctor.profile_url - with this parameter in url, query results will contain urls to doctors profiles
  • doctor.specializations - with this parameter in url, query results will contain specialization of doctors
  • doctor.license_numbers - with this parameter in url, query results will contain license numbers of doctors
Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

query Parameters
with
Array of strings (DoctorsScopes) unique
Items Enum: "doctor.profile_url" "doctor.specializations" "doctor.license_numbers"

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "_items": [
    • {
      • "id": "123",
      • "name": "Sample",
      • "surname": "Doctor 123"
      },
    • {
      • "id": "234",
      • "name": "Sample",
      • "surname": "Doctor 234"
      }
    ]
}

getDoctor

Get a single doctor in a facility

Extensions:

  • doctor.profile_url - with this parameter in url, query results will contain urls to doctors profiles
  • doctor.addresses - with this parameter in url, query results will return a list of all the doctor addresses in a given facility
  • doctor.license_numbers - with this parameter in url, query results will contain license numbers of doctors
  • address.booking_extra_fields - with this parameter in url, query results will return required parameters requested from patient in the booking flow
  • address.online_only - with this parameter in url, query results will return additional parameter indicating if an address is dedicated to video consultations
  • address.visit_payment - with this parameter in url, query results will return additional parameter indicating when visit payments are enabled
  • address.commercial_type - with this parameter in url, query results will return additional parameter indicating address commercial type
Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

query Parameters
with
Array of strings (DoctorScopes) unique
Items Enum: "doctor.profile_url" "doctor.addresses" "doctor.license_numbers" "address.booking_extra_fields" "address.online_only" "address.visit_payment" "address.commercial_type"

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "id": "123",
  • "name": "Sample",
  • "surname": "Doctor 123",
  • "specializations": {
    • "_items": [
      • {
        • "id": "12",
        • "name": "Specialization example 12"
        }
      ]
    }
}

Addresses

More information on how we define what a Addresses is, its use cases and more can be found here.

getAddresses

Get a list of addresses of a doctor

Extensions:

  • address.online_only - with this parameter in url, query results will return additional parameter indicating if returned addresses are dedicated to video consultations
  • address.visit_payment - with this parameter in url, query results will return additional parameter indicating if visit payments are enabled
  • address.commercial_type - with this parameter in url, query results will return additional parameter indicating address commercial type
  • address.insurance_support - with this parameter in url, query results will return additional parameter indicating insurance support type of an address
Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

query Parameters
with
Array of strings (AddressesScopes) unique
Items Enum: "address.online_only" "address.visit_payment" "address.commercial_type" "address.insurance_support"

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "_items": [
    • {
      • "id": "111",
      • "name": "Example hospital",
      • "post_code": "xx-xxx",
      • "street": "Some street",
      • "booking_extra_fields": {
        • "birth_date": false,
        • "gender": false,
        • "nin": false
        }
      }
    ]
}

getAddress

Get a single address of a doctor

Extensions:

  • address.online_only - with this parameter in url, query results will return additional parameter indicating if an address is dedicated to video consultations
  • address.visit_payment - with this parameter in url, query results will return additional parameter indicating if visit payment isr enabled
  • address.commercial_type - with this parameter in url, query results will return additional parameter indicating address commercial type
  • address.insurance_support - with this parameter in url, query results will return additional parameter indicating insurance support type of an address
Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

query Parameters
with
Array of strings (AddressesScopes) unique
Items Enum: "address.online_only" "address.visit_payment" "address.commercial_type" "address.insurance_support"

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "id": "111",
  • "name": "Example hospital",
  • "post_code": "xx-xxx",
  • "street": "Some street",
  • "booking_extra_fields": {
    • "birth_date": false,
    • "gender": false,
    • "nin": false
    }
}

updateAddress

Get a single address of a doctor

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

Request Body schema: application/json
insurance_support
string
Enum: "private" "insurance" "private_and_insurance"

Responses

Request samples

Content type
application/json
{
  • "insurance_support": "private_and_insurance"
}

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "id": "111",
  • "name": "Example hospital",
  • "post_code": "xx-xxx",
  • "street": "Some street",
  • "booking_extra_fields": {
    • "birth_date": false,
    • "gender": false,
    • "nin": false
    },
  • "insurance_support": "private"
}

Services

More information on how we define what a Services is, its use cases and more can be found here.

getServices

Services returned in this endpoint are dictionary services.

Services returned here are from a dictionary (item_services).

Scopes:

  • services.only_diagnostics - with this parameter in url, query results will return only dictionary of services dedicated to integration with diagnostics marketplace
Authorizations:
oauth2
query Parameters
with
Array of strings (ServicesScopes) unique
Items Value: "services.only_diagnostics"

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "_items": [
    • {
      • "id": "1",
      • "name": "USG"
      },
    • {
      • "id": "2",
      • "name": "EKG"
      },
    • {
      • "id": "3",
      • "name": "EEG"
      }
    ]
}

getAddressServices

Services returned in this endpoint are address services.

Services returned here are from specified address (address_services).

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

query Parameters
start
string <date-time>
Example: start=2021-05-16T14:00:00+01:00

Slot start date (parameter must be urlencoded before sending request). Limits results to only those linked to slots that start on that date.

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "_items": [
    • {
      • "id": "101",
      • "name": "USG",
      • "is_default": true,
      • "is_price_from": false,
      • "price": 100,
      • "description": "Description of service",
      • "service_id": "1",
      • "is_visible": true
      },
    • {
      • "id": "103",
      • "name": "EEG",
      • "is_default": true,
      • "is_price_from": false,
      • "price": null,
      • "description": "Description of service",
      • "service_id": "3",
      • "is_visible": false
      }
    ]
}

addAddressService

Adds new service to an address of the doctor

Services added here are specific to this address (address_services).

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

Request Body schema: application/json
service_id
required
string

ID of a service

is_price_from
boolean

If the specified price is the minimum price of the service

price
integer

Minimum price

description
string
is_visible
boolean
default_duration
integer

Responses

Request samples

Content type
application/json
{
  • "service_id": "2",
  • "is_price_from": true,
  • "price": 200,
  • "description": "Address service description",
  • "is_visible": true,
  • "default_duration": 20
}

Response samples

Content type
application/vnd.error+docplanner+json
{
  • "errors": [ ],
  • "message": "Validation error message, e.g.: Invalid price value for service. Price should be either null or integer greater or equal 0."
}

getAddressService

Service returned in this endpoint is an address service.

Service returned here is from a specified address (address_services).

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

address_service_id
required
string
Example: 123

ID of an address service

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "id": "101",
  • "name": "USG",
  • "is_default": true,
  • "is_price_from": false,
  • "price": 100,
  • "description": "Description of service",
  • "service_id": "1",
  • "is_visible": true
}

updateAddressService

Service updated in this endpoint is an address service from this specified address (address_services).

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

address_service_id
required
string
Example: 123

ID of an address service

Request Body schema: application/json
is_price_from
boolean

If the specified price is the minimum price of the service

price
integer

Minimum price

description
string
default_duration
integer

Responses

Request samples

Content type
application/json
{
  • "price": 200,
  • "is_price_from": true,
  • "description": "Address service description",
  • "default_duration": 20
}

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "id": "101",
  • "name": "USG",
  • "is_default": true,
  • "is_price_from": true,
  • "price": 200,
  • "description": "Address service description",
  • "service_id": "1",
  • "is_visible": true
}

deleteAddressService

Service deleted in this endpoint is an address service from this specified address (address_services).

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

address_service_id
required
string
Example: 123

ID of an address service

Responses

Response samples

Content type
application/vnd.error+docplanner+json
Example
{
  • "errors": [ ],
  • "message": "You are not authorized to see this facility"
}

Insurances

More information on how we define what a Insurances is, its use cases and more can be found here.

getInsuranceProviders

Get a list of available insurance providers

Authorizations:
oauth2

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "_items": [
    • {
      • "insurance_provider_id": "1",
      • "name": "Insurance provider 1"
      },
    • {
      • "insurance_provider_id": "2",
      • "name": "Insurance provider 2"
      },
    • {
      • "insurance_provider_id": "3",
      • "name": "Insurance provider 3"
      }
    ]
}

getInsurancePlans

Get a list of available insurance plans for a given insurance provider

Authorizations:
oauth2
path Parameters
insurance_provider_id
required
string
Example: 123

ID of an insurance provider from DP dictionary

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "_items": [
    • {
      • "insurance_plan_id": "999",
      • "name": "Insurance plan 999"
      },
    • {
      • "insurance_plan_id": "1000",
      • "name": "Insurance plan 1000"
      }
    ]
}

getAddressInsuranceProviders

Get a list of insurance providers for a specific address

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "_items": [
    • {
      • "insurance_provider_id": "1",
      • "name": "Insurance provider 1",
      • "insurance_plans": {
        • "_items": [
          • {
            },
          • {
            }
          ]
        }
      },
    • {
      • "insurance_provider_id": "2",
      • "name": "Insurance provider 2",
      • "insurance_plans": {
        • "_items": [ ]
        }
      }
    ]
}

addAddressInsuranceProvider

Adds new insurance provider to an address of the doctor

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

Request Body schema: application/json
insurance_provider_id
required
string

ID of an insurance provider from DP dictionary

Responses

Request samples

Content type
application/json
{
  • "insurance_provider_id": "3"
}

Response samples

Content type
application/vnd.error+docplanner+json
{
  • "errors": [ ],
  • "message": "Validation error message, e.g.: Insurance provider with given ID is already assigned to this address."
}

updateOrCreateAddressInsuranceProvider

Updates or creates insurance provider for a given doctor address

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

Request Body schema: application/json
insurance_provider_id
required
string

ID of an insurance provider from DP dictionary

Array of objects

Responses

Request samples

Content type
application/json
{
  • "insurance_provider_id": "3",
  • "insurance_plans": [
    • {
      • "insurance_plan_id": "999"
      },
    • {
      • "insurance_plan_id": "1000"
      }
    ]
}

Response samples

Content type
application/vnd.error+docplanner+json
Example
{
  • "errors": [ ],
  • "message": "You are not authorized to see this facility"
}

deleteAddressInsuranceProvider

Delete an insurance provider from doctor’s address

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

insurance_provider_id
required
string
Example: 123

ID of an insurance provider from DP dictionary

Responses

Response samples

Content type
application/vnd.error+docplanner+json
{
  • "errors": [ ],
  • "message": "Validation error message, e.g.: Insurance provider with given ID is not assigned to this address."
}

Calendars

Simple operations on the calendar belonging to the address

getCalendar

Gets calendar of the address

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "status": "enabled"
}

enableCalendar

Enable calendar on the address

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

Responses

Response samples

Content type
application/vnd.error+docplanner+json
{
  • "errors": [ ],
  • "message": "Could not enable calendar on disabled address"
}

disableCalendar

Disable calendar on the address

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

Responses

Response samples

Content type
application/vnd.error+docplanner+json
Example
{
  • "errors": [ ],
  • "message": "You are not authorized to see this facility"
}

Calendar Breaks

More information on how we define what a Calendar Breaks is, its use cases and more can be found here.

getCalendarBreaks

Get the list of calendar breaks

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

query Parameters
since
required
string <date-time>
Example: since=2021-05-16T14:00:00+01:00
till
required
string <date-time>
Example: till=2021-05-16T15:00:00+01:00

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "id": "567",
  • "since": "2020-12-16T14:00:00+01:00",
  • "till": "2020-12-16T14:30:00+01:00",
  • "description": "Optional description"
}

addCalendarBreak

Add a new break to the calendar

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

Request Body schema: application/json
since
required
string <date-time>
till
required
string <date-time>
description
string

Responses

Request samples

Content type
application/json
{
  • "since": "2021-05-16T14:00:00+01:00",
  • "till": "2021-05-16T15:00:00+01:00",
  • "description": "Optional reason for adding this particular break"
}

Response samples

Content type
application/vnd.error+docplanner+json
Example
{
  • "errors": [ ],
  • "message": "Param \"since\" is required!"
}

getCalendarBreak

View a specific calendar break

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

break_id
required
string
Example: 123

ID of the Calendar Break

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "id": "567",
  • "since": "2020-12-16T14:00:00+01:00",
  • "till": "2020-12-16T14:30:00+01:00",
  • "description": "Optional description"
}

moveCalendarBreak

Move the calendar break

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

break_id
required
string
Example: 123

ID of the Calendar Break

Request Body schema: application/json
since
required
string <date-time>
till
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "since": "2021-05-16T14:00:00+01:00",
  • "till": "2021-05-16T15:00:00+01:00"
}

Response samples

Content type
application/vnd.error+docplanner+json
Example
{
  • "errors": [ ],
  • "message": "Param \"since\" is required!"
}

deleteCalendarBreak

Delete the calendar break

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

break_id
required
string
Example: 123

ID of the Calendar Break

Responses

Response samples

Content type
application/vnd.error+docplanner+json
Example
{
  • "errors": [ ],
  • "message": "You are not authorized to see this facility"
}

Slots

More information on how we define what a Slots is, its use cases and more can be found here.

getSlots

List of free slots for the address within specified date range

Extensions:

  • slot.services - with this parameter in url, query results will return address services attached to given slots
Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

query Parameters
start
required
string <date-time>
Example: start=2021-05-16T14:00:00+01:00

Slot start date (parameter must be urlencoded before sending request)

end
required
string <date-time>
Example: end=2021-05-16T15:00:00+01:00

Slot start date (parameter must be urlencoded before sending request)

with
Array of strings (SlotsScopes) unique
Items Value: "slot.services"

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "_items": [
    • {
      • "start": "2020-12-16T14:00:00+01:00"
      },
    • {
      • "start": "2020-12-16T14:30:00+01:00"
      }
    ]
}

replaceSlots

Adds or replaces the slots. This will override all existing slots for given date ranges

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

Request Body schema: application/json
Array of objects

Responses

Request samples

Content type
application/json
{
  • "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"
      }
    ]
}

Response samples

Content type
application/vnd.error+docplanner+json
Example
{
  • "errors": [ ],
  • "message": "Validation error message, e.g.: Slots comes from different days"
}

bookSlot

Book a slot

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

start
required
string <date-time>
Example: 2021-05-16T14:00:00+01:00

Slot start date (parameter must be urlencoded before sending request)

Request Body schema: application/json
address_service_id
required
string
is_returning
boolean
required
object (Patient)
duration
required
integer
send_notifications
boolean
Default: null

Whether we should send visit notifications

label
string
Default: null

Responses

Request samples

Content type
application/json
{
  • "address_service_id": "113",
  • "is_returning": false,
  • "duration": 30,
  • "send_notifications": true,
  • "label": "label",
  • "patient": {
    • "name": "Abraham",
    • "surname": "Lincoln",
    • "email": "example@example.com",
    • "phone": 48123123123,
    • "birth_date": "1985-01-01",
    • "nin": 894237492,
    • "gender": "m",
    • "marketing_consent": true,
    • "data_privacy_consent": true
    }
}

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "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": {
    • "name": "Abraham",
    • "surname": "Lincoln",
    • "email": "example@example.com",
    • "phone": 48123123123,
    • "birth_date": "1985-01-01",
    • "nin": 894237492,
    • "gender": "m"
    },
  • "presence": "present"
}

deleteSlots

Delete slots for the given date

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

date
required
string <date>
Example: 2021-05-16

Responses

Response samples

Content type
application/vnd.error+docplanner+json
Example
{
  • "errors": [ ],
  • "message": "You are not authorized to see this facility"
}

Bookings

More information on how we define what a Bookings is, its use cases and more can be found here.

addBooking

In order to add a new booking use POST bookSlot endpoint from Slots section.

getBookings

Get bookings list of a doctor in the facility Passing the page parameter in the query string will enable pagination. Extensions:

  • booking.patient - with this parameter in url, query results will return patient data for every booking
  • booking.address_service - with this parameter in url, query results will return address service for every booking
  • booking.presence - with this parameter in url, query results will return additional information weather patient was present for every booking
Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

query Parameters
start
required
string <date-time>
Example: start=2021-05-16T14:00:00+01:00

Slot start date (parameter must be urlencoded before sending request)

end
required
string <date-time>
Example: end=2021-05-16T15:00:00+01:00

Slot start date (parameter must be urlencoded before sending request)

page
integer
Example: page=1

Page number to use for pagination. If not provided the pagination is not applied.

limit
integer
Example: limit=100

Maximum number of items per page. If not provided the default value of 100 is applied if pagination is used.

with
Array of strings (BookingsScopes) unique
Items Enum: "booking.patient" "booking.address_service" "booking.presence"

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "_items": [
    • {
      • "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": null,
      • "comment": "comment",
      • "insurance": {
        • "id": "11",
        • "name": "Axa",
        • "plan": null,
        • "plan_id": null
        }
      },
    • {
      • "id": "2134125",
      • "status": "booked",
      • "start_at": "2021-05-16T17:00:00+01:00",
      • "end_at": "2021-05-16T17:30:00+01:00",
      • "duration": 15,
      • "booked_by": "doctor",
      • "canceled_by": "doctor",
      • "booked_at": "2021-05-12T13:00:00+01:00",
      • "canceled_at": "2021-05-16T14:30:00+01:00",
      • "comment": null,
      • "insurance": {
        • "id": "11",
        • "name": "Axa",
        • "plan": null,
        • "plan_id": null
        }
      }
    ]
}

getBooking

View specific booking

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

booking_id
required
string
Example: 123

ID of the Booking

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "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": null,
  • "patient": {
    • "name": "Abraham",
    • "surname": "Lincoln",
    • "email": "example@example.com",
    • "phone": 48123123123,
    • "birth_date": "1985-01-01",
    • "nin": 894237492,
    • "gender": "m",
    • "is_returning": false
    },
  • "address_service": {
    • "id": "101",
    • "name": "USG",
    • "price": 100,
    • "is_price_from": false,
    • "is_default": true,
    • "service_id": "1",
    • "description": "Description of service",
    • "is_visible": true
    },
  • "comment": "comment",
  • "insurance": {
    • "id": "11",
    • "name": "Axa",
    • "plan": null,
    • "plan_id": null
    }
}

cancelBooking

Cancel the booking

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

booking_id
required
string
Example: 123

ID of the Booking

Request Body schema: application/json
reason
string

Reason why visit was canceled

send_notifications
boolean
Default: null

Whether patient should get notification on canceling the visit

Responses

Request samples

Content type
application/json
Example
{
  • "reason": "Doctor will not be present on that day in the clinic",
  • "send_notifications": true
}

Response samples

Content type
application/vnd.error+docplanner+json
Example
{
  • "errors": [ ],
  • "message": "Validation error message, e.g.: Visit 12345 cannot be canceled because it is not booked"
}

moveBooking

Move booking for a doctor

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

booking_id
required
string
Example: 123

ID of the Booking

Request Body schema: application/json
address_service_id
required
string
start
required
string <date-time>
duration
integer
address_id
string

Responses

Request samples

Content type
application/json
Example
{
  • "address_service_id": "112",
  • "start": "2021-05-26T16:00:00+01:00",
  • "duration": 30
}

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
{
  • "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": null,
  • "patient": {
    • "name": "Abraham",
    • "surname": "Lincoln",
    • "email": "example@example.com",
    • "phone": 48123123123,
    • "birth_date": "1985-01-01",
    • "nin": 894237492,
    • "gender": "m",
    • "is_returning": false
    },
  • "address_service": {
    • "id": "101",
    • "name": "USG",
    • "price": 100,
    • "is_price_from": false,
    • "is_default": true,
    • "service_id": "1",
    • "description": "Description of service",
    • "is_visible": true
    },
  • "comment": "comment",
  • "insurance": {
    • "id": "11",
    • "name": "Axa",
    • "plan": null,
    • "plan_id": null
    }
}

requestOpinion

After the visit was booked via clinics software, by calling this endpoint you can request SMS asking patient to leave an opinion. We do not store patient and visit information

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

Request Body schema: application/json

Phone number of the patient

phone
required
string

Responses

Request samples

Content type
application/json
{
  • "phone": "123456789"
}

Response samples

Content type
application/vnd.error+docplanner+json
{
  • "errors": [ ],
  • "message": "Validation error message, e.g.: Phone number is invalid."
}

Patient Presence

More information on how we define what a Patient Presence is, its use cases and more can be found here.

markPatientPresence

Mark the presence of the patient on the visit

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

booking_id
required
string
Example: 123

ID of the Booking

Responses

Response samples

Content type
application/vnd.error+docplanner+json
{
  • "errors": [ ],
  • "message": "Validation error message, e.g.: Visit is in the future"
}

markPatientAbsence

Mark the absence of the patient on the visit

Authorizations:
oauth2
path Parameters
facility_id
required
string
Example: 1

ID of the Facility

doctor_id
required
string
Example: 123

ID of a doctor in a facility

address_id
required
string
Example: 123

ID of a doctor`s address in a facility

booking_id
required
string
Example: 123

ID of the Booking

Responses

Response samples

Content type
application/vnd.error+docplanner+json
{
  • "errors": [ ],
  • "message": "Validation error message, e.g.: Visit is in the future"
}

API Notification Callbacks

More information on how we define what a API Notification Callbacks is, its use cases and more can be found here.

Push Notifications

Pushing Notifications - To be able to use this method, client should give us an endpoint url, and we will be pushing notifications to this endpoint in real time. HTTP POST method will be used to push event data to endpoint. Note: Regardless of the response status (500, 200, 400) from the client endpoint, the events will be pushed only once. You can find every possible event notification requests below.

Responses

Callbacks

Callback payload samples

Callback
Content type
application/json
Example
{
  • "name": "slot-booking",
  • "data": {
    • "facility": {
      • "id": "1",
      • "name": "Sample hospital"
      },
    • "doctor": {
      • "id": "123",
      • "name": "Sample",
      • "surname": "Doctor 123"
      },
    • "address": {
      • "id": "111",
      • "name": "Example hospital",
      • "street": "Some street",
      • "post_code": "xx-xxx"
      },
    • "visit_booking_request": {
      • "booking_at": "2021-05-12T10:18:24+01:00",
      • "booking_by": "user",
      • "duration": 30,
      • "start_at": "2021-05-26T16:00:00+01:00",
      • "end_at": "2021-05-26T16:30:00+01:00",
      • "address_service": {
        • "id": "243665",
        • "name": "biopsja nerki",
        • "price": 50,
        • "is_price_from": false,
        • "is_visible": true
        },
      • "patient": {
        • "name": "Abraham",
        • "surname": "Lincoln",
        • "email": "example@example.com",
        • "phone": "+48123123123",
        • "birth_date": "1985-01-01",
        • "nin": "894237492",
        • "gender": "m"
        },
      • "comment": "Additional information about the visit"
      }
    },
  • "created_at": "2021-05-12T10:18:34+01:00"
}

Pull Notification

Pulling Notifications - You can pull notifications via this endpoint. This page will respond to you with the earliest notification you haven’t been pulled yet. First In First Out (FIFO) principle applied here. This endpoint will respond with one notification per request until there aren’t any notifications left in the notification queue. Important: Notifications that are not pulled in 72 hours are marked as expired and deleted from the system.

Authorizations:
oauth2

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "name": "slot-booking",
  • "data": {
    • "facility": {
      • "id": "1",
      • "name": "Sample hospital"
      },
    • "doctor": {
      • "id": "123",
      • "name": "Sample",
      • "surname": "Doctor 123"
      },
    • "address": {
      • "id": "111",
      • "name": "Example hospital",
      • "street": "Some street",
      • "post_code": "xx-xxx"
      },
    • "visit_booking_request": {
      • "booking_at": "2021-05-12T10:18:24+01:00",
      • "booking_by": "user",
      • "duration": 30,
      • "start_at": "2021-05-26T16:00:00+01:00",
      • "end_at": "2021-05-26T16:30:00+01:00",
      • "address_service": {
        • "id": "243665",
        • "name": "biopsja nerki",
        • "price": 50,
        • "is_price_from": false,
        • "is_visible": true
        },
      • "patient": {
        • "name": "Abraham",
        • "surname": "Lincoln",
        • "email": "example@example.com",
        • "phone": "+48123123123",
        • "birth_date": "1985-01-01",
        • "nin": "894237492",
        • "gender": "m"
        },
      • "comment": "Additional information about the visit"
      }
    },
  • "created_at": "2021-05-12T10:18:34+01:00"
}

Pull Multiple Notification

Pulling Notifications - You can pull multiple notifications via this endpoint. This page will respond to you with the earliest notifications you haven’t been pulled yet in the quantity limited by limit parameter. First In First Out (FIFO) principle applied here. This endpoint will respond with the collection of notifications and amount of remaining notifications. Important: Notifications that are not pulled in 72 hours are marked as expired and deleted from the system.

Authorizations:
oauth2
query Parameters
limit
integer
Example: limit=5

Maximum number of notifications pulled. Can take value from 1 to 100. If not provided the default value of 1 is applied.

Responses

Response samples

Content type
application/vnd.docplanner+json; charset=UTF-8
Example
{
  • "notifications": [
    • {
      • "name": "break-created",
      • "data": {
        • "facility": {
          • "id": "1",
          • "name": "Sample hospital"
          },
        • "doctor": {
          • "id": "123",
          • "name": "Sample",
          • "surname": "Doctor 123"
          },
        • "address": {
          • "id": "111",
          • "name": "Example hospital",
          • "street": "Some street",
          • "post_code": "xx-xxx"
          },
        • "break": {
          • "id": "2573784",
          • "since": "2021-05-25T10:00:00+01:00",
          • "till": "2021-05-25T12:00:00+01:00"
          }
        },
      • "created_at": "2021-05-14T15:46:34+01:00"
      },
    • {
      • "name": "presence-marked",
      • "data": {
        • "facility": {
          • "id": "1",
          • "name": "Sample hospital"
          },
        • "doctor": {
          • "id": "123",
          • "name": "Sample",
          • "surname": "Doctor 123"
          },
        • "address": {
          • "id": "111",
          • "name": "Example hospital",
          • "street": "Some street",
          • "post_code": "xx-xxx"
          },
        • "visit_booking": {
          • "id": "6264532",
          • "status": "booked",
          • "start_at": "2021-05-27T11:00:00+01:00",
          • "end_at": "2021-05-27T11:30:00+01:00",
          • "duration": 30,
          • "booked_by": "user",
          • "canceled_by": "",
          • "booked_at": "2021-05-14T10:19:02+01:00",
          • "patient": {
            },
          • "signature": "f6b9b2fc-4faa-feab-58d9-26a3767f1426"
          },
        • "presence": "ABSENT"
        },
      • "created_at": "2021-05-14T15:46:34+01:00"
      }
    ],
  • "remaining": 5
}

Release Notifications

Action allowing to trigger re-dispatching all the notifications that were not processed correctly. Call to this endpoint should be repeated periodically to ensure consistency between systems. Docplanner API allows to perform notifications release once per hour. Endpoint can be used only if Docplanner system is pushing events to the external endpoints.

Authorizations:
oauth2

Responses

Response samples

Content type
application/vnd.error+docplanner+json
{
  • "errors": [ ],
  • "message": "You are not allowed to use this method"
}