---
title: "Activate an interviewer"
method: POST
path: "/api/v2/postings/{posting_id}/activate"
tags: ["Interviewers"]
---

# Activate an interviewer

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

Activate an interviewer so it begins accepting candidates. The interviewer must have a valid workflow configuration.

For ATS-derived postings still in the `pending_activation` intermediate stage (created via `createPosting` with an ATS-derived `interview_template_id`, or `clonePosting` of an ATS-derived posting), this call finalizes the posting **and** attaches the ATS mapping so candidate ingestion from the ATS begins. The two steps run in one call; the ATS attach is idempotent and best-effort, so re-calling activate is safe and a transient ATS integrator hiccup will not block finalize.

## Path parameters

- `posting_id` string, required

## Headers

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

## Response `200`

Successful Response

- SingleResponsePostingResponse
  - `data` PostingResponse, required — A job posting with its full agentic workflow configuration. A posting represents a complete hiring pipeline — it defines the job, the AI agents involved, and how candidates progress through each screening step.
    - `object` 'posting' — Object type identifier.
    - `id` string, required — Unique posting identifier.
    - `company_id` string, required — ID of the company that owns this posting.
    - `title` string, required — Job title displayed to candidates.
    - `name` string, nullable — URL-friendly slug for the posting.
    - `description` string, required — Full job description text.
    - `language` string, nullable — BCP-47 language code.
    - `interviewer_name` string, nullable — Display name of the AI interviewer.
    - `status` string, required — Posting status: 'draft', 'active', 'expired', 'archived'.
    - `finalized` boolean, required — Whether the posting has been finalized/activated.
    - `archived` boolean, required — Whether the posting is archived.
    - `test_posting` boolean, required — Whether this is a test posting.
    - `workflow` WorkflowStep[] — Ordered list of agentic workflow steps.
      - `id` string, nullable — Unique identifier for this workflow step.
      - `type` string, required — Agent type: 'web_interview', 'conversational_sms', 'resume', 'form'.
      - `order` integer, required — Position in the workflow pipeline (1-based).
      - `config` object — Agent-specific configuration. Shape varies by type. See GET /api/v2/schemas/agents for details.
    - `urls` PostingURLs — All URLs associated with a posting.
      - `candidate_url` string, nullable — Candidate-facing interview URL.
      - `ingestion_url_key` string, nullable — URL key for candidate ingestion. Use with POST /intake/v1/candidate/{key}.
      - `review_url` string, nullable — Admin dashboard review URL.
    - `deadline` number, nullable — Unix timestamp deadline for the posting.
    - `redirect_url` string, nullable — URL candidates are redirected to after completing the interview.
    - `scheduling_url` string, nullable — Calendar scheduling URL for shortlisted candidates.
    - `max_retakes` integer, nullable — Maximum number of interview retakes allowed.
    - `allow_sms_comms` boolean, nullable — Whether SMS communications are enabled.
    - `instructions` string, nullable — General instructions for the AI interviewer shared with agents.
    - `company_overview` string, nullable — Overview of the company shared with agents.
    - `job_overview` string, nullable — Overview of the job/role shared with agents.
    - `interview_process_overview` string, nullable — Overview of the interview process shared with agents.
    - `company_overview_delivery_mode` string, nullable — How the AI interviewer delivers the company overview.
    - `job_overview_delivery_mode` string, nullable — How the AI interviewer delivers the job overview.
    - `interview_process_overview_delivery_mode` string, nullable — How the AI interviewer delivers the interview process overview.
    - `phone_number_id` string, nullable — ID of the phone number used for outbound calls.
    - `sender_email_id` string, nullable — ID of the sender email configuration.
    - `email_template_group_id` string, nullable — ID of the email template group.
    - `design_template_group_id` string, nullable — ID of the design template group.
    - `retake_cooldown_days` number, nullable — Cooldown period in days before a candidate can retake.
    - `email_report_to_candidate` boolean, nullable — Whether to email the interview report to the candidate.
    - `ats_metadata` object, nullable — ATS integration metadata for postings derived from an ATS (Import-from-ATS flow or `createPosting` with an ATS-derived `interview_template_id`). Null for postings not connected to an ATS. Common fields: - `source` (string): how the posting was created, e.g. `job_sync`. - `ats_name` (string): identifier of the ATS, e.g. `workable`, `bullhorn`. - `ats_job_id` (string): ID of the ATS job that backs this posting. - `ats_job_posting_id` (string, optional): ATS-side job-posting ID when distinct from `ats_job_id`. - `integration_id` (string, optional): heymilo ATS integration ID. - `job_ids` (string[], optional): ATS job IDs included in the mapping config. - `pending_activation` (bool): `true` while the agent is in the intermediate stage created by `createPosting` / `clonePosting` for ATS-derived postings. Candidate ingestion does not begin until the caller transitions out of this stage by calling `POST /postings/{posting_id}/activate`, which finalizes the posting and attaches the ATS mapping in one step. - `mapping_activated_at`, `mapping_activated_by` (read-only): audit fields stamped when the ATS mapping was attached. - `mapping_deactivated_at`, `mapping_deactivated_by` (read-only): audit fields stamped when the ATS mapping was last paused.
    - `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.
    - `team_ids` string[], nullable — Team IDs this interviewer is assigned to. Null when Teams is not enabled for the workspace. An empty array means Teams is enabled but the interviewer is not assigned to any team — it is then visible to the whole workspace.
    - `created_at` number, nullable — Unix timestamp when the posting was created.
    - `updated_at` number, nullable — Unix timestamp when the posting was last updated.
  - `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/5e07b657706b/schema)