# AI Receptionist API — Complete LLM Reference

> White-label AI receptionist API. Create conversational AI receptionists that handle customer inquiries, capture leads, book appointments, and send SMS — all via RESTful endpoints.

## Overview
AI Receptionist is a REST API that lets you deploy AI-powered receptionists for any business. Each receptionist is trained on the business's services, pricing, FAQs, and brand voice. Receptionists handle customer conversations via web chat and SMS, automatically capture leads, and book appointments.

## API Base URL
https://aireceptionist.fit/api

## Authentication
All API requests require a Bearer token in the Authorization header.
- Header: Authorization: Bearer air_your_key
- Key format: Starts with "air_"
- Get your key: https://aireceptionist.fit/signup

## Response Headers (All Endpoints)
Every API response includes these headers:
- X-Request-Id: Unique request identifier (e.g., req_abc123def456) for tracing
- X-Credits-Remaining: Credits left in current billing period
- X-Credits-Reset: ISO 8601 timestamp when credits reset (e.g., 2026-07-01T00:00:00Z)

---

## Endpoints

### POST /v1/receptionists
Create a new AI receptionist trained on a specific business.

**Cost:** 0 credits
**Latency:** <2s typical

**Request Body (JSON):**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| businessName | string | yes | Name of the business |
| industry | string | yes | Industry (dental, real_estate, legal, home_services, restaurant, automotive, general) |
| greeting | string | no | Custom greeting message (default: "Welcome! How can I help you today?") |
| personality | string | no | Personality description |
| tone | string | no | Tone (professional, friendly, casual) |
| faqs | array | no | Array of {question, answer} objects |
| services | string | no | Comma-separated list of services |
| hours | string | no | Business hours description |
| webhookUrl | string | no | URL for webhook notifications |

**Response (201):**
```json
{
  "success": true,
  "receptionist": {
    "id": "rec_abc123",
    "businessName": "Sunrise Dental",
    "industry": "dental",
    "greeting": "Welcome to Sunrise Dental!",
    "status": "active"
  }
}
```

---

### POST /v1/chat
Send a message to an AI receptionist and get a response.

**Cost:** 1 credit per message
**Latency:** 1-3s typical

**Request Body (JSON):**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| receptionistId | string | yes | ID of the receptionist |
| message | string | yes | Customer's message |
| conversationId | string | no | Existing conversation ID for context continuity |
| visitorName | string | no | Visitor's name for personalization |
| visitorEmail | string | no | Visitor's email for lead capture |
| visitorPhone | string | no | Visitor's phone for lead capture |

**Response (200):**
```json
{
  "success": true,
  "response": "Hello! Welcome to Sunrise Dental. How can I help you today?",
  "conversationId": "conv_xyz789",
  "leadCaptured": false
}
```

---

### GET /v1/leads
Retrieve leads captured by your receptionists.

**Cost:** 0 credits
**Latency:** <500ms typical

**Query Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| receptionistId | string | no | Filter by receptionist |
| status | string | no | Filter by status (new, contacted, qualified, converted) |
| page | integer | no | Page number (default: 1) |
| limit | integer | no | Results per page (default: 50, max: 100) |

**Response (200):**
```json
{
  "success": true,
  "leads": [
    {
      "id": "lead_abc123",
      "name": "John Smith",
      "email": "john@example.com",
      "phone": "+15551234567",
      "company": "Acme Corp",
      "status": "new",
      "source": "web_chat",
      "receptionistId": "rec_abc123",
      "createdAt": "2026-06-15T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "pages": 1
}
```

---

### POST /v1/sms
Send an SMS message from a receptionist's dedicated phone number.

**Cost:** 1 credit per message
**Latency:** <2s typical

**Request Body (JSON):**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| receptionistId | string | yes | ID of the receptionist with a provisioned number |
| to | string | yes | Recipient phone number (E.164 format) |
| message | string | yes | SMS message text (max 1600 chars) |

**Response (200):**
```json
{
  "success": true,
  "messageId": "msg_abc123",
  "from": "+15559876543",
  "to": "+15551234567",
  "status": "sent"
}
```

---

### GET /v1/usage
Monitor your current month's API usage and plan limits.

**Cost:** 0 credits
**Latency:** <500ms typical

**Response (200):**
```json
{
  "success": true,
  "plan": "api_growth",
  "period": {
    "start": "2026-06-01T00:00:00Z",
    "end": "2026-07-01T00:00:00Z"
  },
  "usage": {
    "conversations": { "used": 4521, "limit": 10000 },
    "sms": { "used": 892, "limit": 5000 },
    "voiceCalls": { "used": 156, "limit": 1000 },
    "receptionists": { "used": 12, "limit": 50 }
  }
}
```

---

### GET /v1/receptionists
List all receptionists in your account.

**Cost:** 0 credits
**Latency:** <500ms typical

**Response (200):**
```json
{
  "success": true,
  "receptionists": [
    {
      "id": "rec_abc123",
      "businessName": "Sunrise Dental",
      "industry": "dental",
      "status": "active",
      "createdAt": "2026-06-01T12:00:00Z"
    }
  ]
}
```

---

### GET /v1/receptionists/{id}
Get detailed information about a specific receptionist.

**Cost:** 0 credits
**Latency:** <500ms typical

---

### PUT /v1/receptionists/{id}
Update a receptionist's settings (name, greeting, tone, FAQs, etc).

**Cost:** 0 credits
**Latency:** <2s typical

---

### DELETE /v1/receptionists/{id}
Permanently delete a receptionist and all associated data.

**Cost:** 0 credits

---

### GET /v1/appointments
List appointments booked through your receptionists.

**Cost:** 0 credits
**Latency:** <500ms typical

**Query Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| receptionistId | string | no | Filter by receptionist |
| status | string | no | Filter by status |
| upcoming | boolean | no | Only future appointments |
| page | integer | no | Page number (default: 1) |

---

### GET /v1/webhooks
List all configured webhook endpoints.

**Cost:** 0 credits
**Plan:** API Growth or API Scale

---

### POST /v1/webhooks
Register a new webhook endpoint to receive real-time events.

**Cost:** 0 credits
**Plan:** API Growth or API Scale

**Request Body (JSON):**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string | yes | HTTPS endpoint URL |
| events | string[] | yes | Event types to subscribe to |
| description | string | no | Human-readable description |

**Available Events:**
`lead.created`, `lead.updated`, `conversation.started`, `conversation.completed`, `conversation.flagged`, `appointment.booked`, `appointment.cancelled`, `receptionist.created`, `receptionist.updated`, `receptionist.deleted`, `sms.received`, `voice.completed`, `*` (all events)

**Response (201):**
```json
{
  "success": true,
  "webhook": {
    "id": "wh_abc123",
    "url": "https://your-app.com/webhooks",
    "events": ["lead.created", "appointment.booked"],
    "secret": "whsec_abc123..." // Only shown once!
  }
}
```

---

### PUT /v1/webhooks/{id}
Update webhook URL, events, or active status.

---

### DELETE /v1/webhooks/{id}
Remove a webhook endpoint.

---

### Webhook Signature Verification
Every delivery includes `X-Webhook-Signature` header (HMAC-SHA256):
```
t=1719000000,v1=<hex_signature>
```
Verify by computing `HMAC-SHA256(secret, timestamp + "." + body)`.

---

## Error Taxonomy

All errors return structured JSON:
```json
{
  "success": false,
  "request_id": "req_abc123def456",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "category": "rate_limit",
    "message": "Rate limit exceeded. Max 50 requests per second on Growth plan.",
    "retryable": true,
    "retry_after_seconds": 2,
    "suggestion": "Wait 2 seconds and retry the request."
  }
}
```

### Error Codes
| Code | Category | HTTP | Retryable | Description |
|------|----------|------|-----------|-------------|
| MISSING_API_KEY | authentication | 401 | false | No Authorization header provided |
| INVALID_API_KEY | authentication | 401 | false | API key doesn't exist or is malformed |
| API_KEY_DEACTIVATED | authorization | 403 | false | API key has been deactivated |
| RATE_LIMIT_EXCEEDED | rate_limit | 429 | true | Per-second rate limit exceeded |
| MONTHLY_QUOTA_EXCEEDED | quota | 429 | true | Monthly conversation/SMS quota exceeded |
| VALIDATION_ERROR | validation | 400 | false | Invalid request parameters |
| RECEPTIONIST_NOT_FOUND | validation | 404 | false | Specified receptionist ID not found |
| RENDER_FAILED | server | 500 | true | Internal processing error |

---

## Pricing

### API Starter — $149/month
- 1,000 conversations/month
- 500 SMS messages/month
- 100 voice minutes/month
- 5 receptionists
- 10 requests/second
- Cost per conversation: ~$0.15

### API Growth — $699/month
- 10,000 conversations/month
- 5,000 SMS messages/month
- 500 voice minutes/month
- 50 receptionists
- 50 requests/second
- Cost per conversation: ~$0.07

### API Scale — $2,999/month
- 50,000 conversations/month
- 25,000 SMS messages/month
- 2,500 voice minutes/month
- Unlimited receptionists
- 200 requests/second
- Cost per conversation: ~$0.06

All plans are billed as a fixed monthly price with included usage allowances (conversations, SMS, voice minutes). No hidden fees. Requests beyond quota return 429 with structured error.

---

## Rate Limiting
Rate limits are per API key, per second:
- API Starter: 10 req/sec
- API Growth: 50 req/sec
- API Scale: 200 req/sec

Exceeding the rate limit returns HTTP 429 with:
- Retry-After header (seconds)
- Structured error with retryable: true

---

## Webhook Payloads
Configure webhookUrl on receptionist creation to receive real-time notifications.

### lead.captured
```json
{
  "event": "lead.captured",
  "receptionistId": "rec_abc123",
  "lead": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+15551234567"
  },
  "timestamp": "2026-06-15T10:30:00Z"
}
```

### conversation.completed
```json
{
  "event": "conversation.completed",
  "receptionistId": "rec_abc123",
  "conversationId": "conv_xyz789",
  "messageCount": 8,
  "duration": 245,
  "timestamp": "2026-06-15T10:35:00Z"
}
```

---

## Discovery & Machine-Readable Specs
- OpenAPI Spec: https://aireceptionist.fit/api/openapi.json
- AI Plugin: https://aireceptionist.fit/.well-known/ai-plugin.json
- ARD Catalog: https://aireceptionist.fit/.well-known/ai-catalog.json
- Trust Manifest: https://aireceptionist.fit/.well-known/trust-manifest.json
- LLM Summary: https://aireceptionist.fit/llms.txt
- LLM Full Reference: https://aireceptionist.fit/llms-full.txt
- Human Docs: https://aireceptionist.fit/developers

---

## SDKs & Libraries
- JavaScript/Node.js: https://github.com/Trade-Media-Group-LLC/aireceptionist-js
- Python: https://github.com/Trade-Media-Group-LLC/aireceptionist-python
- MCP Server: https://github.com/Trade-Media-Group-LLC/aireceptionist-mcp

## Changelog
https://aireceptionist.fit/changelog

## Contact
- Email: support@aireceptionist.fit
- Website: https://aireceptionist.fit
- AI Agent Page: https://aireceptionist.fit/for-ai-agents