Charthop change API

openapi: 3.2.0
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access Change API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: change
paths:
  /v1/org/{orgId}/change:
    get:
      tags:
      - change
      summary: Return recent changes across an org, or for a particular person or job
      operationId: findChanges
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: scenarioId
        in: query
        description: Scenario id
        required: false
        schema:
          type: string
      - name: date
        in: query
        description: Date to start from
        required: false
        schema:
          type: string
          format: date
      - name: untilDate
        in: query
        description: Date to get changes through (exclusive)
        required: false
        schema:
          type: string
          format: date
      - name: type
        in: query
        description: Types of change to filter by
        required: false
        schema:
          type: string
      - name: fields
        in: query
        description: Return changes that modify these fields
        required: false
        schema:
          type: string
      - name: personId
        in: query
        description: Person id to filter by
        required: false
        schema:
          type: string
      - name: jobId
        in: query
        description: Job id to filter by
        required: false
        schema:
          type: string
      - name: includeBackfill
        in: query
        description: Find and include first backfill if it exists
        required: false
        schema:
          type: boolean
      - name: refs
        in: query
        description: References to filter by
        required: false
        schema:
          type: string
      - name: q
        in: query
        description: Query to filter against
        required: false
        schema:
          type: string
      - name: from
        in: query
        description: Change id to start paginating from
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: open
        in: query
        description: Whether the role is open or not
        required: false
        schema:
          type: string
          enum:
          - FILLED
          - OPEN
      - name: desc
        in: query
        description: Descending (default false)
        required: false
        schema:
          type: boolean
      - name: scenarioOnly
        in: query
        description: Scenario only (exclude primary changes)
        required: false
        schema:
          type: boolean
      - name: parentOnly
        in: query
        description: Parent changes only (exclude child changes)
        required: false
        schema:
          type: boolean
      - name: excludeAtsRecruitingFields
        in: query
        description: Whether to exclude ats recruiting fields. Only applies when fieldEntityTypeString is passed
        required: false
        schema:
          type: boolean
      - name: includeStruck
        in: query
        description: Deprecated parameter for backwards-compatibility (use statuses) - whether to include STRUCK and PROPOSED changes, or just ACTIVE changes
        required: false
        schema:
          type: boolean
      - name: status
        in: query
        description: Statuses to filter by
        required: false
        schema:
          type: string
      - name: stripUpdates
        in: query
        description: Whether to strip returned update changes of update types that were not explicitly requested
        required: false
        schema:
          type: boolean
      - name: format
        in: query
        description: Data format to use; default is json, can also use json-extended or json-readable
        required: false
        schema:
          type: string
      - name: fieldEntityTypes
        in: query
        description: Only return changes which set fields with these entity types
        required: false
        schema:
          type: string
      - name: returnAccess
        in: query
        description: 'Return access information -- pass a list of actions to check, for example: create,update,delete'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsChange'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/change/bulkchange:
    post:
      tags:
      - change
      summary: Perform a series of changes at once
      operationId: bulkChange
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkChangeRequest'
        description: Bulk change data
  /v1/org/{orgId}/change/bulkupdate:
    post:
      tags:
      - change
      summary: Perform a bulk update on a number of jobs
      operationId: bulkUpdate
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdateRequest'
        description: Bulk update data
  /v1/org/{orgId}/change/compensation-history:
    get:
      tags:
      - change
      summary: Return enriched compensation history rows (one row per comp change), in descending date order
      operationId: findCompensationHistory
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: startDate
        in: query
        description: Date to start from
        required: false
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: Date to get changes through (inclusive)
        required: false
        schema:
          type: string
          format: date
      - name: q
        in: query
        description: Filter query string
        required: false
        schema:
          type: string
      - name: from
        in: query
        description: Cursor for paginating from a previous response
        required: false
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: format
        in: query
        description: Data format to use; default is json, can also use json-extended or json-readable
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsCompensationHistoryRow'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/change/depart-rehire:
    post:
      tags:
      - change
      summary: Create a depart-rehire pair of changes, for filling in historical data
      operationId: departRehire
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: startDate
        in: query
        description: Rehire start date
        required: false
        schema:
          type: string
          format: date
      responses:
        '202':
          description: accepted
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChange'
        description: Depart data
        required: true
  /v1/org/{orgId}/change/scenario/{scenarioId}:
    get:
      tags:
      - change
      summary: Return all changes for a particular scenario, with before job
      operationId: findScenarioChanges
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: scenarioId
        in: path
        description: Scenario id
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: Fields to retrieve
        required: false
        schema:
          type: string
      - name: format
        in: query
        description: Data format to use; default is json, can also use json-extended or json-readable
        required: false
        schema:
          type: string
      - name: q
        in: query
        description: Search query
        required: false
        schema:
          type: string
      - name: returnAccess
        in: query
        description: 'Return access information -- pass a list of actions to check, for example: create,update,delete'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScenarioChangesWithBudgetRollup'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/change/sync/{type}:
    post:
      tags:
      - change
      summary: Sync a change (create the change only if it does not already exist)
      operationId: syncChange
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: type
        in: path
        description: Change type
        required: true
        schema:
          type: string
      - name: processId
        in: query
        description: Process id of person creation
        required: false
        schema:
          type: string
      responses:
        '200':
          description: synced change
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Change'
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChange'
        description: Change data
  /v1/org/{orgId}/change/{changeId}:
    get:
      tags:
      - change
      summary: Return a particular change by id
      operationId: getChange
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: changeId
        in: path
        description: Change id
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: Data format to use; default is json, can also use json-extended or json-readable
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Change'
        '400':
          description: bad request
        '404':
          description: not found
    patch:
      tags:
      - change
      summary: Make a change to a change
      operationId: updateChange
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: changeId
        in: path
        description: Change id
        required: true
        schema:
          type: string
      - name: processId
        in: query
        description: Process id of person creation
        required: false
        schema:
          type: string
      responses:
        '204':
          description: no content
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateChange'
        description: Change data
        required: true
    delete:
      tags:
      - change
      summary: Delete a previous change
      operationId: deleteChange
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: changeId
        in: path
        description: Change id
        required: true
        schema:
          type: string
      - name: processId
        in: query
        description: Process id of person creation
        required: false
        schema:
          type: string
      responses:
        '400':
          description: bad request
        '404':
          description: not found
  /v1/org/{orgId}/change/{changeId}/approve:
    post:
      tags:
      - change
      summary: Approve or reject a change
      operationId: approveChange
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: changeId
        in: path
        description: Change id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: no content
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveChange'
        description: Change approval details
        required: true
  /v1/org/{orgId}/change/{changeId}/approver:
    get:
      tags:
      - change
      summary: Given a of change id, see if the person can approve/reject
      operationId: changeApprover
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: changeId
        in: path
        description: Change Id
        required: true
        schema:
          type: string
      - name: date
        in: query
        description: Date to check the approval on
        required: false
        schema:
          type: string
          format: date
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: boolean
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/change/{type}:
    post:
      tags:
      - change
      summary: Create a new change
      operationId: createChange
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: type
        in: path
        description: Change type
        required: true
        schema:
          type: string
      - name: source
        in: query
        description: Source of change
        required: false
        schema:
          type: string
      - name: processId
        in: query
        description: Process id of change creation
        required: false
        schema:
          type: string
      responses:
        '201':
          description: created change
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Change'
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChange'
        description: Change data
  /v1/org/{orgId}/change/{type}/validate:
    post:
      tags:
      - change
      summary: Validate a change
      operationId: validateChange
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: type
        in: path
        description: Change type
        required: true
        schema:
          type: string
      responses:
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChange'
        description: Change data
  /v1/org/{orgId}/scenario/{scenarioId}/change/{changeId}:
    patch:
      tags:
      - change
      summary: Amend a change within a scenario, and potentially return the updated data
      operationId: updateScenarioChange
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: scenarioId
        in: path
        description: Scenario id
        required: true
        schema:
          type: string
      - name: changeId
        in: path
        description: Change id
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: Fields to retrieve
        required: false
        schema:
          type: string
      - name: includeUpdatedFields
        in: query
        description: Include all updated fields in the response, including change.after.fieldName for each updated field
        required: false
        schema:
          type: boolean
      - name: format
        in: query
        description: Data format to return; default is json, can also use json-extended or json-readable
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateScenarioChangeResponse'
        '204':
          description: no content
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: object
        description: Column and data to update (must contain only one entry)
        required: true
  /v1/org/{orgId}/scenario/{scenarioId}/change/{changeId}/status/{processId}:
    get:
      tags:
      - change
      summary: Get the status of a running change within a scenario
      operationId: getChangeStatus
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: scenarioId
        in: path
        description: Scenario id
        required: true
        schema:
          type: string
      - name: changeId
        in: path
        description: Change id
        required: true
        schema:
          type: string
      - name: processId
        in: path
        description: Process id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeStatusResponse'
        '404':
          description: not found
components:
  schemas:
    CreateChange:
      type: object
      properties:
        jobId:
          type: string
          description: job id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent organization id
          example: 588f7ee98f138b19220041a7
        scenarioId:
          type: string
          description: scenario that this change belongs to
          example: 588f7ee98f138b19220041a7
        personId:
          type: string
          description: the id of the person involved, or empty if no person attached to job
          example: 588f7ee98f138b19220041a7
        otherJobId:
          type: string
          description: for MOVE changes, the id of the job moving from; for RELATE changes, the id of the other job
          example: 588f7ee98f138b19220041a7
        type:
          type: string
          description: type of change
          enum:
          - HIRE
          - DEPART
          - MOVE
          - UPCOMING
          - CREATE
          - UPDATE
          - DATA
          - DELETE
          - RELATE
          - BACKFILL
        date:
          type: string
          format: date
          description: date of change
        announceDate:
          type: string
          format: date
          description: for HIRE and DEPART changes, the announce date, if the announce date is different from the date of change
        departType:
          type: string
          description: for DEPART changes, the type of departure
          enum:
          - VOLUNTARY
          - INVOLUNTARY
        departRegret:
          type: string
          description: for DEPART changes, whether the departure is regrettable
          enum:
          - REGRET
          - NONREGRET
        reason:
          type: string
          description: the reason of the change
        promotionType:
          type: string
          description: if it's a promotion or a demotion
          enum:
          - PROMOTION
          - DEMOTION
          - NONE
        job:
          description: for CREATE changes, the initial job data; for other changes, the title and groups at the time of change
          $ref: '#/components/schemas/PartialJob'
        update:
          description: for UPDATE changes, the data being updated
          $ref: '#/components/schemas/JobUpdate'
        note:
          type: string
          description: note on the change
        mergeId:
          type: string
          description: merged by user id, if this change was merged
          example: 588f7ee98f138b19220041a7
        mergeScenarioId:
          type: string
          description: scenario that this change was merged in from, if the change originally came from a scenario
          example: 588f7ee98f138b19220041a7
        overrideDefaults:
          type: object
          description: for job code linked field overrides, records the default job code value
          additionalProperties:
            type: object
        autoAppliedDefaults:
          type: object
          description: for job code linked fields, records which fields were auto-populated from defaults
          additionalProperties:
            type: object
    ChangeData:
      type: object
      required:
      - change
      - data
      - cost
      properties:
        change:
          description: the change that was applied
          $ref: '#/components/schemas/Change'
        data:
          type: object
          description: the returned data fields requested
          additionalProperties:
            type: object
        cost:
          type: number
          description: the annualized impact of this change, denoted in organization's currency
        lockedFields:
          type: array
          description: set of locked fields for this change
          uniqueItems: true
          items:
            type: string
    Money:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: number
        currency:
          type: string
        places:
          type: integer
          format: int32
    ChangeStatusResponse:
      type: object
      required:
      - processId
      - status
      properties:
        processId:
          type: integer
          format: int32
        status:
          type: boolean
    JobRelationship:
      type: object
      required:
      - jobId
      - type
      properties:
        jobId:
          type: string
          description: destination job id
          example: 5887a7718f138b6a2a0041a7
        type:
          type: string
          description: type of relationship
          enum:
          - MANAGER
          - DIRECT
          - INDIRECT_MANAGER
          - INDIRECT
          - NONE
    StockGrant:
      type: object
      required:
      - id
      - stock
      - date
      - shares
      - price
      - type
      - vestSchedule
      properties:
        id:
          type: string
          description: unique identifier of grant
        stock:
          type: string
          description: ticker symbol of this stock
          example: GOOG
        date:
          type: string
          format: date
          description: date of grant
        vestStartDate:
          type: string
          format: date
          description: vesting start date of grant
        expireDate:
          type: string
          format: date
          description: expiration date of grant
        shares:
          type: number
          description: number of shares granted
        price:
          type: number
          description: per share strike price
        type:
          type: string
          description: type of grant
          enum:
          - ISO
          - NSO
          - RSU
          - SAR
          - PERFORMANCE_SHARES
          - PHANTOM_STOCK
          - RSA
        vestSchedule:
          type: string
          description: vesting schedule
        originalPrice:
          type: number
          description: original per share value of stock (grant price at time of issue)
        currentPrice:
          type: number
          description: current per share value of stock
        vestedShares:
          type: number
          description: current number of shares vested
        vestedSharesNextYear:
          type: number
          description: number of shares vested one year from today
        vestedSharesByDate:
          type: object
          description: number of shares vested, by future date
          additionalProperties:
            type: number
        vestEndDate:
          type: string
          format: date
          description: vesting end date
        cancelDate:
          type: string
          format: date
          description: cancellation date
        terminationDate:
          type: string
          format: date
          description: termination date — vesting freezes on this date when the holder separates
        lastExercisableDate:
          type: string
          format: date
          description: last date on which vested shares can be exercised; after this the grant is forfeited
        details:
          type: string
          description: details of the grant (arbitrary text)
        description:
          type: string
          description: human-readable description of vesting schedule
    ResultsChangeData:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ChangeData'
        next:
          type: string
        access:
          type: array
          items:
            $ref: '#/components/schemas/ResultsAccess'
    ApproveChange:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - ACTIVE
          - STRUCK
          - CONFLICT
          - INACTIVE
          - PROPOSED
        approvalNote:
          type: string
        changeId:
          type: string
          example: 588f7ee98f138b19220041a7
    UpdateChange:
      type: object
      properties:
        date:
          type: string
          format: date
          description: date of change
        announceDate:
          type: string
          format: date
          description: for HIRE and DEPART changes, the announce date, if the announce date is different from the date of change
        status:
          type: string
          description: whether the change is active or not
          enum:
          - ACTIVE
          - STRUCK
          - CONFLICT
          - INACTIVE
          - PROPOSED
        departType:
          type: string
          description: for DEPART changes, the type of departure
          enum:
          - VOLUNTARY
          - INVOLUNTARY
        departRegret:
          type: string
          description: for DEPART changes, whether the departure is regrettable
          enum:
          - REGRET
          - NONREGRET
        reason:
          type: string
          description: the reason of the change
        promotionType:
          type: string
          description: if it's a promotion or a demotion
          enum:
          - PROMOTION
          - DEMOTION
          - NONE
        job:
          description: for CREATE changes, the initial job data; for other changes, the title and groups at the time of change
          $ref: '#/components/schemas/PartialJob'
        update:
          description: for UPDATE changes, the data being updated
          $ref: '#/components/schemas/JobUpdate'
        note:
          type: string
          description: note on the change
        approvalNote:
          type: string
          description: approval/rejection note
          example: Not acceptable
    BulkChangeRequest:
      type: object
      required:
      - changes
      properties:
        changes:
          type: array
          description: list of changes to create
          items:
            $ref: '#/components/schemas/CreateChange'
    ResultsAccess:
      type: object
      required:
      - allowed
      properties:
        ids:
          type: array
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        allowed:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/AccessAction'
    PartialJob:
      type: object
      properties:
        jobId:
          type: string
          description: globally unique job id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent organization id
          example: 588f7ee98f138b19220041a7
        snapshotId:
          type: string
          description: snapshot that this job belongs to
          example: 588f7ee98f138b19220041a7
        title:
          type: string
          description: job title
          example: Senior Engineer
          minItems: 1
          maxItems: 160
        comp:
          description: compensation
          $ref: '#/components/schemas/Comp'
        sensitive:
          type: string
          description: view sensitive of the job while open
          enum:
          - GLOBAL
          - ORG
          - SE

# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/charthop/refs/heads/main/openapi/charthop-change-api-openapi.yml