{
  "booking": {
    "slot_id": "SLOT-789",
    "service": {
      "type": "inspection",
      "category": "residential",
      "add_ons": ["express_service"],
      "duration_minutes": 60
    },
    "customer": {
      "id": "CUST-123",
      "name": {
        "first": "Jane",
        "last": "Doe"
      },
      "contact": {
        "email": "[email protected]",
        "phone": "+15550123",
        "preferred_method": "sms"
      },
      "address": {
        "street_1": "123 Main St",
        "street_2": "Apt 4B",
        "city": "Springfield",
        "state": "IL",
        "zip": "62701",
        "country": "US"
      }
    },
    "preferences": {
      "language": "en",
      "special_requests": "Please call before arrival",
      "accessibility_needs": [],
      "notification_preferences": {
        "booking_confirmation": ["email", "sms"],
        "reminder_24h": ["sms"],
        "reminder_2h": ["sms"]
      }
    },
    "metadata": {
      "source": "voice_call",
      "campaign_id": "CAMP-456",
      "referral_code": "REF123",
      "notes": "Customer mentioned urgent need"
    }
  }
}

{
  "query": {
    "service_type": "inspection",
    "location": {
      "id": "LOC-123",
      "or_zip": "62701",
      "radius_miles": 25
    },
    "date_range": {
      "start": "2025-11-01T00:00:00Z",
      "end": "2025-11-07T23:59:59Z"
    },
    "time_preferences": {
      "preferred_times": ["morning", "afternoon"],
      "avoid_days": ["sunday"],
      "earliest_time": "08:00",
      "latest_time": "17:00"
    },
    "provider_preferences": {
      "provider_id": "PROV-456",
      "attributes": ["certified", "experienced"]
    },
    "filters": {
      "max_price": 200.0,
      "duration_minutes": 60
    }
  }
}

{
  "status": "success",
  "request_id": "req_abc123",
  "data": {
    "available_slots": [
      {
        "slot_id": "SLOT-789",
        "start_time": "2025-11-01T09:00:00Z",
        "end_time": "2025-11-01T10:00:00Z",
        "provider": {
          "id": "PROV-456",
          "name": "John Smith",
          "credentials": ["Licensed Inspector"],
          "rating": 4.8
        },
        "location": {
          "id": "LOC-123",
          "name": "Downtown Office",
          "address": "456 Oak Ave, Springfield, IL"
        },
        "pricing": {
          "base_price": 150.0,
          "add_ons": [],
          "total": 150.0,
          "currency": "USD"
        },
        "availability_score": 0.95
      }
    ],
    "total_available": 15,
    "search_parameters": {}
  },
  "metadata": {
    "response_time_ms": 145,
    "cached": false
  }
}

{
  "status": "success",
  "request_id": "req_def456",
  "data": {
    "booking": {
      "id": "BOOK-12345",
      "confirmation_number": "CONF-ABC123",
      "status": "confirmed",
      "appointment": {
        "start_time": "2025-11-01T09:00:00Z",
        "end_time": "2025-11-01T10:00:00Z",
        "timezone": "America/Chicago"
      },
      "service": {},
      "customer": {},
      "provider": {},
      "location": {},
      "pricing": {},
      "notifications_sent": {
        "confirmation_email": true,
        "confirmation_sms": true
      }
    },
    "next_steps": {
      "customer_actions": [
        "Check email for confirmation details",
        "Add to calendar via provided link"
      ],
      "preparation_instructions": "Please arrive 5 minutes early"
    }
  },
  "created_at": "2025-10-31T14:30:00Z"
}

{
  "status": "error",
  "request_id": "req_ghi789",
  "error": {
    "code": "SLOT_UNAVAILABLE",
    "message": "The requested time slot is no longer available",
    "type": "booking_conflict",
    "details": {
      "slot_id": "SLOT-789",
      "reason": "recently_booked",
      "alternative_slots": [
        {
          "slot_id": "SLOT-790",
          "start_time": "2025-11-01T10:00:00Z"
        }
      ]
    },
    "recoverable": true,
    "suggested_action": "query_alternative_times"
  },
  "timestamp": "2025-10-31T14:30:15Z"
}

{
  "status": "error",
  "request_id": "req_jkl012",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "type": "client_error",
    "details": {
      "field_errors": [
        {
          "field": "customer.phone",
          "error": "invalid_format",
          "message": "Phone number must include country code",
          "provided_value": "555-0123"
        },
        {
          "field": "service_type",
          "error": "invalid_value",
          "message": "Service type 'unknown' is not recognized",
          "valid_values": ["inspection", "maintenance", "repair"]
        }
      ]
    },
    "recoverable": true,
    "suggested_action": "correct_parameters_and_retry"
  },
  "timestamp": "2025-10-31T14:30:15Z"
}

POST /api/v1/bookings

{
  "status": "processing",
  "job_id": "job_abc123",
  "status_url": "/api/v1/jobs/job_abc123",
  "estimated_completion": "2025-10-31T14:31:00Z"
}

GET /api/v1/jobs/job_abc123

{
  "status": "completed",
  "result": {}
}

1. Customer calls → Avoca AI answers
2. AI extracts intent (book appointment)
3. AI queries availability API in real time
4. AI presents options to customer verbally
5. Customer selects option
6. AI calls booking creation API
7. AI confirms booking details verbally
8. AI sends confirmation via SMS/email (your notification APIs or ours)

1. Customer texts request
2. AI parses intent from text
3. AI queries your APIs
4. AI responds via SMS with options
5. Customer replies with selection
6. AI creates booking
7. Confirmation sent via SMS

1. Customer emails request
2. AI processes email (async acceptable)
3. AI drafts response with availability options
4. Customer clicks link or replies
5. Booking created upon customer action
6. Email confirmation sent