AI Receptionist API Integration Guide: From Zero to Production in 1 Day

Why Build on the AI Receptionist API?

If you're building an AI agent platform, SaaS product, or managed service that needs customer-facing AI conversations, you have two choices: build the entire stack from scratch (LLM orchestration, conversation management, lead capture, SMS integration, calendar booking) or integrate a purpose-built API that handles all of it.

The AI Receptionist API gives your platform instant access to AI-powered customer interactions through six simple REST endpoints. This guide walks you through a production integration in under a day.

Prerequisites

• An AI Receptionist account with an API plan subscription
• Your API key (starts with air_)
• Any HTTP client (curl, fetch, axios, etc.)

Step 1: Create Your First Receptionist

Every AI interaction starts with a receptionist. Think of it as a configured AI agent with specific knowledge about a business.

const response = await fetch('https://aireceptionist.fit/api/v1/receptionists', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer air_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    businessName: 'Sunrise Dental',
    industry: 'dental',
    greeting: 'Welcome to Sunrise Dental! How can I help you today?',
    tone: 'friendly',
    faqs: [
      { question: 'What insurance do you accept?', answer: 'We accept most PPO plans including Delta, Cigna, and Aetna.' },
      { question: 'What are your hours?', answer: 'Monday-Friday 8am-6pm, Saturday 9am-2pm.' }
    ]
  })
});
const receptionist = await response.json();
console.log('Created receptionist:', receptionist.id);

Step 2: Send a Customer Message

Once you have a receptionist ID, you can start conversations:

const chatResponse = await fetch('https://aireceptionist.fit/api/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer air_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    receptionistId: receptionist.id,
    message: 'Do you take walk-ins on Saturday?',
    visitorName: 'Sarah Johnson',
    visitorEmail: '[email protected]'
  })
});
const { reply, conversationId, leadCaptured } = await chatResponse.json();
// reply: "Yes! We welcome walk-ins on Saturdays from 9am to 2pm..."

The API automatically handles conversation context, so follow-up messages in the same conversation maintain full history.

Step 3: Retrieve Captured Leads

When visitors share their name, email, or phone during conversations, the AI automatically captures them as leads:

const leadsResponse = await fetch(
  'https://aireceptionist.fit/api/v1/leads?status=new&limit=50',
  { headers: { 'Authorization': 'Bearer air_your_api_key' } }
);
const { leads, total, page } = await leadsResponse.json();
// Each lead includes: name, email, phone, source, createdAt, receptionistId

Step 4: Monitor Usage

const usageResponse = await fetch(
  'https://aireceptionist.fit/api/v1/usage',
  { headers: { 'Authorization': 'Bearer air_your_api_key' } }
);
const { conversations, smsMessages, calendarBookings, limits } = await usageResponse.json();

Best Practices

• Store receptionist IDs in your database — Map each of your clients to their AI Receptionist ID for easy management
• Use descriptive FAQs — The more specific your FAQs, the better the AI performs. Include pricing, hours, location, and common objections.
• Set the right tone — Options include professional, friendly, casual. Match it to the business type.
• Monitor usage weekly — Set up alerts when you approach plan limits so you can upgrade proactively.
• Cache receptionist data — Receptionist configurations don't change often. Cache the list and refresh periodically.

Common Pitfalls

• Missing the Authorization header — All requests require Bearer air_your_key. You'll get a 401 without it.
• Not passing conversationId for follow-ups — If you want multi-turn conversations, pass the conversationId from the first response.
• Generic FAQs — "We provide great service" tells the AI nothing. Be specific: "Root canals cost $800-1200 depending on insurance coverage."

Ready to build? Check the full API documentation and get your API key in minutes.