---
title: "Delete Succession Plan"
method: DELETE
path: "/api/v2/careerhub/succession_plans/{positionId}"
tags: ["Succession Plan"]
---

# Delete Succession Plan

`DELETE /api/v2/careerhub/succession_plans/{positionId}`

## Request

- Base URL: `https://apiv2.eightfold.ai`
- URL: `https://apiv2.eightfold.ai/api/v2/careerhub/succession_plans/{positionId}`
- Auth: none declared. Required headers: `Authorization`
- TypeScript: <https://skmtc.dev/eightfold/apis/api-server-v2-service-service/docs/api/v2/careerhub/succession_plans/:positionId/delete.ts> (a function with typed inputs; its response is checked against the schema)

Deletes a succession plan specified by the Eightfold position ID

## Path parameters

- `positionId` integer, required

## Headers

- `Authorization` string, required

## Response `200`

OK

- SuccessionPlanSchema
  - `createdAt` integer, nullable: Timestamp representing creation date and time of the succession plan
  - `associatedRoleId` string, nullable: Eightfold role ID associated with the succession plan
  - `jobCode` string, nullable: External job code of the incumbent(s)
  - `caretakers` SuccessionPlanCaretaker[], nullable: Caretaker profile IDs of the succession plan
    - `createdAt` integer, nullable: Timestamp when the caretaker was first added to the plan
    - `employeeId` string, nullable: ATS/HRIS employee ID of the caretaker
    - `updatedAt` integer, nullable: Timestamp when the caretaker data was last updated
    - `profileId` integer, nullable: Eightfold decoded profile ID (numeric) of the caretaker
  - `entityId` string, nullable: ATS/HRIS position ID associated with the plan
  - `positionCriticalityTags` string[], nullable: Criticality tags of the succession plan that is associated with the position held by the incumbent
  - `incumbents` SuccessionPlanIncumbent[], nullable: Incumbents of the succession plan
    - `externalJobId` string, nullable: Position ID associated with the incumbent in ATS/HRIS
    - `employeeId` string, nullable: ATS/HRIS employee ID of the incumbent
    - `profileId` integer, nullable: Eightfold decoded profile ID (numeric) of the incumbent
  - `planType` string, nullable: Type of the succession plan Ex. either "position" or "role" (only honored for POST)
  - `planName` string, nullable: Name of the succession plan
  - `successors` SuccessionPlanSuccessor[], nullable: Successors of the succession plan
    - `createdAt` integer, nullable: Timestamp when the successor was first added to the plan
    - `order` integer, nullable: Order of the successor within its succession state group
    - `profileId` integer, nullable: Eightfold decoded profile ID (numeric)
    - `employeeId` string, nullable: ATS/HRIS employee ID of the successor
    - `matchScores` EmployeeMatchScoreSchema[], nullable: Match score details
      - `matchType` string, nullable: Match score criteria
      - `rawScore` number, float, nullable: Raw match score in float
      - `topMatches` string[], nullable: Top items matched based on the match type
      - `score` integer, nullable: Rounded match score in integer
    - `updatedAt` integer, nullable: Timestamp when the successor data was last updated
    - `state` string, required: Succession state of the successor
  - `updatedAt` integer, nullable: Timestamp representing the updation date and time of the succession plan
  - `metricFields` SuccessionPlanMetricFields
    - `insightTag` string[], nullable: Tags to highlight key aspects of the plan
    - `pipelineStrength` string, nullable: Strength of the plan’s successor pipeline
    - `femalePercentage` number, float, nullable: Percentage of female successors in the plan
    - `diverseEthnicityPercentage` number, float, nullable: Percentage of diverse-ethnicity successor in the plan
  - `roleCriticalityTags` string[], nullable: Criticality tags of the role that is associated with the position held by the incumbent
  - `positionId` integer, required: Eightfold position ID associated with the succession plan
  - `description` string, nullable: Description of the succession plan

## Changes

- **2026-11-03** `9a8b3a927e93`: 1 info
  - the response property `successors/items/state` became required for the status `200`

[Operation history](https://skmtc.dev/eightfold/apis/api-server-v2-service-service/changes/api/v2/careerhub/succession_plans/:positionId/delete.md)

---

[API](https://skmtc.dev/eightfold/apis/api-server-v2-service-service.md) - [All operations](https://skmtc.dev/eightfold/apis/api-server-v2-service-service/llms.txt) - [OpenAPI document](https://skmtc.dev/eightfold/apis/api-server-v2-service-service/revisions/9a8b3a927e93?raw)