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

# Patch Succession Plan

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

Update existing succession plan's metadata. Refer to request schema for fields that can be updated. For updating successors and caretakers, please use the dedicated successor and caretaker endpoints. Note: All required body params in the schema are not enforced in PATCH request, unlike path params.

## Path parameters

- `positionId` integer, required

## Headers

- `Authorization` string, required

## Request body

- SuccessionPlanPatchSchema
  - `planName` string, nullable — Name of the succession plan
  - `description` string, nullable — Description of the succession plan
  - `positionCriticalityTags` string[], nullable — Criticality tags of the succession plan that is associated with the position held by the incumbent

## 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, nullable — 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

---

[API](https://skmtc.net/eightfold/apis/api-server-v2-service-service.md) · [All operations](https://skmtc.net/eightfold/apis/api-server-v2-service-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/eightfold/api-server-v2-service-service/versions/0fb26f4e41bf/schema)