ZnanyLekarz Doctors API

openapi: 3.2.0
info:
  title: Docplanner Integrations Doctors API
  description: 'Welcome to Docplanner Integrations REST API!


    This API gives You the ability to build Your own application and integrate it with Docplanner services.'
  version: 1.14.0
  x-logo:
    url: https://docplanner.tech/logo.svg
    backgroundColor: '#012c6d'
    altText: Docplanner Tech
  x-changelog:
    1.14.0: '* Introducing new optional **apply_on_coupled_addresses** field in **AddCalendarBreakRequest** for creating the same break on the doctor''s coupled addresses in the facility

      * **moveCalendarBreak** and **deleteCalendarBreak** now move and remove those coupled breaks together with the break they follow

      '
    1.13.0: '* **moveBooking** may now move a booking to an **address_id** belonging to a different doctor within the same facility, reassigning the booking to that doctor. An address outside the facility named in the path is still rejected with **403**

      * **moveBooking** returns **422 Unprocessable Entity** when the booking still holds money and the target address is billed through a different payment account. Cancel the booking and create a new one instead. A payment that was fully refunded or charged back holds no money, so it does not restrict the move

      '
    1.12.0: '* Documenting **price** in **AddAddressServiceRequest** and **UpdateAddressServiceRequest** as a number with up to 2 decimal places; invalid price formats now return a **400 Bad Request** error

      '
    1.11.0: '* Introducing new **removeAddressIntegration** endpoint for DocplannerPMS API clients

      '
    1.10.0: '* Introducing new optional **custom_name** field in **AddAddressServiceRequest** and **UpdateAddressServiceRequest** for creating and updating address services with custom display names

      '
    1.9.3: '* Adding maximum date range validation of 180 days to **getSlots** endpoint. Requests exceeding this range will return a **400 Bad Request** error

      '
    1.9.2: '* Introducing new optional **specialization_id** query parameter in **getServices** endpoint

      '
    1.9.1: '* Making **price** and **description** fields in **UpdateAddressServiceRequest** nullable as they are not required

      '
    1.9.0: '* Introducing new **confirmBooking** endpoint

      '
    1.8.1: '* Introducing new **insurance_number** field in **Patient** schema for booking related notifications and endpoints

      '
    1.8.0: '* Introducing new **address_service.public_insurance_flow** scope for **getBookings** endpoint

      * Introducing new **address_service.public_insurance_flow** scope for **getBooking** endpoint

      * Introducing new **address_service.public_insurance_flow** scope for **getAddressServices** endpoint

      * Introducing new **address_service.public_insurance_flow** scope for **getAddressService** endpoint

      '
    1.7.1: '* Introducing new optional **insurance_plans** field in **addAddressInsuranceProvider** endpoint

      '
    1.6.1: '* Introducing new **address_service.custom_name** scope for **getAddressService** and **getAddressServices** endpoints.

      '
    1.5.0: '* Introducing new optional **allowed_patients** field with **minimum_age** and **maximum_age** properties in **AddAddressServiceRequest**, **UpdateAddressServiceRequest**, and **AddressService** schema for age restrictions

      '
    1.4.8: '* Improved error message clarity for calendar breaks endpoints.

      '
    1.4.7: '* Fixed **addAddressService** and **addCalendarBreak** response not having body

      '
    1.4.6: '* Documentation: Added IP whitelisting endpoints information for partners receiving webhooks

      '
    1.4.5: "* Marking **name**, **city_name** and **street** fields in **Address** schema as nullable  \n"
    1.4.4: '* Fixed **license_number** field name in **DoctorsWithLicenseNumbers** example for **getDoctors** endpoint

      '
    1.4.3: '* Add **city_name** field information for **Addresses** endpoints.

      '
    1.4.2: '* Fixed issue with **getBooking** endpoint in PHP SDK

      '
    1.4.1: '* Introducing new **booking.confirmation** scope for **getBookings** endpoint

      '
    1.4.0: '* Introducing new **booking.moving** scope for **getBooking** endpoint

      '
    1.3.3: '* Fixing **insurance** schema in booking callback notifications

      '
    1.3.2: '* Introducing new optional **is_recurring** field in **bookSlot** endpoint

      '
    1.3.1: '* Making **price** in **AddAddressServiceRequest** field nullable as it''s not required

      '
    1.3.0: '* Introducing new optional **insurance_provider_id** and **insurance_plan_id** fields in **bookSlot** endpoint

      '
    1.2.0: '* Introducing new optional is_visible field in updateAddressService endpoint

      '
    1.0.40: '* Marking **address_service** and **insurance** fields in **getBooking** endpoint response as nullable             * Marking **address_service** field in **getSlots** endpoint response as nullable * Marking **address_service** and **insurance** fields in booking related callback notifications as nullable

      '
    1.0.39: '* Deprecated **videocall_url** field in **getBookings** endpoint

      '
    1.0.38: '* Deprecated **send_notifications** field in **BookSlot** and **CancelBookingRequest**

      '
    1.0.37: '* Adding 422 response status code in **bookSlot** endpoint

      '
    1.0.36: '* Adding **booking-payment-status-changed** callback

      '
    1.0.35: '* Introducing new optional **comment** field on **bookSlot** endpoint

      '
    1.0.34: '* PHP SDK without dependencies on GuzzleHttp building query method.

      '
    1.0.33: '* Fixed **Error** schema

      '
    1.0.32: '* Added **address-assigned** and **address-unassigned** callbacks

      '
    1.0.31: '* Added optional pagination to **getBookings** endpoint

      '
    1.0.30: '* Changed **errors* field type in the **Error** schema

      '
    1.0.29: '* Adding **address-commercial-type-changed** callback

      '
    1.0.28: '* Introducing new optional **marketing_consent** and **data_privacy_consent** fields on **bookSlot** endpoint

      '
    1.0.27: '* Introducing new optional **label** field on **bookSlot** endpoint

      '
    1.0.26: '* Introducing **address.insurance_support** scope for **getAddress** and **getAddresses** endpoints * Introducing **updateAddress** endpoint for changing insurance support type of an address

      '
    1.0.25: '* Introducing **getCalendar** endpoint for getting calendar status

      '
    1.0.24: '* Introducing **address.commercial_type** scope for **getAddress**, **getAddresses** and **getDoctor** endpoints

      '
    1.0.23: '* Added "address-service-created", "address-service-deleted", "address-service-changed" callbacks

      '
    1.0.22: '* Introducing **doctor.profile_url** scope for **getDoctor** and **getDoctors** endpoints

      '
    1.0.21: '* Added missing **insuranceProviderId** property to **getInsurancePlans** operation  * Renamed **insurance_provider** parameter to **insurance_provider_id** in **deleteAddressInsuranceProvider** operation * Renamed **OAuth 2.0** security scheme to **oauth2** * Fixed minor syntax error * Renamed invalid **docplanner.it** domain to **miodottore.it** in the description

      '
    1.0.20: '* New (optional) property **default_duration** for **AddAddressServiceRequest** and **UpdateAddressServiceRequest**

      '
    1.0.19: '* Added "booking-confirmed" callback

      '
    1.0.18: '* Added support for insurance plans

      '
    1.0.17.1: '* Added missing is_visible property to **AddAddressServiceRequest** example payload

      '
    1.0.17: '* Introduced **Pull Multiple Notifications** endpoint

      '
    1.0.16: '* New (optional) property **is_visible** for **AddAddressServiceRequest**

      '
    1.0.15: '* New (optional) property **reason** for **CancelBookingRequest** (it is now possible to set a reason why booking was canceled)

      '
    1.0.14.1: '* Added missing is_visible property to responses and examples

      '
    1.0.14: '* Added support for custom services and is_visible property of AddressService

      '
    1.0.13: '* Creating calendar in **addCalendarBreak** when it''s missing.

      '
    1.0.12: '* Returning whole Booking on moveBooking action.

      '
    1.0.11: '* Added **insurance_accepted** and **insurance_providers** fields to **ReplaceSlotsRequest** (support for insurances configuration)

      '
    1.0.10: '* Introducing **doctor.license_numbers** scope for **getDoctor** and **getDoctors** endpoints

      '
    1.0.9: '* Added Calendars API * Added methods to enable and disable calendar on the address

      '
    1.0.8: '* New (optional) property **send_notifications** for **CancelBookingRequest** (it is now possible to set if the patient should get notifications on canceling the visit)

      '
    1.0.7: '* Buried notifications can be released: added **releaseNotifications** method

      '
    1.0.6: '* Making **patient.surname** field optional in *BookSlotRequest*

      '
    1.0.5: '* Removing **slot-changed** notification callback.

      '
    1.0.4: '* New (optional) property **address_id** for **MoveBookingRequest** (it is now possible to move booking to another address) * Changed **address_service_id** and **start** properties of **MoveBookingRequest** so they are required (documentation was missing it, they were already required in the API)

      '
    1.0.3: '* New (optional) property **description** for **AddCalendarBreakRequest** * New property **description** for **CalendarBreak**

      '
    1.0.2: '* Calendar breaks can be moved: adding **moveCalendarBreak** method for **CalendarBreaksApi** * New notification callback **break-moved**

      '
    1.0.1: '* Notification callbacks * IDs are now strings instead of integers

      '
servers:
- url: https://www.{domain}/api/v3/integration
  description: \{domain} - locale of docplanner marketplace ex. znanylekarz.pl
security:
- oauth2:
  - integration
tags:
- name: Doctors
  description: More information on how we define what a Doctors is, its use cases and more can be found here.
paths:
  /facilities/{facility_id}/doctors:
    parameters:
    - $ref: '#/components/parameters/facilityId'
    get:
      operationId: getDoctors
      description: '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'
      tags:
      - Doctors
      parameters:
      - $ref: '#/components/parameters/doctorsWith'
      responses:
        '200':
          description: List of doctors
          content:
            application/vnd.docplanner+json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Doctors'
              examples:
                Doctors:
                  $ref: '#/components/examples/Doctors'
                Doctors with doctor.profile_url:
                  $ref: '#/components/examples/DoctorsWithProfileUrl'
                Doctors with doctor.specializations:
                  $ref: '#/components/examples/DoctorsWithSpecializations'
                Doctors with doctor.license_numbers:
                  $ref: '#/components/examples/DoctorsWithLicenseNumbers'
        '403':
          description: You are not authorized to see this resource
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Facility:
                  $ref: '#/components/examples/FacilityNotAuthorized'
        '404':
          description: Resource not found
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Object not found:
                  $ref: '#/components/examples/ObjectNotFound'
      summary: Get doctors
      x-summary-source: derived
  /facilities/{facility_id}/doctors/{doctor_id}:
    parameters:
    - $ref: '#/components/parameters/facilityId'
    - $ref: '#/components/parameters/doctorId'
    get:
      operationId: getDoctor
      description: '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'
      tags:
      - Doctors
      parameters:
      - $ref: '#/components/parameters/doctorWith'
      responses:
        '200':
          description: Doctor data
          content:
            application/vnd.docplanner+json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Doctor'
              examples:
                Doctor:
                  $ref: '#/components/examples/Doctor'
                Doctor with doctor.profile_url:
                  $ref: '#/components/examples/DoctorWithProfileUrl'
                Doctor with doctor.license_numbers:
                  $ref: '#/components/examples/DoctorWithLicenseNumbers'
                Doctor with doctor.addresses:
                  $ref: '#/components/examples/DoctorWithAddresses'
                Doctor with doctor.addresses and address.online_only:
                  $ref: '#/components/examples/DoctorWithOnlineOnlyAddresses'
                Doctor with doctor.addresses and address.visit_payment:
                  $ref: '#/components/examples/DoctorWithVisitPaymentAddresses'
                Doctor with doctor.addresses and address.booking_extra_fields:
                  $ref: '#/components/examples/DoctorWithAddressBookingExtraFields'
                Doctor with doctor.addresses and address.commercial_type:
                  $ref: '#/components/examples/DoctorWithAddressCommercialType'
        '403':
          description: You are not authorized to see this resource
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Facility:
                  $ref: '#/components/examples/FacilityNotAuthorized'
                Doctor:
                  $ref: '#/components/examples/DoctorNotAuthorized'
        '404':
          description: Resource not found
          content:
            application/vnd.error+docplanner+json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Object not found:
                  $ref: '#/components/examples/ObjectNotFound'
      summary: Get doctor
      x-summary-source: derived
components:
  examples:
    DoctorWithAddresses:
      value:
        id: '123'
        name: Sample
        surname: Doctor 123
        addresses:
          _items:
          - id: '111'
            name: Example hospital
            post_code: xx-xxx
            street: Some street
        specializations:
          _items:
          - id: '12'
            name: Specialization example 12
    DoctorWithVisitPaymentAddresses:
      value:
        id: '123'
        name: Sample
        surname: Doctor 123
        addresses:
          _items:
          - id: '111'
            name: Example hospital
            post_code: xx-xxx
            street: Some street
            visit_payment: false
        specializations:
          _items:
          - id: '12'
            name: Specialization example 12
    DoctorNotAuthorized:
      value:
        errors: []
        message: You are not authorized to see this doctor
    DoctorWithAddressCommercialType:
      value:
        id: '123'
        name: Sample
        surname: Doctor 123
        addresses:
          _items:
          - id: '111'
            name: Example hospital
            post_code: xx-xxx
            street: Some street
            commercial_type: basic
        specializations:
          _items:
          - id: '12'
            name: Specialization example 12
    DoctorWithProfileUrl:
      value:
        id: '123'
        name: Sample
        surname: Doctor 123
        profile_url: http://url-to-doctors-profile
    ObjectNotFound:
      value:
        errors: []
        message: Object not found
    DoctorsWithSpecializations:
      value:
        _items:
        - id: '123'
          name: Sample
          surname: Doctor 123
          specializations:
            _items:
            - id: '12'
              name: Specialization example 12
        - id: '234'
          name: Sample
          surname: Doctor 234
          specializations:
            _items:
            - id: '23'
              name: Specialization example 23
    DoctorWithOnlineOnlyAddresses:
      value:
        id: '123'
        name: Sample
        surname: Doctor 123
        addresses:
          _items:
          - id: '111'
            name: Example hospital
            post_code: xx-xxx
            street: Some street
            is_online_only: true
        specializations:
          _items:
          - id: '12'
            name: Specialization example 12
    Doctor:
      value:
        id: '123'
        name: Sample
        surname: Doctor 123
        specializations:
          _items:
          - id: '12'
            name: Specialization example 12
    DoctorWithLicenseNumbers:
      value:
        id: '123'
        name: Sample
        surname: Doctor 123
        license_numbers:
          _items:
          - id: '12'
            license_number: License number 1
    DoctorWithAddressBookingExtraFields:
      value:
        id: '123'
        name: Sample
        surname: Doctor 123
        addresses:
          _items:
          - id: '111'
            name: Example hospital
            post_code: xx-xxx
            street: Some street
            booking_extra_fields:
              birth_date: true
              gender: true
              nin: true
        specializations:
          _items:
          - id: '12'
            name: Specialization example 12
    DoctorsWithProfileUrl:
      value:
        _items:
        - id: '123'
          name: Sample
          surname: Doctor 123
          profile_url: http://url-to-doctors-profile
        - id: '234'
          name: Sample
          surname: Doctor 234
          profile_url: http://url-to-doctors-profile
    Doctors:
      value:
        _items:
        - id: '123'
          name: Sample
          surname: Doctor 123
        - id: '234'
          name: Sample
          surname: Doctor 234
    DoctorsWithLicenseNumbers:
      value:
        _items:
        - id: '123'
          name: Sample
          surname: Doctor 123
          license_numbers:
            _items:
            - id: '12'
              license_number: License number 1
        - id: '234'
          name: Sample
          surname: Doctor 234
          license_numbers:
            _items:
            - id: '23'
              license_number: License number 2
    FacilityNotAuthorized:
      value:
        errors: []
        message: You are not authorized to see this facility
  schemas:
    Address:
      type: object
      properties:
        id:
          type: string
          example: 333
        name:
          type:
          - string
          - 'null'
          example: Test hospital
        city_name:
          type:
          - string
          - 'null'
          example: Testing city
        post_code:
          type:
          - string
          - 'null'
          example: XX-XXX
        street:
          type:
          - string
          - 'null'
          example: Testing street
        is_online_only:
          type: boolean
          example: false
        visit_payment:
          type: boolean
          example: false
        booking_extra_fields:
          type: object
          properties:
            gender:
              type: boolean
              example: true
            nin:
              type: boolean
              example: true
            birth_date:
              type: boolean
              example: true
        commercial_type:
          type: string
          enum:
          - premium
          - saas-only
          - basic
          example: basic
        insurance_support:
          type: string
          enum:
          - private
          - insurance
          - private_and_insurance
          example: private
    DoctorScopes:
      type: string
      enum:
      - doctor.profile_url
      - doctor.addresses
      - doctor.license_numbers
      - address.booking_extra_fields
      - address.online_only
      - address.visit_payment
      - address.commercial_type
    DoctorsScopes:
      type: string
      enum:
      - doctor.profile_url
      - doctor.specializations
      - doctor.license_numbers
    Doctors:
      type: object
      properties:
        _items:
          type: array
          items:
            $ref: '#/components/schemas/Doctor'
    Doctor:
      type: object
      properties:
        id:
          type: string
          example: 123
        name:
          type: string
          example: Sample
        surname:
          type: string
          example: Doctor 123
        addresses:
          $ref: '#/components/schemas/Addresses'
        specialization:
          $ref: '#/components/schemas/Specializations'
        license_numbers:
          $ref: '#/components/schemas/LicenseNumbers'
    Specialization:
      type: object
      properties:
        id:
          type: string
          example: 12
        name:
          type: string
          example: Specialization example
    LicenseNumbers:
      type: object
      properties:
        _items:
          type: array
          items:
            $ref: '#/components/schemas/LicenseNumber'
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
        message:
          type: string
    Specializations:
      type: object
      properties:
        _items:
          type: array
          items:
            $ref: '#/components/schemas/Specialization'
    Addresses:
      type: object
      properties:
        _items:
          type: array
          items:
            $ref: '#/components/schemas/Address'
    LicenseNumber:
      type: object
      properties:
        id:
          type: string
          example: 12
        license_number:
          type: string
          example: License number
  parameters:
    doctorId:
      name: doctor_id
      in: path
      description: ID of a doctor in a facility
      example: 123
      required: true
      schema:
        type: string
    doctorsWith:
      name: with
      in: query
      required: false
      style: simple
      schema:
        type: array
        uniqueItems: true
        items:
          $ref: '#/components/schemas/DoctorsScopes'
    facilityId:
      name: facility_id
      in: path
      description: ID of the Facility
      example: 1
      required: true
      schema:
        type: string
    doctorWith:
      name: with
      in: query
      required: false
      style: simple
      schema:
        type: array
        uniqueItems: true
        items:
          $ref: '#/components/schemas/DoctorScopes'
  securitySchemes:
    oauth2:
      name: OAuth 2.0
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://www.{domain}/oauth/v2/token
          scopes:
            integration: API integration
      description: "The API utilizes the industry-standard [OAuth 2.0](https://tools.ietf.org/html/rfc6749) protocol.\n\nAll requests to our API must be authenticated and must include a valid access token.\n\n`NOTE! Our SSO Api version is v2 while our Integration Api version is v3`\n\nYou can get a token for testing purposes with cURL\n\n```\ncurl -u {client_id}:{client_secret} https://www.{domain}/oauth/v2/token -d 'grant_type=client_credentials&scope=integration'\n```\n\nA response example you can expect\n\n```\n{\n    \"access_token\": \"03807cb390319329bdf6c777d4dfae9c0d3b3c35\",\n    \"expires_in\": 3600,\n    \"token_type\": \"bearer\",\n    \"scope\": null\n}\n```\n\nAnd then with every request in the `request header` you should add your bearer token like so:\n\n```\nAuthorization: Bearer {access_token}\n```\n"