--- title: "List candidates for an interviewer" method: GET path: "/api/v2/postings/{posting_id}/candidates" tags: ["Candidates"] --- # List candidates for an interviewer `GET /api/v2/postings/{posting_id}/candidates` Retrieve a paginated list of candidates for a specific interviewer. Each candidate includes workflow progress, scores, and agent summaries. ## Path parameters - `posting_id` string, required ## Query parameters - `limit` integer — Maximum number of candidates to return (1–100). - `starting_after` string, nullable — Cursor for pagination. Pass the `interview_id` of the last candidate from the previous page. - `created_after` string, 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. - `created_before` string, 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. ## Headers - `X-API-KEY` string, nullable - `Authorization` string, nullable - `X-Workspace-Id` string, nullable ## Response `200` Successful Response - ListResponseCandidateResponse - `data` CandidateResponse[], required - `object` 'candidate' — Object type identifier. - `interview_id` string, required — Unique interview identifier (one per candidate-posting pair). - `candidate_id` string, nullable — Unique candidate identifier (shared across postings within a workspace). - `posting_id` string, required — ID of the posting this candidate belongs to. - `name` string, required — Candidate's full name. - `email` string, required — Candidate's email address. - `score` number, nullable — Overall match score (0-100). Aggregated across all completed workflow steps. - `status` string, required — Current candidate status: 'pending', 'in_progress', 'evaluating', 'completed', 'shortlisted', 'dismissed', 'knocked_out'. 'evaluating' means all workflow steps are done but the final score is still being computed. - `interview_url` string, nullable — URL the candidate uses to access the interview. - `workflow` CandidateWorkflow — Overall workflow progress for a candidate. - `steps` WorkflowStepStatus[], required — Ordered list of workflow step statuses. - `step_id` string, required — Workflow step identifier. - `order` integer, required — Position in the workflow (1-based). - `status` string, required — Step status: 'not_started', 'in_progress', 'completed', 'knocked_out'. - `started` boolean, required — Whether the candidate has started this step. - `completed` boolean, required — Whether the candidate has completed this step. - `knocked_out` boolean — Whether the candidate was disqualified at this step. - `last_updated_at` number, nullable — Unix timestamp of the last status change. - `all_complete` boolean, required — True when every step has been completed. - `last_activity_at` number, nullable — Unix timestamp of the candidate's most recent interaction with any step. - `agent_summary` AgentSummary — Per-agent-type summary metrics for a candidate. - `resume` AgentResumeSummary — Resume screening summary metrics. - `resume_score` number, nullable — Resume match score. - `is_eligible` boolean, nullable — Whether the candidate meets eligibility criteria. - `resume_link` string, nullable — URL to the uploaded resume. - `web_interview` AgentWebInterviewSummary — Web interview summary metrics. - `score` number, nullable — Overall interview score. - `highlights` string[] — Candidate strengths identified by AI. - `audio_recording_link` string, nullable — Signed URL to audio recording. - `video_recording_link` string, nullable — Signed URL to video recording. - `sms` AgentSMSSummary — SMS screening summary metrics. - `is_eligible` boolean, nullable — Whether the candidate passed SMS screening. - `criteria_passed` string[] — Criteria the candidate passed. - `criteria_failed` string[] — Criteria the candidate failed. - `messages_sent` integer, nullable — Total messages sent by the agent. - `form` AgentFormSummary — Form screening summary metrics. - `is_complete` boolean, nullable — Whether the candidate completed the form. - `is_eligible` boolean, nullable — Whether the candidate passed all knockout questions. - `questions_answered` integer, nullable — Number of questions answered. - `total_questions` integer, nullable — Total number of questions on the form. - `shortlisted` boolean — Whether a recruiter has shortlisted this candidate. - `dismissed` boolean — Whether a recruiter has dismissed this candidate. - `metadata` object, nullable — Set of key-value pairs for storing additional information. Up to 50 keys, each key max 40 chars, each value max 500 chars. - `data` object, nullable — Additional candidate data supplied at ingestion time. - `interviewed_at` number, nullable — Unix timestamp when the candidate completed the interview. - `created_at` number, nullable — Unix timestamp when the candidate was ingested. - `pagination` PaginationMeta, required - `has_more` boolean, required — Whether more results exist beyond this page - `total_count` integer, nullable — Total number of results (if available) - `url` string, nullable — URL of this resource ## Other responses - `400` — Invalid date range (e.g. `created_before` < `created_after`). - `401` — Invalid or missing API key. - `404` — Resource not found. - `422` — Validation Error - `429` — Rate limit exceeded. --- [API](https://skmtc.net/heymilo/apis/heymilo-public-api.md) · [All operations](https://skmtc.net/heymilo/apis/heymilo-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heymilo/heymilo-public-api/revisions/5e07b657706b/schema)