---
title: "Ingest a single candidate"
method: POST
path: "/api/v2/postings/{posting_id}/candidates"
tags: ["Candidates"]
---

# Ingest a single candidate

`POST /api/v2/postings/{posting_id}/candidates`

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

## Path parameters

- `posting_id` string, required

## Headers

- `X-API-KEY` string, nullable
- `Authorization` string, nullable
- `X-Workspace-Id` string, nullable

## Request body

- CandidateIngestRequest
  - `name` string, required — Candidate full name
  - `email` string, required — Candidate email address
  - `phone_number` string, nullable — Candidate phone number (E.164 format)
  - `metadata` object, 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.
  - `data` object, nullable — Additional candidate data

## Response `201`

Successful Response

- SingleResponseIngestCandidateResponse
  - `data` IngestCandidateResponse, required — Response after successfully ingesting a candidate.
    - `object` 'candidate' — Object type identifier.
    - `interview_id` string, required — Unique interview identifier for this candidate-posting pair.
    - `interview_url` string, required — URL the candidate uses to access the interview.
    - `posting_id` string, required — ID of the posting this candidate was ingested into.
    - `candidate` CandidateResponse — A candidate within a posting's pipeline. Each candidate has a unique ``interview_id`` (one per candidate-posting pair) and a ``candidate_id`` (shared across postings within a workspace).
      - `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.
  - `meta` object, nullable — Optional metadata. Shape varies by endpoint.

## Other responses

- `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/a93ca9c2c777/schema)