Receptionists

A receptionist is a fully functional AI voice agent that answers calls, checks calendar availability, books appointments, and follows up over SMS. This page covers the full lifecycle: create, poll or listen for readiness, update, and suspend.

How provisioning works

POST /api/v1/receptionists returns 202 Accepted immediately while provisioning completes asynchronously. Provisioning typically takes 10 to 30 seconds.

curl -X POST https://app.autorev.ai/api/v1/receptionists \
  -H "Authorization: Bearer ar_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "business_name": "Acme HVAC",
    "industry": "hvac"
  }'

Response (202 Accepted)
{
  "id": "uuid",
  "status": "provisioning",
  "created_at": "2026-03-11T12:00:00Z"
}

Wait until the receptionist is ready in one of two ways:

Poll: call GET /api/v1/receptionists/:id until status changes from provisioning to active.
Webhook: register a webhook subscription for the receptionist.ready event. A receptionist.error event fires if async provisioning or the post-provision database update fails.

List responses also expose the provisioning state directly:

GET /api/v1/receptionists (excerpt)
{
  "data": [
    {
      "id": "uuid",
      "status": "active",
      "business_name": "Acme HVAC",
      "phone_number": "+16145551234",
      "provisioning_status": "complete",
      "provisioning_error": null,
      "created_at": "2026-03-01T12:00:00Z"
    }
  ]
}

provisioning_status is one of pending, in_progress, complete, or error. When it is error, provisioning_error carries the failure message.

Plan limits (409)

The number of active receptionists is capped by your plan. If the cap is reached, POST /api/v1/receptionists returns 409. Delete an existing receptionist to free a slot, or contact support@autorev.ai to raise the cap.

Request body

POST /api/v1/receptionists
{
  "business_name": "Acme HVAC",
  "industry": "hvac",
  "business_hours": {
    "schedule": {
      "weekdays": "8:00 AM - 5:00 PM",
      "weekends": "Closed"
    },
    "service_area": ["43068"]
  },
  "voice": {
    "greeting": "Thank you for calling Acme HVAC!"
  },
  "system_prompt": "You are a helpful...",
  "calendar": {
    "api_key": "cal_live_...",
    "event_type_id": 12345,
    "booking_link": "https://cal.com/acme/30min",
    "timezone": "America/New_York"
  },
  "webhook_url": "https://your-app.com/webhooks/autorev"
}

Only business_name is required. industry is required unless you provide a system_prompt: with a custom system_prompt, no industry or playbook is needed and the receptionist can be any kind of AI agent, not just a service business.

Industries

When you provide an industry, the receptionist gets a production-tested call flow with 10 structured steps for greeting, availability checking, phone verification, address collection, and booking. Each industry comes with tailored emergency keywords, service descriptions, and booking flows. The AI handles emergency triage, offers 2-hour appointment windows, verifies caller ID, and confirms bookings with SMS automatically.

Industry key	Description
`hvac`	HVAC, heating, cooling, air quality
`plumbing`	Pipes, drains, water heaters, leak repairs
`electrical`	Wiring, outlets, panels, lighting, generators
`roofing`	Roof repair, replacement, storm damage
`landscaping`	Lawn care, tree service, irrigation
`pool_service`	Pool cleaning, maintenance, equipment repair
`cleaning`	Residential and commercial cleaning
`automotive`	Auto repair, maintenance, towing
`home-repair`	Handyman, general repairs, maintenance
`other`	Generic service business

The 6 built-in tools

Every receptionist ships with six tools the AI uses automatically during calls. No configuration is needed, and the tools remain available even when you override the playbook with a custom system_prompt.

Tool	What it does
`check_availability`	Queries open time slots before offering options
`get_caller_info`	Looks up the caller's phone number via caller ID
`create_booking`	Books the appointment and sends SMS confirmation
`quote_estimate`	Provides price ranges when customers ask
`handoff_sms`	Sends callback requests via SMS
`update_crm_note`	Logs notes about the call

The receptionist is also date/time aware: it always knows the current date and handles relative dates like "tomorrow" and "next week".

Phone number sharing and `skip_phone_provisioning`

By default, phone provisioning is skipped. New receptionists share the tenant's existing primary phone number for outbound calls, and only one receptionist per account handles inbound calls.

Set skip_phone_provisioning: false in the create request body to buy a dedicated number for the receptionist. Receptionists without a dedicated number can still make outbound calls using the tenant's primary phone number.

Voice options

Set voice options in the voice object on create or PATCH:

Field	Values
`voice_id`	`rachel` (professional female, default), `james` (confident male), `emma` (friendly female), `david` (calm male)
`style`	`professional`, `friendly` (default), `efficient`
`greeting`	Custom greeting text spoken when a call connects

Voice AI uses a professional ElevenLabs voice with optimized latency.

Get a receptionist

GET /api/v1/receptionists/:id returns full detail with usage stats:

Response
{
  "id": "uuid",
  "status": "active",
  "business_name": "Acme HVAC",
  "phone_number": "+16145551234",
  "settings": {
    "industry": "hvac",
    "business_hours": { "schedule": { "weekdays": "8:00 AM - 5:00 PM" } },
    "voice": { "voice_id": "rachel", "style": "friendly", "greeting": "Thank you for calling!" },
    "system_prompt": "You are a helpful...",
    "webhook_url": "https://your-app.com/webhooks/autorev"
  },
  "stats": {
    "total_calls": 47,
    "total_minutes": 142,
    "total_bookings": 12
  },
  "created_at": "2026-03-01T12:00:00Z",
  "updated_at": "2026-03-10T15:30:00Z"
}

Update a receptionist (PATCH semantics)

PATCH /api/v1/receptionists/:id updates settings. All fields are optional; send only what you want to change. Changes are automatically synced to the voice AI and are live on the next call.

Request body (all fields optional)
{
  "business_name": "Acme HVAC & Plumbing",
  "voice": {
    "greeting": "Hi, thanks for calling Acme!",
    "voice_id": "james",
    "style": "professional"
  },
  "system_prompt": "Updated instructions...",
  "business_hours": { "schedule": { "weekdays": "8:00 AM - 6:00 PM" } },
  "calendar": {
    "api_key": "cal_live_...",
    "event_type_id": 12345,
    "booking_link": "https://cal.com/acme/consultation",
    "timezone": "America/Chicago"
  },
  "webhook_url": "https://your-app.com/webhooks/autorev"
}

Pass calendar: null to disconnect the receptionist's calendar. See Bookings and Calendar for how the per-receptionist calendar works during calls.

Legacy webhook_url

The webhook_url field here is a legacy per-receptionist delivery target and does not expose a retrievable signing secret. For signed, verifiable webhooks use the Webhook Subscriptions API (POST /api/v1/webhooks), which returns a whsec_... signing secret once at creation.

Delete = suspend

DELETE /api/v1/receptionists/:id suspends the receptionist (soft delete):

Response
{ "id": "uuid", "status": "suspended" }

Not reversible via the API

Suspension cannot currently be reversed through the API. Contact support@autorev.ai to re-activate a suspended receptionist.

How provisioning works​

Plan limits (409)​

Request body​

Industries​

The 6 built-in tools​

Phone number sharing and skip_phone_provisioning​

Voice options​

Get a receptionist​

Update a receptionist (PATCH semantics)​

Delete = suspend​