Skip to main content

Doctolib Integration Template

Integrate Germany’s leading doctor appointment platform Doctolib directly into your Mid-call Actions. Enable your customers to find doctors, check available appointments, and even book appointments – all while on the phone.

Overview & Features

Doctor Search Automation

  • Search for specialists based on location and specialty
  • Filter by insurance type (public/private)
  • Availability within defined timeframes
  • Radius-based search for optimal accessibility

Appointment Management

  • Real-time availability of doctor appointments
  • Automatic appointment booking during the call
  • Support for video consultations
  • Full patient data integration

Setting Up Doctolib API Access

1. Doctolib Developer Account

1

Developer Registration

  • Visit the Doctolib Developer Portal
  • Register as a healthcare integration partner
  • Submit your business license and data protection documentation
2

Obtain API Credentials

After approval, you will receive:
  - Client ID
  - Client Secret  
  - API environment (Sandbox/Production)
  - Rate limits and usage guidelines
3

OAuth 2.0 Setup

OAuth Configuration:
  Authorization URL: https://api.doctolib.de/oauth/authorize
  Token URL: https://api.doctolib.de/oauth/token
  Scopes: 
    - "read:practitioners"
    - "read:appointments" 
    - "write:appointments"

Tool 1: Doctor Search Tool

Configuration in Famulor Interface

FieldValue
Name*Doctolib Arztsuche
Description”Searches for available doctors and specialists based on location and specialty”
Function Name*search_doctolib_practitioners
Function Description*“Searches for doctors by specialty and location. Use this function when the patient is looking for a doctor nearby.”
HTTP MethodGET
Timeout (ms)5000
Endpoint*https://api.doctolib.de/practitioners/search

Parameter Schema

{
  "type": "object",
  "properties": {
    "speciality": {
      "type": "string",
      "description": "Medical specialty (e.g. 'General Medicine', 'Dentist', 'Orthopedics', 'Dermatology')",
      "examples": ["General Medicine", "Dentist", "Orthopedics", "Dermatology", "Gynecology"]
    },
    "location": {
      "type": "string", 
      "description": "Postal code or city for the doctor search"
    },
    "insurance_type": {
      "type": "string",
      "enum": ["public", "private", "both"],
      "description": "Insurance type: 'public' (statutory insured), 'private' (private insured), 'both' (both)"
    },
    "availability_days": {
      "type": "integer",
      "description": "Availability within the next X days",
      "minimum": 1,
      "maximum": 90,
      "default": 14
    },
    "radius": {
      "type": "integer",
      "description": "Search radius in kilometers",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    }
  },
  "required": ["speciality", "location"]
}

Response Mapping

{
  "practitioners": "data.practitioners",
  "total": "data.total_count",
  "searchRadius": "data.search_radius_km"
}

Natural Language Integration

Template: "I'm searching for {{speciality}} in {{location}} for you..."Examples:
  • “I’m searching for dentists in Munich for you…”
  • “I’ll look for general practitioners in 10115 Berlin…”
  • “I’m finding orthopedists in Hamburg who accept public insurance…”
I found {{total}} doctors. Dr. {{practitioners[0].name}} practices at {{practitioners[0].address}} and has the next available appointment on {{practitioners[0].next_availability}}. {{#if practitioners[1]}}Other options include Dr. {{practitioners[1].name}} at {{practitioners[1].address}}.{{/if}}

Tool 2: Appointment Slots Inquiry

Configuration in Famulor Interface

FieldValue
Name*Doctolib Terminslots
Description”Displays available appointments for a specific doctor”
Function Name*get_doctolib_slots
Function Description*“Retrieves available appointment slots. Use this function after a doctor has been selected to show concrete appointment options.”
HTTP MethodGET
Timeout (ms)5000
Endpoint*https://api.doctolib.de/practitioners/{practitioner_id}/availabilities

Parameter Schema for Appointment Inquiry

{
  "type": "object",
  "properties": {
    "practitioner_id": {
      "type": "string",
      "description": "Unique Doctolib ID of the doctor (from previous search)"
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "Start date for appointment search (YYYY-MM-DD)"
    },
    "end_date": {
      "type": "string",
      "format": "date", 
      "description": "End date for appointment search (YYYY-MM-DD)"
    },
    "motive_id": {
      "type": "string",
      "description": "ID of the treatment reason (optional, for specific appointment types)"
    },
    "telehealth": {
      "type": "boolean",
      "description": "Show only video consultations? (true/false)",
      "default": false
    }
  },
  "required": ["practitioner_id", "start_date"]
}

Response Handling

{
  "slots": "data.availabilities",
  "nextSlot": "data.availabilities[0]",
  "practitioner": "data.practitioner_info"
}

Tool 3: Appointment Booking

Configuration for Booking Tool

FieldValue
Name*Doctolib Termin buchen
Description”Books a doctor appointment via Doctolib”
Function Name*book_doctolib_appointment
Function Description*“Books a specific appointment with a doctor. Use this function only after all patient data is fully collected.”
HTTP MethodPOST
Timeout (ms)10000
Endpoint*https://api.doctolib.de/appointments

Complete Parameter Schema for Booking

{
  "type": "object",
  "properties": {
    "practitioner_id": {
      "type": "string",
      "description": "Doctor ID from the previous search"
    },
    "start_time": {
      "type": "string",
      "format": "date-time",
      "description": "Selected appointment time (ISO 8601 format)"
    },
    "motive_id": {
      "type": "string",
      "description": "Treatment reason ID"
    },
    "first_name": {
      "type": "string",
      "description": "Patient's first name"
    },
    "last_name": {
      "type": "string", 
      "description": "Patient's last name"
    },
    "birthdate": {
      "type": "string",
      "format": "date",
      "description": "Patient's date of birth (YYYY-MM-DD)"
    },
    "phone": {
      "type": "string",
      "description": "Patient's phone number"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Patient's email address"
    },
    "insurance_type": {
      "type": "string",
      "enum": ["public", "private"],
      "description": "Insurance type: 'public' (statutory) or 'private' (private)"
    },
    "insurance_number": {
      "type": "string",
      "description": "Insurance number (for statutory insurance)"
    },
    "comments": {
      "type": "string",
      "description": "Additional notes or complaints"
    }
  },
  "required": ["practitioner_id", "start_time", "first_name", "last_name", "phone"]
}

Complete Workflow

Step-by-Step Integration

Practical Conversation Example

Patient: “I need a dentist appointment in Munich.”AI Assistant: “I’d be glad to help. Are you insured publicly or privately?”Patient: “Publicly insured.”AI: “Perfect. I’m searching for dentists in Munich for you…”→ Tool: search_doctolib_practitioners
{
  "speciality": "Dentist",
  "location": "Munich", 
  "insurance_type": "public",
  "availability_days": 14,
  "radius": 25
}
AI: “I found 8 dentists. Dr. Schmidt on Maximilianstraße has an appointment available the day after tomorrow. Dr. Müller in Schwabing is available next week as well. Which practice would be more convenient for you?”Patient: “Dr. Schmidt sounds good.”AI: “I’m checking available appointments for Dr. Schmidt…”→ Tool: get_doctolib_slots
{
  "practitioner_id": "dr_schmidt_12345",
  "start_date": "2024-01-17",
  "end_date": "2024-01-31"
}
AI: “Dr. Schmidt has the following appointments available: Wednesday 14:30, Thursday 09:15, or Friday 16:00. What works best for you?”Patient: “Thursday 09:15 would be perfect.”AI: “Excellent! Now I need your details to complete the booking. What is your full name and birthdate?”→ Data collection → Tool: book_doctolib_appointmentAI: “Appointment booked! You have an appointment with Dr. Schmidt on Thursday, January 18 at 09:15. You will receive a confirmation via SMS and email.”
Emergency Appointments:
If patient says: "It’s an emergency"
→ availability_days: 1
→ Search for emergency hours
→ Prioritize availability today
Video Consultations:
If patient says: "Is this possible as a video consultation?"
→ telehealth: true
→ Extended appointment options
→ Online consultation possibilities
Multiple Specialties:
If patient says: "I also need an orthopedist"
→ Parallel search for multiple specialties
→ Appointment coordination
→ Optimized routing suggestions

Response Handling & Error Management

Typical API Responses

{
  "data": {
    "practitioners": [
      {
        "id": "dr_schmidt_12345",
        "name": "Dr. med. Schmidt",
        "speciality": "Dentist",
        "address": "Maximilianstraße 15, 80539 Munich",
        "phone": "+49 89 12345678",
        "rating": 4.8,
        "review_count": 127,
        "insurance_types": ["public", "private"],
        "next_availability": "2024-01-18T09:15:00Z",
        "distance_km": 2.3
      }
    ],
    "total_count": 8,
    "search_radius_km": 25
  }
}

Error Handling

No doctors found (404):
Fallback: "Unfortunately, I couldn’t find any available doctors in your area. 
          Would you like me to expand the search radius or try another city?"

Next-Action: 
  - Increase search radius
  - Suggest alternative cities
  - Offer other specialties
Possible_Causes:
  - Appointment already taken
  - Incomplete patient data
  - Insurance not accepted

Graceful_Handling:
  "I’m sorry, this appointment is no longer available. 
   I can offer you another available slot..."

Fallback_Actions:
  - Retrieve alternative appointment slots
  - Offer a waiting list
  - Suggest a different doctor
Rate_Limit_Exceeded (429):
  Fallback: "The doctor search is currently highly loaded. 
            May I try again in a few seconds?"
  
Retry_Logic:
  - Exponential backoff: 2s, 4s, 8s
  - Max 3 retry attempts
  - After 3 failures, offer manual alternative

Advanced Features

Integration with CRM Systems

CRM_Integration_Workflow:
  1. After successful booking:
     → Transfer patient data to CRM
     → Categorize appointment as "Healthcare Appointment"
     → Create a follow-up task for appointment reminder
  
  2. Existing patient recognition:
     → CRM lookup before creating new record
     → Pre-fill existing data
     → Preference-based doctor selection

Compliance & Data Protection

Privacy_by_Design:
  - Minimal data collection (only what is needed for booking)
  - Explicit consent before booking
  - Automatic data deletion after appointment date
  - Audit trail for all data processing

Patient_Rights:
  - Right to data portability
  - Right to deletion
  - Right to correction
  - Transparency about data use
Security_Measures:
  - End-to-end encryption for patient data
  - Secure API communication (TLS 1.3)
  - Access logging and monitoring
  - Regular security audits

Compliance_Standards:
  - BDSG compliance
  - TMG compliance
  - eHealth standards (DiGA-V compliant)

Performance & Monitoring

KPIs and Metrics

MetricTarget ValueCritical Value
Doctor Search Response Time<2 seconds>5 seconds
Booking Success Rate>90%<75%
Patient Satisfaction>4.5/5<4.0/5
API Availability>99.5%<97%

Monitoring Dashboard

1

Real-time Metrics

  • API response times for all three tools
  • Success / failure ratio
  • Current booking rate
  • Geographic heat map of requests
2

Business Intelligence

  • Most-requested specialties
  • Peak hours for appointment inquiries
  • Regional demand analysis
  • Patient demographics
3

Alerting System

  • High API error rate (>5%)
  • Unusual booking patterns (spam detection)
  • Low success rate (<80%)
  • Doctor API outages

Healthcare Integration Patterns

Expand your healthcare automation:
Medical-Legal Notice: The Doctolib integration is subject to strict healthcare compliance requirements. Ensure all data protection regulations are observed and that the integration complies with applicable telemedicine laws.
Pro Tip: Start with the doctor search functionality and gradually expand to appointment booking. Most patients already appreciate the fast doctor search, even if they book the appointment themselves.