Skip to main content
POST
/
scheduling
/
availability
curl -X POST https://api.avoca.ai/v1/scheduling/availability \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "service_type": "water_heater_repair",
    "zip_code": "90210",
    "date_range": {
      "start": "2024-01-20",
      "end": "2024-01-25"
    },
    "duration_minutes": 120,
    "urgency": "standard",
    "preferred_times": {
      "morning": true,
      "afternoon": true,
      "evening": false
    }
  }'

{
  "data": {
    "available_slots": [
      {
        "date": "2024-01-20",
        "time_slots": [
          {
            "start": "09:00",
            "end": "11:00",
            "technician_id": "tech_123",
            "technician_name": "John Smith",
            "arrival_window": "9:00 AM - 11:00 AM",
            "capacity_available": true
          },
          {
            "start": "14:00",
            "end": "16:00",
            "technician_id": "tech_456",
            "technician_name": "Mike Johnson",
            "arrival_window": "2:00 PM - 4:00 PM",
            "capacity_available": true
          }
        ]
      },
      {
        "date": "2024-01-21",
        "time_slots": [
          {
            "start": "10:00",
            "end": "12:00",
            "technician_id": "tech_789",
            "technician_name": "Sarah Davis",
            "arrival_window": "10:00 AM - 12:00 PM",
            "capacity_available": true
          }
        ]
      }
    ],
    "booking_fee": {
      "amount": 0,
      "applies_after": "2024-01-22",
      "reason": null
    },
    "service_area_available": true,
    "next_available": null
  },
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2024-01-19T15:00:00Z"
  }
}
This endpoint returns real-time availability for service appointments based on technician schedules, service area, and job requirements.

​
Request

​
service_type
string
required
Type of service needed. Common types:
  • drain_cleaning
  • water_heater_repair
  • water_heater_install
  • leak_repair
  • toilet_repair
  • faucet_repair
  • emergency_service
  • plumbing_inspection
​
zip_code
string
required
Service location ZIP code
​
date_range
object
required
Date range to check for availability
​
duration_minutes
number
default:"120"
Estimated duration for the service in minutes
​
urgency
string
default:"standard"
Service urgency level:
  • emergency - Same day service required
  • urgent - Within 24-48 hours
  • standard - Normal scheduling
​
preferred_times
object
Customer’s preferred appointment times
​
technician_id
string
Request specific technician (if customer has preference)

​
Response

​
available_slots
array
Array of available days with time slots
​
booking_fee
object
Information about any booking fees
​
service_area_available
boolean
Whether the ZIP code is in service area
​
next_available
object
Next available appointment if no slots in range
curl -X POST https://api.avoca.ai/v1/scheduling/availability \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "service_type": "water_heater_repair",
    "zip_code": "90210",
    "date_range": {
      "start": "2024-01-20",
      "end": "2024-01-25"
    },
    "duration_minutes": 120,
    "urgency": "standard",
    "preferred_times": {
      "morning": true,
      "afternoon": true,
      "evening": false
    }
  }'

{
  "data": {
    "available_slots": [
      {
        "date": "2024-01-20",
        "time_slots": [
          {
            "start": "09:00",
            "end": "11:00",
            "technician_id": "tech_123",
            "technician_name": "John Smith",
            "arrival_window": "9:00 AM - 11:00 AM",
            "capacity_available": true
          },
          {
            "start": "14:00",
            "end": "16:00",
            "technician_id": "tech_456",
            "technician_name": "Mike Johnson",
            "arrival_window": "2:00 PM - 4:00 PM",
            "capacity_available": true
          }
        ]
      },
      {
        "date": "2024-01-21",
        "time_slots": [
          {
            "start": "10:00",
            "end": "12:00",
            "technician_id": "tech_789",
            "technician_name": "Sarah Davis",
            "arrival_window": "10:00 AM - 12:00 PM",
            "capacity_available": true
          }
        ]
      }
    ],
    "booking_fee": {
      "amount": 0,
      "applies_after": "2024-01-22",
      "reason": null
    },
    "service_area_available": true,
    "next_available": null
  },
  "meta": {
    "request_id": "req_def456",
    "timestamp": "2024-01-19T15:00:00Z"
  }
}