Skip to main content

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.

​
Guide: Resume to Video Agent (Software Engineer)

Use case: Technical hiring where you want AI to pre-screen resumes against specific skill requirements before inviting qualified candidates to a video interview. Ideal for engineering roles where resume quality varies widely and recruiter time is expensive.

​
What You’ll Build

A two-stage hiring pipeline:
  1. Resume Screening — AI analyzes each candidate’s resume against eligibility criteria (must-haves) and scoring criteria (nice-to-haves). Candidates who fail any eligibility criterion are automatically disqualified.
  2. Video Interview — Qualified candidates are invited to a video interview where the AI asks technical and behavioral questions, scores responses, and generates a detailed scorecard.

​
Step 1: Create the Agent

Create a posting with a two-step workflow: resume screening first, then a video 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": "Senior Software Engineer - Backend",
    "description": "We are hiring a Senior Software Engineer to build and scale backend services. Requirements: 5+ years of professional software engineering experience, strong proficiency in Python or Go, experience with distributed systems and cloud infrastructure (AWS/GCP), and a BS in Computer Science or equivalent. Nice to have: experience with Kubernetes, event-driven architectures, and leading technical projects.",
    "interviewer_name": "Alex",
    "language": "en",
    "company_overview": "DataForge is a Series B data infrastructure startup processing 50B+ events per day for enterprise customers.",
    "job_overview": "Design, build, and operate backend services that power our real-time data pipeline. You will own services end-to-end from architecture through deployment and monitoring.",
    "workflow": [
      {
        "type": "resume",
        "config": {},
        "questions": [
          {
            "modality": "resume_eligibility",
            "text": "5+ years of professional software engineering experience"
          },
          {
            "modality": "resume_eligibility",
            "text": "Proficiency in Python or Go"
          },
          {
            "modality": "resume_eligibility",
            "text": "Experience with cloud infrastructure (AWS, GCP, or Azure)"
          },
          {
            "modality": "resume_eligibility",
            "text": "Bachelor's degree in Computer Science or equivalent practical experience"
          },
          {
            "modality": "resume_scoring",
            "text": "Experience with distributed systems and microservices architecture",
            "weight": 3.0
          },
          {
            "modality": "resume_scoring",
            "text": "Experience with Kubernetes and container orchestration",
            "weight": 2.0
          },
          {
            "modality": "resume_scoring",
            "text": "Track record of leading technical projects or mentoring engineers",
            "weight": 2.0
          },
          {
            "modality": "resume_scoring",
            "text": "Experience with event-driven architectures or real-time data processing",
            "weight": 3.0
          }
        ]
      },
      {
        "type": "web_interview",
        "config": {
          "video": true,
          "num_questions": 5
        },
        "questions": [
          {
            "modality": "voice",
            "text": "Tell me about a backend system you designed from scratch. What were the key architectural decisions you made and why?",
            "evaluation_criteria": "Assess system design thinking, tradeoff analysis, and ability to articulate technical decisions. Look for discussion of scalability, reliability, and maintainability.",
            "score_of_1": "Cannot describe a system they designed or gives vague, surface-level answers.",
            "score_of_5": "Describes a well-thought-out architecture with clear reasoning for technology choices, tradeoff analysis, and measurable outcomes.",
            "question_type": "open-ended",
            "score_weight": 3.0,
            "min_follow_ups": 1,
            "max_follow_ups": 2
          },
          {
            "modality": "voice",
            "text": "Describe a production incident you were involved in. How did you diagnose and resolve it? What did you change to prevent it from happening again?",
            "evaluation_criteria": "Evaluate debugging methodology, incident response skills, and ability to implement preventive measures.",
            "score_of_1": "No specific example or shows poor debugging approach.",
            "score_of_5": "Describes a systematic debugging process, clear communication during the incident, and concrete preventive measures implemented afterward.",
            "question_type": "open-ended",
            "score_weight": 2.5,
            "min_follow_ups": 1,
            "max_follow_ups": 2
          },
          {
            "modality": "voice",
            "text": "How do you approach testing in your projects? Walk me through your testing strategy for a new backend service.",
            "evaluation_criteria": "Assess testing philosophy and practical experience with different testing levels (unit, integration, e2e, load).",
            "score_of_1": "Minimal testing awareness or only mentions unit tests.",
            "score_of_5": "Describes a comprehensive testing pyramid including unit, integration, contract, and load testing with specific tooling examples.",
            "question_type": "open-ended",
            "score_weight": 2.0,
            "min_follow_ups": 1,
            "max_follow_ups": 1
          },
          {
            "modality": "voice",
            "text": "Tell me about a time you had to optimize a system for performance. What was the bottleneck and how did you address it?",
            "evaluation_criteria": "Evaluate profiling and optimization skills. Look for data-driven approach to identifying bottlenecks and measuring improvements.",
            "score_of_1": "No specific example or optimization was done without measurement.",
            "score_of_5": "Shows rigorous profiling, identifies root cause with data, implements a targeted fix, and measures the improvement quantitatively.",
            "question_type": "open-ended",
            "score_weight": 2.5,
            "min_follow_ups": 1,
            "max_follow_ups": 2
          },
          {
            "modality": "voice",
            "text": "How do you approach working with cross-functional teams — product, data science, DevOps? Give me an example of a project that required heavy collaboration.",
            "evaluation_criteria": "Assess collaboration and communication skills in a technical context. Look for specific examples of working across team boundaries.",
            "score_of_1": "Works in isolation, poor communication about technical tradeoffs.",
            "score_of_5": "Proactively communicates, translates technical concepts for non-technical stakeholders, and drives alignment across teams.",
            "question_type": "open-ended",
            "score_weight": 2.0,
            "min_follow_ups": 0,
            "max_follow_ups": 1
          }
        ]
      }
    ]
  }'
Response: 
{
  "object": "posting",
  "data": {
    "object": "posting",
    "id": "C7D8E9F0",
    "status": "active",
    "urls": {
      "candidate_url": "https://candidates.heymilo.io/dataforge/senior-software-engineer",
      "ingestion_url_key": "pR3sT5uV7wX9yZ1aB3cD5eF7gH9iJ1kL3mN5oP",
      "review_url": "https://admin.heymilo.ai/w/WORKSPACE_ID/lab2/C7D8E9F0/1-details"
    },
    "created_at": 1739612400.0,
    "posting": { ... }
  }
}
How resume screening works: When a candidate is ingested, the AI immediately analyzes their resume against your criteria. Eligibility criteria are pass/fail — if a candidate fails any one, they are automatically disqualified and won’t receive a video interview invitation. Scoring criteria produce a weighted score (1.0–5.0) that helps you rank qualified candidates.

​
Step 2: Manage Criteria After Creation

​
List all resume criteria

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

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

​
Add a new eligibility criterion

Realized you also need candidates to be US-authorized: 
curl -X POST "https://api.heymilo.network/api/v4/postings/C7D8E9F0/questions" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "modality": "resume_eligibility",
    "text": "Must be authorized to work in the United States"
  }'

​
Update a scoring criterion’s weight

Make the distributed systems criterion more important: 
curl -X PATCH "https://api.heymilo.network/api/v4/postings/C7D8E9F0/questions/{question_id}" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "weight": 4.0
  }'

​
Delete a criterion that is no longer relevant

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

​
Step 3: Ingest Candidates

For resume screening, you need to provide the candidate’s resume. The candidate will upload their resume when they visit the interview URL, or you can attach it as metadata.

​
Single candidate

curl -X POST "https://api.heymilo.network/api/v4/postings/C7D8E9F0/candidates" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jamie Chen",
    "email": "jamie.chen@email.com",
    "phone_number": "+14155551234",
    "metadata": {
      "source": "greenhouse",
      "recruiter_notes": "Strong referral from CTO",
      "linkedin": "https://linkedin.com/in/jamiechen"
    }
  }'
Response: 
{
  "object": "candidate",
  "data": {
    "object": "candidate",
    "interview_id": "F1A2B3C4D5E6F7A8",
    "interview_url": "https://candidates.heymilo.io/dataforge/i/F1A2B3C4D5E6F7A8",
    "posting_id": "C7D8E9F0"
  }
}
When Jamie visits the interview_url, they’ll be prompted to upload their resume. The AI screens it immediately, and if they pass all eligibility criteria, they proceed directly to the video interview.

​
Bulk ingest from a job board export

curl -X POST "https://api.heymilo.network/api/v4/postings/C7D8E9F0/candidates/bulk" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"name": "Sam Rivera", "email": "s.rivera@email.com", "metadata": {"source": "lever"}},
      {"name": "Morgan Park", "email": "m.park@email.com", "metadata": {"source": "linkedin_easy_apply"}},
      {"name": "Casey Wu", "email": "c.wu@email.com", "metadata": {"source": "referral"}}
    ]
  }'

​
Step 4: See Results

​
List candidates with resume scores

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

​
Get full results for a candidate

curl -X GET "https://api.heymilo.network/api/v4/interviews/F1A2B3C4D5E6F7A8/data" \
  -H "X-API-KEY: your_api_key_here"
Response (after both stages complete): 
{
  "object": "interview_data",
  "data": {
    "object": "interview_data",
    "interview_id": "F1A2B3C4D5E6F7A8",
    "posting_id": "C7D8E9F0",
    "name": "Jamie Chen",
    "email": "jamie.chen@email.com",
    "score": 85.0,
    "status": "completed",
    "workflow": {
      "steps": [
        {"id": "resume", "order": 1, "status": "complete", "started": true, "completed": true},
        {"id": "web_interview", "order": 2, "status": "complete", "started": true, "completed": true}
      ],
      "all_complete": true
    },
    "resume": {
      "object": "resume_result",
      "interview_id": "F1A2B3C4D5E6F7A8",
      "overall_score": 4.2,
      "is_eligible": true,
      "eligibility_criteria": [
        {
          "criteria_id": "rec_001",
          "criteria_text": "5+ years of professional software engineering experience",
          "passed": true,
          "confidence": 0.95,
          "reasons": ["Resume shows 7 years of SWE experience at two companies"]
        },
        {
          "criteria_id": "rec_002",
          "criteria_text": "Proficiency in Python or Go",
          "passed": true,
          "confidence": 0.98,
          "reasons": ["Listed Python as primary language, multiple Python projects described"]
        },
        {
          "criteria_id": "rec_003",
          "criteria_text": "Experience with cloud infrastructure (AWS, GCP, or Azure)",
          "passed": true,
          "confidence": 0.92,
          "reasons": ["AWS experience mentioned: EC2, S3, Lambda, ECS"]
        },
        {
          "criteria_id": "rec_004",
          "criteria_text": "Bachelor's degree in Computer Science or equivalent",
          "passed": true,
          "confidence": 0.99,
          "reasons": ["BS Computer Science from UC Berkeley"]
        }
      ],
      "score_criteria": [
        {
          "criteria_id": "rsc_001",
          "criteria_text": "Experience with distributed systems and microservices architecture",
          "score": 4.5,
          "confidence": 0.88,
          "reasons": ["Led migration from monolith to microservices, designed event-driven data pipeline processing 10B events/day"]
        },
        {
          "criteria_id": "rsc_002",
          "criteria_text": "Experience with Kubernetes and container orchestration",
          "score": 3.8,
          "confidence": 0.82,
          "reasons": ["Kubernetes mentioned in skills section but no detailed project description"]
        },
        {
          "criteria_id": "rsc_003",
          "criteria_text": "Track record of leading technical projects or mentoring engineers",
          "score": 4.0,
          "confidence": 0.85,
          "reasons": ["Led team of 4 engineers on data pipeline project, mentored 2 junior engineers"]
        },
        {
          "criteria_id": "rsc_004",
          "criteria_text": "Experience with event-driven architectures or real-time data processing",
          "score": 4.8,
          "confidence": 0.93,
          "reasons": ["Built real-time event pipeline using Kafka processing 10B events/day at previous company"]
        }
      ],
      "resume_url": "https://cdn.heymilo.io/resumes/F1A2B3C4.pdf"
    },
    "web_interview": {
      "object": "web_interview_result",
      "interview_id": "F1A2B3C4D5E6F7A8",
      "match_score": 85,
      "highlights": [
        "Deep distributed systems experience with quantifiable scale",
        "Strong system design thinking with clear tradeoff analysis",
        "Excellent incident response methodology"
      ],
      "lowlights": [
        "Testing strategy focused heavily on unit tests, less experience with contract testing"
      ],
      "speech_score": 82.0,
      "scorecard": [
        {
          "question_id": "q1",
          "question": "Tell me about a backend system you designed from scratch...",
          "evaluation_score": 5,
          "evaluation_summary": "Described designing a real-time event ingestion system. Excellent discussion of tradeoffs between consistency and availability, choice of Kafka over SQS with clear reasoning, and quantified 99.99% uptime.",
          "score_weight": 3.0,
          "rank": 1
        },
        {
          "question_id": "q2",
          "question": "Describe a production incident you were involved in...",
          "evaluation_score": 4,
          "evaluation_summary": "Detailed account of a cascading failure in a microservices mesh. Good use of distributed tracing to identify root cause. Implemented circuit breakers and improved alerting afterward.",
          "score_weight": 2.5,
          "rank": 2
        }
      ],
      "video_recording_url": "https://cdn.heymilo.io/recordings/F1A2B3C4.mp4",
      "audio_recording_url": "https://cdn.heymilo.io/recordings/F1A2B3C4.mp3",
      "tags": ["systems-thinker", "data-engineering", "strong-communicator"]
    }
  }
}

​
Understanding the two-stage results

SectionWhat It Tells You
resume.is_eligibleDid the candidate pass all must-have criteria?
resume.eligibility_criteria[]Pass/fail result for each requirement, with AI reasoning
resume.score_criteria[]Weighted score (1.0–5.0) for each nice-to-have, with reasoning
resume.overall_scoreAggregate resume score across all scoring criteria
web_interview.match_scoreOverall interview performance (0–100)
web_interview.scorecard[]Per-question breakdown with AI evaluation
scoreCombined final score across both stages
If a candidate fails resume screening, they will not be invited to the video interview. The web_interview section will be null, and the workflow status will show the resume step as complete but the interview step as not started.

​
Summary

StepEndpointWhat Happens
Create agentPOST /v4/postingsTwo-stage pipeline: resume screen + video interview
Manage criteriaGET/POST/PATCH/DELETE /v4/postings/{id}/questionsEdit eligibility and scoring criteria at any time
Ingest candidatePOST /v4/postings/{id}/candidatesCandidate visits link, uploads resume
Resume screen(automatic)AI evaluates resume against your criteria
Video interview(automatic, if eligible)Alex interviews the candidate on video
Get resultsGET /v4/interviews/{id}/dataResume analysis + video scorecard + recordings