> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avoca.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Data Exchange & Booking Process
> Schemas, response patterns, and omnichannel booking flows
# 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](/custom-integration/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**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```json theme={null}
{
"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**
```http theme={null}
POST /api/v1/bookings
```
`202 Accepted` response:
```json theme={null}
{
"status": "processing",
"job_id": "job_abc123",
"status_url": "/api/v1/jobs/job_abc123",
"estimated_completion": "2025-10-31T14:31:00Z"
}
```
Polling:
```http theme={null}
GET /api/v1/jobs/job_abc123
```
Response:
```json theme={null}
{
"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**
```
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)
```
**SMS/Text**
```
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
```
**Email**
```
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
```
**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