Data Exchange and Appointment Booking Process

The schemas below are reference shapes for the contract between Avoca and your API — they illustrate the information Avoca can send and expects back, and are tailored to your system’s actual field names and formats during the integration process. Existing production integrations use flatter, partner-specific payloads over the payload handshake. Optional blocks (e.g. notifications_sent) apply only if your system provides them — customer notifications are typically sent by your system, not by Avoca.

Inbound Data Schema (AI → Your APIs)

Booking Request Schema

{
  "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": "jane.doe@example.com",
        "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"
    }
  }
}

Availability Query Schema

{
  "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
    }
  }
}

Expected API Responses

Success – Availability Check

{
  "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
  }
}

Success – Booking Creation

{
  "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"
}

Error – Unavailable Slot

{
  "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"
}

Error – Validation Failure

{
  "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"
}

Error Codes We Expect

SLOT_UNAVAILABLE
VALIDATION_ERROR
CUSTOMER_NOT_FOUND
SERVICE_NOT_AVAILABLE
DUPLICATE_BOOKING
RATE_LIMIT_EXCEEDED
AUTHENTICATION_FAILED
AUTHORIZATION_FAILED
INTERNAL_SERVER_ERROR
SERVICE_UNAVAILABLE

Latency & Asynchronous Handling

Timeout Configuration

Availability queries: 5-second timeout
Booking creation: 10-second timeout
Customer updates: 5-second timeout
Webhook delivery: 30-second timeout

Retry Logic

Automatic retries: 3 attempts with exponential backoff (1 s, 2 s, 4 s)
Idempotency: All mutations include idempotency keys (Idempotency-Key: {unique_request_id})
Retry-safe: Only idempotent operations retried automatically
Circuit breaker: After 5 consecutive failures, 60-second cooldown period

Asynchronous Operations

POST /api/v1/bookings

202 Accepted response:

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

Polling:

GET /api/v1/jobs/job_abc123

Response:

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

Real-Time Conversational Handling – During live customer interactions (phone/chat):

User experience priority: Display “checking availability…” messaging
Progressive disclosure: Show partial results as they arrive
Graceful degradation: Offer callback/email options if systems slow
Optimistic UI: Tentatively show likely success while awaiting confirmation

Omnichannel Integration Flow

Voice Calls

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

SMS/Text

Customer texts request
AI parses intent from text
AI queries your APIs
AI responds via SMS with options
Customer replies with selection
AI creates booking
Confirmation sent via SMS

Email

Customer emails request
AI processes email (async acceptable)
AI drafts response with availability options
Customer clicks link or replies
Booking created upon customer action
Email confirmation sent

Cross-Channel Continuity

Each customer interaction includes a session_id for conversation tracking
Customers can start on one channel (call) and complete on another (email link)
APIs should support lookup by customer identifier across channels

Overview

Technical Overview

API Specifications

Operations

Integration Templates

Data Exchange & Booking Process

Data Exchange and Appointment Booking Process

Inbound Data Schema (AI → Your APIs)

Expected API Responses

Latency & Asynchronous Handling

Omnichannel Integration Flow

​Data Exchange and Appointment Booking Process

​Inbound Data Schema (AI → Your APIs)

​Expected API Responses

​Latency & Asynchronous Handling

​Omnichannel Integration Flow

Data Exchange and Appointment Booking Process

Inbound Data Schema (AI → Your APIs)

Expected API Responses

Latency & Asynchronous Handling

Omnichannel Integration Flow