Skip to main content
POST
/
scheduling
/
appointments
curl -X POST https://api.avoca.ai/v1/scheduling/appointments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "first_name": "John",
      "last_name": "Smith",
      "phone": "+13105559876",
      "email": "john.smith@email.com",
      "preferred_contact_method": "sms"
    },
    "service_location": {
      "address": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90210",
      "access_notes": "Gate code: 1234"
    },
    "service_details": {
      "type": "water_heater_repair",
      "description": "Water heater not producing hot water. Started yesterday morning.",
      "urgency": "standard"
    },
    "appointment_slot": {
      "date": "2024-01-20",
      "start_time": "09:00",
      "end_time": "11:00",
      "technician_id": "tech_123"
    },
    "source": "api",
    "notes": "Customer prefers morning appointments. Dog in backyard.",
    "marketing_consent": true
  }'

{
  "data": {
    "appointment_id": "appt_def456",
    "confirmation_number": "ABC-2024-0120",
    "servicetitan_job_id": "12345678",
    "status": "scheduled",
    "scheduled_time": {
      "date": "2024-01-20",
      "arrival_window": "9:00 AM - 11:00 AM",
      "technician": {
        "id": "tech_123",
        "name": "John Smith",
        "photo_url": "https://cdn.avoca.ai/technicians/tech_123.jpg"
      }
    },
    "notifications_sent": [
      "sms_confirmation",
      "email_confirmation",
      "calendar_invite"
    ],
    "estimated_cost": {
      "service_fee": 89.00,
      "estimated_total": "$89 - $350"
    },
    "reminders": [
      {
        "type": "sms",
        "scheduled_for": "2024-01-19T17:00:00Z"
      },
      {
        "type": "sms",
        "scheduled_for": "2024-01-20T07:00:00Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_ghi789",
    "timestamp": "2024-01-19T15:30:00Z"
  }
}
This endpoint books a service appointment using an available time slot. Always check availability first using the /scheduling/availability endpoint.

​
Request

​
customer
object
required
Customer information
​
service_location
object
required
Service address details
​
service_details
object
required
Details about the service needed
​
appointment_slot
object
required
Selected appointment slot
​
source
string
default:"api"
Booking source:
  • api
  • phone
  • web
  • sms
  • chat
​
notes
string
Additional notes for the technician
​
marketing_consent
boolean
Customer consent for marketing communications

​
Response

​
appointment_id
string
Unique identifier for the appointment
​
confirmation_number
string
Human-readable confirmation number
​
servicetitan_job_id
string
ServiceTitan job ID if integration is enabled
​
status
string
Appointment status:
  • scheduled - Successfully booked
  • pending_confirmation - Awaiting customer confirmation
  • waitlist - Added to waitlist
​
scheduled_time
object
Confirmed appointment details
​
notifications_sent
array
List of notifications sent to customer:
  • sms_confirmation
  • email_confirmation
  • calendar_invite
​
estimated_cost
object
Cost estimate if available
​
reminders
array
Scheduled reminder notifications
curl -X POST https://api.avoca.ai/v1/scheduling/appointments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "first_name": "John",
      "last_name": "Smith",
      "phone": "+13105559876",
      "email": "john.smith@email.com",
      "preferred_contact_method": "sms"
    },
    "service_location": {
      "address": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90210",
      "access_notes": "Gate code: 1234"
    },
    "service_details": {
      "type": "water_heater_repair",
      "description": "Water heater not producing hot water. Started yesterday morning.",
      "urgency": "standard"
    },
    "appointment_slot": {
      "date": "2024-01-20",
      "start_time": "09:00",
      "end_time": "11:00",
      "technician_id": "tech_123"
    },
    "source": "api",
    "notes": "Customer prefers morning appointments. Dog in backyard.",
    "marketing_consent": true
  }'

{
  "data": {
    "appointment_id": "appt_def456",
    "confirmation_number": "ABC-2024-0120",
    "servicetitan_job_id": "12345678",
    "status": "scheduled",
    "scheduled_time": {
      "date": "2024-01-20",
      "arrival_window": "9:00 AM - 11:00 AM",
      "technician": {
        "id": "tech_123",
        "name": "John Smith",
        "photo_url": "https://cdn.avoca.ai/technicians/tech_123.jpg"
      }
    },
    "notifications_sent": [
      "sms_confirmation",
      "email_confirmation",
      "calendar_invite"
    ],
    "estimated_cost": {
      "service_fee": 89.00,
      "estimated_total": "$89 - $350"
    },
    "reminders": [
      {
        "type": "sms",
        "scheduled_for": "2024-01-19T17:00:00Z"
      },
      {
        "type": "sms",
        "scheduled_for": "2024-01-20T07:00:00Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_ghi789",
    "timestamp": "2024-01-19T15:30:00Z"
  }
}