Guide: SMS to Voice Agent (HVAC Technician)

Use case: High-volume blue-collar hiring where you need to quickly screen candidates via SMS before scheduling a voice interview. Perfect for trades like HVAC, plumbing, electrical, and warehouse roles where candidates are often on the go and respond better to text messages first.

What You’ll Build

A two-stage hiring pipeline:

SMS Screening — An AI agent texts candidates to verify basic qualifications (license, availability, transportation) using yes/no and numeric questions. Candidates who fail dealbreaker criteria are automatically disqualified.
Voice Interview — Qualified candidates are invited to a voice interview where the AI asks role-specific questions and scores responses on a 1–5 scale.

Step 1: Create the Agent

Create a posting with a two-step workflow: SMS screening first, then a voice interview.

curl -X POST "https://api.heymilo.network/api/v4/postings" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "HVAC Technician",
    "description": "We are hiring experienced HVAC technicians for residential and commercial installations. Must hold a valid EPA 608 certification. 3+ years of experience with split systems, heat pumps, and ductwork required. CDL or reliable transportation needed. Competitive pay $28-42/hr depending on experience.",
    "interviewer_name": "Tyler",
    "language": "en",
    "company_overview": "CoolAir Solutions is a leading HVAC contractor serving the greater metro area since 2005.",
    "job_overview": "Install, maintain, and repair HVAC systems for residential and commercial clients.",
    "workflow": [
      {
        "type": "conversational_sms",
        "config": {
          "knockout_enabled": true
        },
        "questions": [
          {
            "modality": "sms",
            "text": "Do you hold a valid EPA 608 certification?",
            "question_type": "YES_NO",
            "expected_answer": "YES",
            "is_dealbreaker": true
          },
          {
            "modality": "sms",
            "text": "Do you have reliable transportation to job sites?",
            "question_type": "YES_NO",
            "expected_answer": "YES",
            "is_dealbreaker": true
          },
          {
            "modality": "sms",
            "text": "How many years of HVAC experience do you have?",
            "question_type": "NUMERIC",
            "expected_value": 3,
            "is_dealbreaker": true
          },
          {
            "modality": "sms",
            "text": "Are you available to start within 2 weeks?",
            "question_type": "YES_NO",
            "expected_answer": "YES",
            "is_dealbreaker": false
          }
        ]
      },
      {
        "type": "web_interview",
        "config": {
          "video": false,
          "num_questions": 5
        },
        "questions": [
          {
            "modality": "voice",
            "text": "Walk me through a typical residential HVAC installation from start to finish.",
            "evaluation_criteria": "Assess depth of hands-on experience with split systems and ductwork. Look for knowledge of load calculations, refrigerant handling, and code compliance.",
            "score_of_1": "Cannot describe basic installation steps or confuses key concepts.",
            "score_of_5": "Provides detailed, confident walkthrough covering equipment selection, ductwork, charging, and testing.",
            "question_type": "open-ended",
            "score_weight": 3.0,
            "max_follow_ups": 2
          },
          {
            "modality": "voice",
            "text": "Describe a challenging repair you diagnosed. How did you troubleshoot it?",
            "evaluation_criteria": "Evaluate systematic troubleshooting approach and diagnostic skill.",
            "score_of_1": "Vague answer with no specific example.",
            "score_of_5": "Describes methodical diagnosis using gauges, electrical testing, and logical elimination.",
            "question_type": "open-ended",
            "score_weight": 3.0,
            "max_follow_ups": 2
          },
          {
            "modality": "voice",
            "text": "How do you handle safety on the job, especially when working with refrigerants and electrical?",
            "evaluation_criteria": "Check awareness of OSHA standards, EPA regulations, and safe work practices.",
            "score_of_1": "Shows no awareness of safety protocols.",
            "score_of_5": "Demonstrates strong safety culture including PPE, lockout/tagout, and proper refrigerant handling.",
            "question_type": "open-ended",
            "score_weight": 2.0,
            "max_follow_ups": 1
          },
          {
            "modality": "voice",
            "text": "Tell me about a time you dealt with a difficult customer on a service call.",
            "evaluation_criteria": "Assess customer service skills and professionalism under pressure.",
            "score_of_1": "No example or shows poor attitude toward customers.",
            "score_of_5": "Shows empathy, clear communication, and a resolution-focused approach.",
            "question_type": "open-ended",
            "score_weight": 1.0,
            "max_follow_ups": 1
          },
          {
            "modality": "voice",
            "text": "What types of HVAC systems are you most experienced with?",
            "evaluation_criteria": "Gauge breadth of experience across system types (split, packaged, mini-split, commercial rooftop, heat pumps).",
            "score_of_1": "Only familiar with one system type.",
            "score_of_5": "Experienced with multiple residential and commercial system types.",
            "question_type": "open-ended",
            "score_weight": 2.0,
            "max_follow_ups": 1
          }
        ]
      }
    ]
  }'

Response:

{
  "object": "posting",
  "data": {
    "object": "posting",
    "id": "A1B2C3D4",
    "status": "active",
    "urls": {
      "candidate_url": "https://candidates.heymilo.io/coolair/hvac-technician",
      "ingestion_url_key": "ibURejyPMSlw6de0OZUdoxyoXTgWO78ey2NUo96EOG1gY",
      "review_url": "https://admin.heymilo.ai/w/WORKSPACE_ID/lab2/A1B2C3D4/1-details"
    },
    "created_at": 1739612400.0,
    "posting": { ... }
  }
}

Save the id (posting ID) from the response — you’ll need it for the next steps.

Tip: The SMS agent (Tyler) will automatically text candidates in a conversational style. The is_dealbreaker: true questions will immediately disqualify candidates who answer incorrectly. Only candidates who pass all dealbreakers will advance to the voice interview.

Step 2: Manage Questions After Creation

Once the agent is created, you can list, edit, reorder, or add new questions at any time using the Questions API.

List current questions

curl -X GET "https://api.heymilo.network/api/v4/postings/A1B2C3D4/questions" \
  -H "X-API-KEY: your_api_key_here"

Filter by modality

View only the SMS screening questions:

curl -X GET "https://api.heymilo.network/api/v4/postings/A1B2C3D4/questions?modality=sms" \
  -H "X-API-KEY: your_api_key_here"

Add a new SMS question

Maybe you realize you also want to ask about overtime availability:

curl -X POST "https://api.heymilo.network/api/v4/postings/A1B2C3D4/questions" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "modality": "sms",
    "text": "Are you willing to work overtime and weekends when needed?",
    "question_type": "YES_NO",
    "expected_answer": "YES",
    "is_dealbreaker": false
  }'

Update an existing question

Change the wording or make a question a dealbreaker:

curl -X PATCH "https://api.heymilo.network/api/v4/postings/A1B2C3D4/questions/{question_id}" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Do you have at least 3 years of hands-on HVAC experience?",
    "is_dealbreaker": true
  }'

Delete a question

curl -X DELETE "https://api.heymilo.network/api/v4/postings/A1B2C3D4/questions/{question_id}" \
  -H "X-API-KEY: your_api_key_here"

Step 3: Ingest Candidates

Now add candidates to the pipeline. The SMS agent will automatically reach out via text.

Single candidate

curl -X POST "https://api.heymilo.network/api/v4/postings/A1B2C3D4/candidates" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mike Torres",
    "email": "mike.torres@email.com",
    "phone_number": "+15551234567",
    "metadata": {
      "source": "indeed",
      "applied_date": "2026-03-15"
    }
  }'

Response:

{
  "object": "candidate",
  "data": {
    "object": "candidate",
    "interview_id": "D536A69A4090E13F",
    "interview_url": "https://candidates.heymilo.io/coolair/i/D536A69A4090E13F",
    "posting_id": "A1B2C3D4"
  }
}

Save the interview_id — you’ll use it to check results later.

Bulk ingest

For high-volume roles, ingest multiple candidates at once:

curl -X POST "https://api.heymilo.network/api/v4/postings/A1B2C3D4/candidates/bulk" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "name": "Sarah Johnson",
        "email": "sarah.j@email.com",
        "phone_number": "+15559876543",
        "metadata": {"source": "job_fair"}
      },
      {
        "name": "Carlos Rivera",
        "email": "c.rivera@email.com",
        "phone_number": "+15555551234",
        "metadata": {"source": "referral"}
      },
      {
        "name": "James Wilson",
        "email": "j.wilson@email.com",
        "phone_number": "+15558884321",
        "metadata": {"source": "indeed"}
      }
    ]
  }'

Phone numbers are required for SMS workflows. Without a valid phone number, the SMS agent cannot reach the candidate and they will be stuck at the SMS step. Use E.164 format (e.g., +15551234567).

Step 4: See Results

List all candidates for the posting

curl -X GET "https://api.heymilo.network/api/v4/postings/A1B2C3D4/candidates" \
  -H "X-API-KEY: your_api_key_here"

This returns a summary for each candidate with their overall score and workflow progress.

Get full interview data for a candidate

curl -X GET "https://api.heymilo.network/api/v4/interviews/D536A69A4090E13F/data" \
  -H "X-API-KEY: your_api_key_here"

Response (after completion):

{
  "object": "interview_data",
  "data": {
    "object": "interview_data",
    "interview_id": "D536A69A4090E13F",
    "posting_id": "A1B2C3D4",
    "name": "Mike Torres",
    "email": "mike.torres@email.com",
    "score": 78.5,
    "status": "completed",
    "workflow": {
      "steps": [
        {
          "id": "conversational_sms",
          "order": 1,
          "status": "complete",
          "started": true,
          "completed": true
        },
        {
          "id": "web_interview",
          "order": 2,
          "status": "complete",
          "started": true,
          "completed": true
        }
      ],
      "all_complete": true
    },
    "sms": {
      "object": "sms_result",
      "interview_id": "D536A69A4090E13F",
      "is_eligible": true,
      "confidence": 0.92,
      "criteria": [
        {
          "criteria_id": "sms_001",
          "criteria_text": "Do you hold a valid EPA 608 certification?",
          "passed": true,
          "confidence": 0.95,
          "is_dealbreaker": true,
          "reasons": ["Candidate confirmed EPA 608 Universal certification"]
        },
        {
          "criteria_id": "sms_002",
          "criteria_text": "How many years of HVAC experience do you have?",
          "passed": true,
          "confidence": 0.90,
          "is_dealbreaker": true,
          "reasons": ["Candidate stated 7 years of experience, meets minimum of 3"]
        }
      ],
      "transcript": [
        {"role": "agent", "text": "Hi Mike! This is Tyler from CoolAir Solutions..."},
        {"role": "candidate", "text": "Yes I have my EPA 608 Universal cert"}
      ]
    },
    "web_interview": {
      "object": "web_interview_result",
      "interview_id": "D536A69A4090E13F",
      "match_score": 78,
      "highlights": [
        "Strong hands-on experience with residential systems",
        "Good troubleshooting methodology"
      ],
      "lowlights": [
        "Limited commercial experience"
      ],
      "scorecard": [
        {
          "question_id": "q1",
          "question": "Walk me through a typical residential HVAC installation...",
          "evaluation_score": 4,
          "evaluation_summary": "Detailed walkthrough of split system installation including proper refrigerant charging procedures.",
          "score_weight": 3.0
        }
      ],
      "audio_recording_url": "https://cdn.heymilo.io/recordings/abc123.mp3"
    }
  }
}

Set up a webhook for real-time notifications

Instead of polling, get notified when interviews complete:

curl -X POST "https://api.heymilo.network/api/v4/webhooks" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_id": "A1B2C3D4",
    "url": "https://your-ats.com/heymilo-webhook",
    "event_type": "interview_completed"
  }'

Summary

Step	Endpoint	What Happens
Create agent	`POST /v4/postings`	Two-stage pipeline created (SMS + Voice) with your questions
Manage questions	`GET/POST/PATCH/DELETE /v4/postings/{id}/questions`	Edit, add, remove, or reorder questions at any time
Ingest candidate	`POST /v4/postings/{id}/candidates`	Tyler texts the candidate immediately
SMS screen completes	(automatic)	Candidates who pass all dealbreakers advance to voice
Voice interview completes	(automatic)	AI scores each answer 1–5 and generates a scorecard
Get results	`GET /v4/interviews/{id}/data`	Full SMS transcript, voice scorecard, and recordings
Webhook	`POST /v4/webhooks`	Get notified in real-time when stages complete

API Quickstarts

Sms to voice agent

Guide: SMS to Voice Agent (HVAC Technician)

What You’ll Build

Step 1: Create the Agent

Step 2: Manage Questions After Creation

List current questions

Filter by modality

Add a new SMS question

Update an existing question

Delete a question

Step 3: Ingest Candidates

Single candidate

Bulk ingest

Step 4: See Results

List all candidates for the posting

Get full interview data for a candidate

Set up a webhook for real-time notifications

Summary

API Quickstarts

Documentation Index

​Guide: SMS to Voice Agent (HVAC Technician)

​What You’ll Build

​Step 1: Create the Agent

​Step 2: Manage Questions After Creation

​List current questions

​Filter by modality

​Add a new SMS question

​Update an existing question

​Delete a question

​Step 3: Ingest Candidates

​Single candidate

​Bulk ingest

​Step 4: See Results

​List all candidates for the posting

​Get full interview data for a candidate

​Set up a webhook for real-time notifications

​Summary

Guide: SMS to Voice Agent (HVAC Technician)

What You’ll Build

Step 1: Create the Agent

Step 2: Manage Questions After Creation

List current questions

Filter by modality

Add a new SMS question

Update an existing question

Delete a question

Step 3: Ingest Candidates

Single candidate

Bulk ingest

Step 4: See Results

List all candidates for the posting

Get full interview data for a candidate

Set up a webhook for real-time notifications

Summary