v1

latestOpenAPI 3.1.02026-08-0456127224.3 KB

Candidates

Ingest a single candidate

Submit a candidate for processing through the interviewer's workflow. Returns the interview ID, interview URL, and full candidate receipt.

post/api/v2/postings/{posting_id}/candidates

Path parameters

posting_idstring required

Headers

X-API-KEYstring nullable

Authorizationstring nullable

X-Workspace-Idstring nullable

Request body

namestring required

Candidate full name

emailstring required

Candidate email address

phone_numberstring nullable

Candidate phone number (E.164 format)

metadataobject nullable

Set of key-value pairs for storing additional information on the candidate. Up to 50 keys, each key max 40 chars, each value max 500 chars.

dataobject nullable

Additional candidate data

Example request

{
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "phone_number": "+12065551234",
  "metadata": {
    "ats_stage": "phone_screen",
    "external_id": "candidate_xyz"
  }
}

Response

Successful Response

metaobject nullable

Optional metadata. Shape varies by endpoint.

Example response

{
  "data": {
    "interview_id": "D536A69A4090E13F",
    "interview_url": "https://candidates.heymilo.io/acme/i/D536A69A4090E13F",
    "posting_id": "13D77095",
    "candidate": {
      "interview_id": "D536A69A4090E13F",
      "candidate_id": "cand_def456",
      "posting_id": "13D77095",
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "score": 78.5,
      "status": "completed",
      "interview_url": "https://candidates.heymilo.io/acme/i/D536A69A4090E13F",
      "workflow": {
        "steps": [
          {
            "step_id": "agent_vi_001",
            "order": 1,
            "status": "completed",
            "started": true,
            "completed": true,
            "last_updated_at": 1739713800
          }
        ],
        "last_activity_at": 1739715600
      },
      "agent_summary": {
        "resume": {
          "resume_score": 3.8,
          "resume_link": "https://cdn.heymilo.io/resumes/abc123.pdf"
        },
        "web_interview": {
          "score": 82
        },
        "sms": {
          "messages_sent": 8
        },
        "form": {
          "questions_answered": 5,
          "total_questions": 7
        }
      },
      "metadata": {
        "ats_stage": "phone_screen",
        "external_id": "candidate_xyz"
      },
      "interviewed_at": 1739713800,
      "created_at": 1739612400
    }
  }
}