--- title: "Update an interviewer" method: PATCH path: "/api/v2/postings/{posting_id}" tags: ["Interviewers"] --- # Update an interviewer `PATCH /api/v2/postings/{posting_id}` Update fields on an existing interviewer. Only provided fields are modified; omitted fields remain unchanged. ## Path parameters - `posting_id` string, required ## Headers - `X-API-KEY` string, nullable - `Authorization` string, nullable - `X-Workspace-Id` string, nullable ## Request body - UpdatePostingRequest — Request body for updating a posting. All fields are optional. - `title` string, nullable — Updated job title. - `description` string, nullable — Updated job description. - `name` string, nullable — Updated URL slug. - `language` string, nullable — Updated default language (BCP-47). - `interviewer_name` string, nullable — Updated AI interviewer display name. - `instructions` string, nullable — Updated global instructions for the AI interviewer. - `company_overview` string, nullable — Updated company overview. - `job_overview` string, nullable — Updated job overview. - `interview_process_overview` string, nullable — Updated process overview shared with agents. - `company_overview_delivery_mode` 'exact_delivery' | 'summarized_delivery' | 'reference_only' | 'silent_reference', nullable — Updated company overview delivery mode. - `job_overview_delivery_mode` 'exact_delivery' | 'summarized_delivery' | 'reference_only' | 'silent_reference', nullable — Updated job overview delivery mode. - `interview_process_overview_delivery_mode` 'exact_delivery' | 'summarized_delivery' | 'reference_only' | 'silent_reference', nullable — Updated interview process overview delivery mode. - `phone_number_id` string, nullable — Updated phone number ID. - `sender_email_id` string, nullable — Updated sender email ID. - `email_template_group_id` string, nullable — Updated email template group ID. - `design_template_group_id` string, nullable — Updated design template group ID. - `redirect_url` string, nullable — Updated post-completion redirect URL. - `scheduling_url` string, nullable — Updated scheduling URL for shortlisted candidates. - `deadline` string, nullable — Updated ISO 8601 deadline. - `allow_sms_comms` boolean, nullable — Updated SMS communications flag. - `max_retakes` integer, nullable — Updated max retake attempts (0-5). - `retake_cooldown_days` number, nullable — Updated retake cooldown in days. - `email_report_to_candidate` boolean, nullable — Updated email report flag. - `metadata` object, nullable — Updated key-value metadata. Replaces existing metadata entirely. Up to 50 keys, each key max 40 chars, each value max 500 chars. ## 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)