> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hirempire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Changelog

> History of changes, additions, and deprecations to the Hirempire API

Stay up to date with every change to the Hirempire API. Breaking changes are marked clearly.

<Update label="June 2026" description="Expanded response fields, partial updates, job source URL endpoints" tags={["New"]}>
  Two follow-up additions on top of the breaking-changes release earlier this month.

  ### New: Job source URL endpoints

  | Method | Path                      | Description                                                     |
  | ------ | ------------------------- | --------------------------------------------------------------- |
  | `GET`  | `/v1/job-sources?job_id=` | List source links for a job                                     |
  | `POST` | `/v1/create-source`       | Create a new source link (idempotent on `job_id`+`source_name`) |

  Each source object includes:

  ```json theme={null}
  {
    "id": "uuid",
    "source_name": "LinkedIn",
    "source_url": "https://jobs.hirempire.com/{company-slug}/{source-id}",
    "code": "a3f9",
    "visits": 142,
    "created_at": "2026-06-18T10:00:00.000Z"
  }
  ```

  `source_url` is the publicly shareable link for that source. Visits to that URL increment the `visits` counter — useful for attribution.

  ### Expanded response fields

  Many fields were previously available in the database but not exposed. They are now included in responses without changing existing field names.

  **Jobs** (`GET /v1/jobs`, `GET /v1/get-job`) now include: `public_slug`, `company_logo_url`, `department`, `industry`, `career_level`, full salary breakdown (`salary_type`, `salary_min`, `salary_max`, `salary_fixed`), and a `sources` object with each source's tracking URL. `GET /v1/get-job` additionally includes `questions` (the application form configuration: built-in `fields` toggles plus `custom` per-job questions).

  **Candidates** (`GET /v1/candidates`, `GET /v1/get-candidate`, `GET /v1/job-candidates`) now include: `github_url`, `cover_letter`, `languages`, `custom_answers` (answers to the job's `questions`), `tags`, `pool_stage`, `location_country`, and the full AI screening breakdown (`ai_skills_match`, `ai_experience_match`, `ai_location_match`, plus `linkedin_matching`). The single-candidate endpoint additionally returns `linkedin_data`, `github_data`, and `github_evaluation`.

  **Webhooks** (`GET /v1/webhooks`) now include `updated_at` alongside `created_at`.

  ### Partial updates: PATCH endpoints accept more fields

  **`PATCH /v1/update-job`** now accepts any subset of: `job_title`, `job_description`, `department`, `industry`, `job_country`, `city`, `workplace`, `job_type`, `career_level`, `salary`, `currency`, `salary_period`, `hide_salary`, `questions`, `status`. Only the fields you send are updated. Status casing rules (`Pending`→`draft`, `Hired`→`closed`) are unchanged.

  **`PATCH /v1/update-candidate`** now accepts: `status`, `tags`, `pool_stage` (`cold`/`warm`/`hot`/`not_interested`), `note_to_candidate`.

  **`POST /v1/add-job`** now accepts two new optional body fields: `industry` and `questions`. `public_slug` is also optional — auto-generated from the title if not provided.
</Update>

<Update label="June 2026" description="Applicants renamed to Candidates, status enums, webhook paths, scopes removed" tags={["Breaking"]}>
  A workspace-wide breaking-changes release. **All clients integrating against the Applicants endpoints, scoped tokens, or capitalized status values need to update.**

  ### Applicants renamed to Candidates

  The applications table now stores three candidate sub-types — `applicant`, `prospect`, and `upload` — so the public API has been renamed from "applicants" to "candidates" to reflect this. Every candidate object now includes a `type` field, and `GET /v1/candidates` accepts an optional `?type=` filter.

  | Old path                              | New path                              |
  | ------------------------------------- | ------------------------------------- |
  | `GET /v1/applicants`                  | `GET /v1/candidates`                  |
  | `GET /v1/get-applicant?applicant_id=` | `GET /v1/get-candidate?candidate_id=` |
  | `GET /v1/job-applicants?job_id=`      | `GET /v1/job-candidates?job_id=`      |
  | `PATCH /v1/update-applicant`          | `PATCH /v1/update-candidate`          |

  | Old field                     | New field          |
  | ----------------------------- | ------------------ |
  | `applicant_id` (query / body) | `candidate_id`     |
  | `applicants[]` (response)     | `candidates[]`     |
  | `total_applicants`            | `total_candidates` |
  | `applicant` (single object)   | `candidate`        |

  A new endpoint `GET /v1/get-candidate?candidate_id=` was added — single-candidate fetches were previously undocumented.

  ### Webhook path changes

  | Old path                  | New path                        |
  | ------------------------- | ------------------------------- |
  | `PATCH /v1/webhooks`      | `PATCH /v1/webhook`             |
  | `DELETE /v1/webhooks?id=` | `DELETE /v1/delete-webhook?id=` |

  `GET /v1/webhooks` and `POST /v1/create-webhook` are unchanged.

  **Multiple webhooks per workspace are now allowed.** The previous one-per-workspace unique constraint has been dropped.

  ### Lowercase status enums

  Status values are now lowercase in both input and output.

  * **Job status** — input accepts `Pending` `Active` `Paused` `Hired` `Closed` (capitalized values still accepted for backwards compatibility) and normalizes them. `Pending` maps to `draft`. `Hired` is accepted as a **deprecated alias** for `closed`. Output is always lowercase: one of `draft` `active` `paused` `closed`.
  * **Candidate status** — canonical lowercase values: `applied` `screening` `phone_screen` `interview` `technical` `offer` `hired` `rejected` `withdrawn` `on_hold` `shortlisted` `qualified` `uploaded`. The previous 7-value capitalized list (`Applied` / `Reviewed` / `Accepted` / `Scheduled` / `Met` / `Hired` / `Rejected`) is no longer accepted.
  * **`job_mode`** — `onsite` `remote` `hybrid` (note: `onsite`, no hyphen).
  * **`job_type`** — `full-time` `part-time` `contract` `freelance` `internship` `temporary` `project-based`.
  * **`career_level`** — `junior` `mid-level` `senior` `team-leader` `manager` `director` `vp` `c-level`.

  ### Scopes removed

  The scope system has been removed entirely. Any valid API token can call any endpoint — there is no `Token is missing required scope` error any more. The `developers/scopes` page has been deleted from the documentation. Existing tokens continue to work.

  ### Other changes

  * **`job_location`** in job responses is now formatted as `"City, Country"` (the city portion is omitted if the job has no city).
  * **Companies** are soft-deleted using an `archived_at` timestamp. No public-facing behavior change for `DELETE /v1/delete-company` — the response shape is the same.
</Update>

<Update label="May 2026" description="Google Jobs sync field" tags={["New"]}>
  Jobs created via the API now include a `google_jobs_indexed` boolean in the response, indicating whether the listing has been submitted to Google Jobs indexing.
</Update>

<Update label="April 2026" description="Webhook event types expanded" tags={["New"]}>
  Five new webhook event types are now available:

  | Event                     | Description                                 |
  | ------------------------- | ------------------------------------------- |
  | `candidate.stage_changed` | Fired when a candidate moves pipeline stage |
  | `candidate.hired`         | Fired when a candidate is marked as hired   |
  | `interview.scheduled`     | Fired when a meeting is booked              |
  | `requisition.approved`    | Fired when a requisition is approved by HR  |
  | `ai_prescreen.completed`  | Fired when an AI Pre-Screen session ends    |

  See the [Event Types](/developers/webhooks/event-types) reference for full payloads.
</Update>

<Update label="April 2026" description="Create Company endpoint" tags={["New"]}>
  Added `POST /companies` — create a company directly via the API. See [Create Company](/developers/companies/create-company) for the full schema.
</Update>

<Update label="April 2026" description="Applicant status values expanded" tags={["New"]}>
  The `status` field on applicants now supports two additional values:

  * `scheduled` — interview has been scheduled
  * `met` — interview has been completed

  These align with the pipeline stages available in the Hirempire UI and MCP Server.
</Update>

<Update label="March 2026" description="Webhooks — real-time event delivery" tags={["New"]}>
  The Hirempire Webhooks API is now available. Subscribe to workspace events and receive instant `POST` notifications to your endpoint.

  **Supported events at launch:**

  | Event                        | Trigger                      |
  | ---------------------------- | ---------------------------- |
  | `job_added`                  | A new job is created         |
  | `job_updated`                | A job's details are changed  |
  | `job_deleted`                | A job is deleted             |
  | `new_applicant`              | A candidate applies to a job |
  | `cv_processed`               | CV parsing by AI completes   |
  | `meeting_created`            | An interview is scheduled    |
  | `application_status_changed` | A candidate's status changes |

  Endpoints: `POST /webhooks` (create), `GET /webhooks` (list), `PUT /webhooks/:id` (update).

  Each registered webhook goes through a **challenge verification** step — your endpoint must echo back the challenge token before delivery begins.

  See the [Webhooks reference](/developers/webhooks/get-started) for full setup instructions and payload schemas.
</Update>

<Update label="March 2026" description="Rate limits introduced" tags={["New"]}>
  API rate limits are now enforced per plan. Exceeding the limit returns `HTTP 429 Too Many Requests`.

  | Plan    | Requests per hour |
  | ------- | ----------------- |
  | Free    | 100               |
  | Starter | 500               |
  | Pro     | 1,000             |
  | Premium | 5,000             |
</Update>

<Update label="March 2026" description="Bearer token scopes" tags={["New"]}>
  API tokens now support **granular scopes**. When generating a token from **Settings → Integrations → API Tokens**, you choose which resource groups the token can access:

  * `Jobs` — read and write job postings
  * `Applicants` — read and update applicant records
  * `Companies` — create and read company profiles

  Requests that use a token without the required scope return:

  ```json theme={null}
  {
    "success": false,
    "error": "Token is missing required scope 'Jobs'"
  }
  ```
</Update>

<Update label="March 2026" description="Initial API launch — Jobs and Applicants endpoints" tags={["New"]}>
  The Hirempire REST API launched with full **Jobs** and **Applicants** coverage.

  **Jobs endpoints:**

  | Method   | Path                  | Description                                        |
  | -------- | --------------------- | -------------------------------------------------- |
  | `GET`    | `/v1/jobs`            | List all jobs                                      |
  | `GET`    | `/v1/jobs/:id`        | Get a specific job                                 |
  | `POST`   | `/v1/jobs`            | Create a job                                       |
  | `PUT`    | `/v1/jobs/:id/status` | Update job status (`Active` / `Paused` / `Closed`) |
  | `DELETE` | `/v1/jobs/:id`        | Delete a job                                       |

  **Applicants endpoints:**

  | Method | Path                        | Description                           |
  | ------ | --------------------------- | ------------------------------------- |
  | `GET`  | `/v1/applicants`            | List all applicants across all jobs   |
  | `GET`  | `/v1/applicants/:id`        | Get a specific applicant              |
  | `GET`  | `/v1/jobs/:id/applicants`   | Get all applicants for a specific job |
  | `PUT`  | `/v1/applicants/:id/status` | Update applicant status               |

  **Applicant status values at launch:** `new`, `reviewed`, `accepted`, `rejected`

  All endpoints require Bearer token authentication. See [Get Started](/developers/get-started) for base URL, authentication, and response format details.
</Update>