---
updatedAt: 2026-05-05T13:44:18.000Z
---

Fetch the complete documentation index at: https://apidocs.eightfold.ai/llms.txt. Use this file to discover all available pages before exploring further.

# List Succession Plans

Search and get a list of succession plans based on the search parameters given

# OpenAPI definition

```json
{
  "servers": [
    {
      "url": "https://apiv2.{domain}.ai",
      "variables": {
        "domain": {
          "default": "eightfold",
          "enum": [
            "eightfold",
            "eightfold-eu",
            "eightfold-gov",
            "eightfold-ca",
            "eightfold-me",
            "eightfold-wu",
            "eightfold-ap"
          ]
        }
      }
    }
  ],
  "paths": {
    "/api/v2/careerhub/succession_plans": {
      "get": {
        "description": "Search and get a list of succession plans based on the search parameters given",
        "operationId": "list_succession_plan",
        "parameters": [
          {
            "description": "The secret key to access the api. It starts with the bearer token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Specifies the offset value to start for the page",
            "in": "query",
            "name": "start",
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Specifies the number of entries to be returned for the page",
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "This specifies list of incumbent profile IDs. If this is given, only plans that have incumbents who match the specified profile IDs are returned. The format should be comma-separated values with or without spaces (ex. 1000,2000, 3000).",
            "in": "query",
            "name": "incumbentIds",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Wildcard text used when searching for the results",
            "in": "query",
            "name": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exclude specific fields in the response. Possible values are the names of the top level fields present in corresponding API schema. To check API schema, expand the response section below.",
            "in": "query",
            "name": "exclude",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Allows selective control over the fields returned in the API response. If the keyList is empty, all fields will be returned. Possible values are the names of the top level fields present in corresponding API schema. To check API schema, expand the response section below.",
            "in": "query",
            "name": "keyList",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/SuccessionPlanSchema"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/MetaSchema"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "OK"
          }
        },
        "summary": "List Succession Plans",
        "tags": [
          "Succession Plan"
        ]
      }
    }
  },
  "info": {
    "title": "Api_server_v2_service Service",
    "version": "1.0.0"
  },
  "openapi": "3.0.2",
  "components": {
    "schemas": {
      "EmployeeMatchScoreSchema": {
        "type": "object",
        "properties": {
          "matchType": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "Match score criteria"
          },
          "rawScore": {
            "type": "number",
            "format": "float",
            "readOnly": true,
            "nullable": true,
            "description": "Raw match score in float"
          },
          "topMatches": {
            "type": "array",
            "readOnly": true,
            "nullable": true,
            "description": "Top items matched based on the match type",
            "items": {
              "type": "string"
            }
          },
          "score": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": "Rounded match score in integer"
          }
        }
      },
      "MetaSchema": {
        "type": "object",
        "properties": {
          "totalCount": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": ""
          },
          "pageTotalCount": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": ""
          },
          "pageStartIndex": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": ""
          }
        }
      },
      "SuccessionPlanCaretaker": {
        "type": "object",
        "properties": {
          "createdAt": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": "Timestamp when the caretaker was first added to the plan"
          },
          "employeeId": {
            "type": "string",
            "nullable": true,
            "description": "ATS/HRIS employee ID of the caretaker"
          },
          "updatedAt": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": "Timestamp when the caretaker data was last updated"
          },
          "profileId": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "description": "Eightfold decoded profile ID (numeric) of the caretaker"
          }
        }
      },
      "SuccessionPlanIncumbent": {
        "type": "object",
        "properties": {
          "externalJobId": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "Position ID associated with the incumbent in ATS/HRIS"
          },
          "employeeId": {
            "type": "string",
            "nullable": true,
            "description": "ATS/HRIS employee ID of the incumbent"
          },
          "profileId": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "description": "Eightfold decoded profile ID (numeric) of the incumbent"
          }
        }
      },
      "SuccessionPlanSuccessor": {
        "type": "object",
        "properties": {
          "createdAt": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": "Timestamp when the successor was first added to the plan"
          },
          "order": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "description": "Order of the successor within its succession state group"
          },
          "profileId": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "description": "Eightfold decoded profile ID (numeric)"
          },
          "employeeId": {
            "type": "string",
            "nullable": true,
            "description": "ATS/HRIS employee ID of the successor"
          },
          "matchScores": {
            "readOnly": true,
            "nullable": true,
            "description": "Match score details",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmployeeMatchScoreSchema"
            }
          },
          "updatedAt": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": "Timestamp when the successor data was last updated"
          },
          "state": {
            "type": "string",
            "nullable": true,
            "description": "Succession state of the successor"
          }
        }
      },
      "SuccessionPlanMetricFields": {
        "type": "object",
        "properties": {
          "insightTag": {
            "type": "array",
            "readOnly": true,
            "nullable": true,
            "description": "Tags to highlight key aspects of the plan",
            "items": {
              "type": "string"
            }
          },
          "pipelineStrength": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "Strength of the plan’s successor pipeline"
          },
          "femalePercentage": {
            "type": "number",
            "format": "float",
            "readOnly": true,
            "nullable": true,
            "description": "Percentage of female successors in the plan"
          },
          "diverseEthnicityPercentage": {
            "type": "number",
            "format": "float",
            "readOnly": true,
            "nullable": true,
            "description": "Percentage of diverse-ethnicity successor in the plan"
          }
        }
      },
      "SuccessionPlanSchema": {
        "type": "object",
        "properties": {
          "createdAt": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": "Timestamp representing creation date and time of the succession plan"
          },
          "associatedRoleId": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "Eightfold role ID associated with the succession plan"
          },
          "jobCode": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "External job code of the incumbent(s)"
          },
          "caretakers": {
            "readOnly": true,
            "nullable": true,
            "description": "Caretaker profile IDs of the succession plan",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SuccessionPlanCaretaker"
            }
          },
          "entityId": {
            "type": "string",
            "readOnly": true,
            "nullable": true,
            "description": "ATS/HRIS position ID associated with the plan"
          },
          "positionCriticalityTags": {
            "type": "array",
            "readOnly": true,
            "nullable": true,
            "description": "Criticality tags of the succession plan that is associated with the position held by the incumbent",
            "items": {
              "type": "string"
            }
          },
          "incumbents": {
            "nullable": true,
            "description": "Incumbents of the succession plan",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SuccessionPlanIncumbent"
            }
          },
          "planType": {
            "type": "string",
            "nullable": true,
            "description": "Type of the succession plan Ex. either \"position\" or \"role\" (only honored for POST)"
          },
          "planName": {
            "type": "string",
            "nullable": true,
            "description": "Name of the succession plan"
          },
          "successors": {
            "readOnly": true,
            "nullable": true,
            "description": "Successors of the succession plan",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SuccessionPlanSuccessor"
            }
          },
          "updatedAt": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "nullable": true,
            "description": "Timestamp representing the updation date and time of the succession plan"
          },
          "metricFields": {
            "readOnly": true,
            "nullable": true,
            "description": "Metric fields highlighting key aspects of the succession plan",
            "allOf": [
              {
                "$ref": "#/components/schemas/SuccessionPlanMetricFields"
              }
            ]
          },
          "roleCriticalityTags": {
            "type": "array",
            "readOnly": true,
            "nullable": true,
            "description": "Criticality tags of the role that is associated with the position held by the incumbent",
            "items": {
              "type": "string"
            }
          },
          "positionId": {
            "type": "integer",
            "format": "int32",
            "readOnly": true,
            "description": "Eightfold position ID associated with the succession plan"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Description of the succession plan"
          }
        },
        "required": [
          "positionId"
        ]
      }
    }
  }
}
```