HEheymilo
Candidates

List candidates for an interviewer

Changed on

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

To sync only what changed, pass updated_after, then pass each response's pagination.next_cursor as cursor until it is null. Results then come oldest change first, and total_count is null.

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

Request

  • Base URL
    https://api.heymilo.ai
  • URL
    https://api.heymilo.ai/api/v2/postings/{posting_id}/candidates
  • Auth
    API key in header X-API-KEY

Path parameters

posting_idstring required

Query parameters

limitinteger

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.

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
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
updated_afterstring nullable

Only return candidates whose interview data changed at or after this time (inclusive), oldest change first. Accepts an ISO-8601 datetime or Unix epoch seconds matching the updated_at field. Follow pagination.next_cursor with cursor for further pages. Cannot be combined with cursor or starting_after.

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

The pagination.next_cursor from the previous response, passed unchanged, to continue an updated_after sync. Cannot be combined with updated_after or starting_after.

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,
      "updated_at": 1739714569.48
    }
  ]
}

Changes

  • 012c345aec46Revision changes
    • info

      added the new optional query request parameter cursor

    • info

      added the new optional query request parameter updated_after

    • info

      added the optional property // to the response with the status

    • info

      added the optional property / to the response with the status