Sign in

v1

latestOpenAPI 3.1.02026-08-0456127224.3 KB
Candidates

List candidates for an interviewer

Retrieve a paginated list of candidates for a specific interviewer. Each candidate includes workflow progress, scores, and agent summaries.

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

Path parameters

posting_idstring required

Query parameters

limitinteger

Maximum number of candidates to return (1–100).

Maximum number of candidates to return (1–100).

starting_afterstring nullable

Cursor for pagination. Pass the interview_id of the last candidate from the previous page.

Cursor for pagination. Pass the interview_id of the last candidate from the previous page.

created_afterstring nullable

Only return candidates invited to this interviewer at or after this bound (inclusive). Accepts an ISO-8601 datetime such as 2026-03-13T00:00:00Z or 2026-03-13T00:00:00+00:00, or Unix epoch seconds matching the created_at field in the response. Naive ISO values (no offset) are interpreted as UTC. Combine with created_before to query a closed interval.

Example:2026-03-13T00:00:00Z

Only return candidates invited to this interviewer at or after this bound (inclusive). Accepts an ISO-8601 datetime such as 2026-03-13T00:00:00Z or 2026-03-13T00:00:00+00:00, or Unix epoch seconds matching the created_at field in the response. Naive ISO values (no offset) are interpreted as UTC. Combine with created_before to query a closed interval.

created_beforestring nullable

Only return candidates invited to this interviewer at or before this bound (inclusive). Accepts an ISO-8601 datetime such as 2026-03-14T23:59:59Z, or Unix epoch seconds matching the created_at field in the response. Naive ISO values (no offset) are interpreted as UTC.

Example:2026-03-14T23:59:59Z

Only return candidates invited to this interviewer at or before this bound (inclusive). Accepts an ISO-8601 datetime such as 2026-03-14T23:59:59Z, or Unix epoch seconds matching the created_at field in the response. Naive ISO values (no offset) are interpreted as UTC.

Headers

X-API-KEYstring nullable
Authorizationstring nullable
X-Workspace-Idstring nullable

Response

Successful Response

Example response

{
  "data": [
    {
      "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
    }
  ]
}