> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heymilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sms to voice agent

# 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:

1. **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.
2. **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.

```bash theme={null}
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:**

```json theme={null}
{
  "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.

<Note>
  **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.
</Note>

***

## 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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```bash theme={null}
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"}
      }
    ]
  }'
```

<Warning>
  **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`).
</Warning>

***

## Step 4: See Results

### List all candidates for the posting

```bash theme={null}
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

```bash theme={null}
curl -X GET "https://api.heymilo.network/api/v4/interviews/D536A69A4090E13F/data" \
  -H "X-API-KEY: your_api_key_here"
```

**Response (after completion):**

```json theme={null}
{
  "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:

```bash theme={null}
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               |