Charthop preload API

openapi: 3.2.0
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access Preload API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: preload
paths:
  /v1/org/{orgId}/preload:
    get:
      tags:
      - preload
      summary: Return a set of pre-loaded data required by the web app
      operationId: getPreloadData
      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/PreloadResponse'
        '400':
          description: bad request
        '404':
          description: not found
components:
  schemas:
    Policy:
      type: object
      required:
      - id
      - label
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent organization id (empty if global)
          example: 588f7ee98f138b19220041a7
        label:
          type: string
          description: human-readable full name of policy
          example: View Compensation
          minItems: 3
          maxItems: 80
        description:
          type: string
          description: description of policy
          example: This policy allows compensation to be viewed.
          minItems: 0
          maxItems: 1000
        rules:
          type: array
          description: the rules that define the policy
          items:
            $ref: '#/components/schemas/PolicyRule'
        roles:
          type: array
          description: the roles the policy is attached to
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Role'
        users:
          type: array
          description: the users the policy is attached to
          uniqueItems: true
          items:
            $ref: '#/components/schemas/User'
        userCount:
          type: integer
          format: int32
          description: number of users the policy is attached to; populated when expand=true on the list endpoint
        createId:
          type: string
          description: created by user id
          example: 588f7ee98f138b19220041a7
        createAt:
          type: string
          description: created timestamp
          example: '2017-01-24T13:57:52Z'
        updateId:
          type: string
          description: last updated by user id
          example: 588f7ee98f138b19220041a7
        updateAt:
          type: string
          description: last updated timestamp
          example: '2017-01-24T13:57:52Z'
        deleteId:
          type: string
          description: deleted by user id
          example: 588f7ee98f138b19220041a7
        deleteAt:
          type: string
          description: deleted timestamp
          example: '2017-01-24T13:57:52Z'
    BuiltInCategoryMap:
      type: object
      required:
      - categoryId
      - fieldIds
      properties:
        categoryId:
          type: string
          description: id of the built-in category
          example: 588f7ee98f138b19220041a7
        fieldIds:
          type: array
          description: set of custom field ids that belongs to the built-in category
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
    Money:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: number
        currency:
          type: string
        places:
          type: integer
          format: int32
    Address:
      type: object
      required:
      - country
      properties:
        street1:
          type: string
          description: street address, line 1
          example: 123 Anywhere Street
          minItems: 0
          maxItems: 200
        street2:
          type: string
          description: street address, line 2
          example: Apt 6L
          minItems: 0
          maxItems: 200
        street3:
          type: string
          description: street address, line 3
          example: Sixth Floor
          minItems: 0
          maxItems: 200
        city:
          type: string
          description: city
          example: New York
          minItems: 0
          maxItems: 80
        state:
          type: string
          description: state
          example: NY
          minItems: 0
          maxItems: 80
        country:
          type: string
          description: country (two-digit ISO code)
          example: NY
          pattern: ^[A-Z]{2}$
        postal:
          type: string
          description: postal code
          example: '10001'
          minItems: 0
          maxItems: 10
        geo:
          description: geopoint location
          $ref: '#/components/schemas/Geopoint'
        approxGeo:
          description: approximate geopoint location (suitable for a map placement, but not exact location)
          $ref: '#/components/schemas/Geopoint'
    TargetedInstruction:
      type: object
      required:
      - filter
      - instructions
      properties:
        filter:
          type: string
          description: filter expression matched against the current viewer's person record
        instructions:
          type: string
          description: instructions injected into the chat prompt when filter matches
    PolicyRule:
      type: object
      properties:
        allow:
          type: array
          description: allow rules
          example: '[''job:read'', ''person.read'']'
          items:
            type: string
        deny:
          type: array
          description: deny rules
          example: '[''job:read'', ''person.read'']'
          items:
            type: string
        categories:
          type: array
          description: categories the rule is limited to
          example: '[''Compensation'', ''Stock Grants'']'
          items:
            type: string
        fields:
          type: array
          description: fields the rule is limited to
          example: '[''base'']'
          items:
            type: string
        departmentIds:
          type: array
          description: departments the rule is limited to
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        filter:
          type: string
          description: custom filter the rule is limited to
          example: department:engineering and under:me
        directions:
          type: array
          description: directions that the rule applies to -- either self or under
          items:
            type: string
        types:
          type: array
          description: types that the rule applies to
          items:
            type: string
        targets:
          type: array
          description: targets allowed for messaging (email addresses, chat channels, user ids)
          items:
            $ref: '#/components/schemas/PolicyRuleTarget'
        visibleSensitive:
          type: array
          description: if specified, controls visibility of sensitive entities -- for example, ['Manager Shared', 'Manager Only']
          items:
            type: string
        fieldsSensitive:
          type: array
          description: if specified, controls applicability of fields by sensitivity -- for example, ['Manager Shared', 'Manager Only']
          items:
            type: string
    OrgConfig:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent organization id
          example: 588f7ee98f138b19220041a7
        hiddenFieldIds:
          type: array
          description: set of hidden field ids of an org
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        builtinCategoryMap:
          type: array
          description: set of maps of the custom fields that belongs to a built-in category
          uniqueItems: true
          items:
            $ref: '#/components/schemas/BuiltInCategoryMap'
        builtinFieldConfig:
          type: array
          description: Org configuration for built-in fields
          uniqueItems: true
          items:
            $ref: '#/components/schemas/BuiltInFieldConfig'
        compensationBandsConfig:
          description: Org configuration for compensation bands tiers, multipliers, and job levels
          $ref: '#/components/schemas/CompensationBandsConfig'
        smartCurrencyOptions:
          type: array
          description: Options for where to source a currency to use when currency is unknown. order specific
          example: PERSON_HOME_ADDRESS_COUNTRY
          items:
            $ref: '#/components/schemas/SmartCurrencyOption'
        smartCurrencyDefault:
          type: string
          description: The default currency to use when currency is unknown and there are no options set in smartCurrencyOptions
          example: USD
        requiredJobFields:
          type: array
          description: Org configuration for required job fields
          uniqueItems: true
          items:
            type: string
        scenarioApprovalChains:
          type: object
          description: Configures which approval chains to use with specific scenario types
          additionalProperties:
            type: string
            example: 588f7ee98f138b19220041a7
        isOpenJobRoleApprovalEnabled:
          type: boolean
          description: Whether to show open job approval on Open Job Profile page
        isNotifySubmitterPerStage:
          type: boolean
          description: Whether to notify the scenario submitter each time an approval stage completes
        jobCodeFieldIds:
          type: array
          description: The set of field IDs that job codes can be set up to auto-fill
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        createId:
          type: string
          description: created by user id
          example: 588f7ee98f138b19220041a7
        createBehalfId:
          type: string
          description: created on behalf of user id
          example: 588f7ee98f138b19220041a7
        createAttribution:
          $ref: '#/components/schemas/Attribution'
        createAt:
          type: string
          description: created timestamp
          example: '2017-01-24T13:57:52Z'
        updateId:
          type: string
          description: last updated by user id
          example: 588f7ee98f138b19220041a7
        updateBehalfId:
          type: string
          description: last updated on behalf of user id
          example: 588f7ee98f138b19220041a7
        updateAttribution:
          $ref: '#/components/schemas/Attribution'
        updateAt:
          type: string
          description: last updated timestamp
          example: '2017-01-24T13:57:52Z'
        deleteId:
          type: string
          description: deleted by user id
          example: 588f7ee98f138b19220041a7
        deleteBehalfId:
          type: string
          description: deleted on behalf of user id
          example: 588f7ee98f138b19220041a7
        deleteAttribution:
          $ref: '#/components/schemas/Attribution'
        deleteAt:
          type: string
          description: deleted timestamp
          example: '2017-01-24T13:57:52Z'
        grantConfiguration:
          type: array
          description: Org Grant Configuration
          uniqueItems: true
          items:
            $ref: '#/components/schemas/GrantAlias'
    InternalOrgOptions:
      type: object
      properties:
        adpOrganizationOID:
          type: string
        assessmentCount:
          type: integer
          format: int32
        dashboardGettingStartedHidden:
          type: boolean
        dashboardNeedHelpHidden:
          type: boolean
        enableUniversalSso:
          type: boolean
        sequoiaOrgId:
          type: string
        tosAgreement:
          type: boolean
        fileUploadLimit:
          type: integer
          format: int64
        maxFileUploadSize:
          type: integer
          format: int64
        lowPriorityReports:
          type: boolean
        isInitialDataSynced:
          type: boolean
        maxReportDatapoints:
          type: integer
          format: int64
        disableImportEvents:
          type: boolean
          description: Whether to disable event notifications on imports -- should only be used temporarily in performance-critical initial imports
        useAlphaSlackApp:
          type: boolean
          description: Use the alpha Slack app (a second real Slack app sharing the global 'slack' install) instead of the default for inbound hooks and outbound messages — ChartHop-staff only, for Slack-team app-review testing
        extraFields:
          type: object
          additionalProperties:
            type: object
    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
    EnumValue:
      type: object
      required:
      - name
      - label
      properties:
        name:
          type: string
          description: enum value name
        label:
          type: string
          description: enum value label
        color:
          type: string
          description: color of property
          pattern: ^#[a-f0-9]{6}$
        expr:
          type: string
          description: computed expression, for ENUM_EXPR type
        num:
          type: number
          description: numeric value, for ENUM_SCALE type
        sort:
          type: integer
          format: int32
          description: sort order
        rank:
          type: integer
          format: int32
          description: rank order, if selected in rank order
        id:
          type: string
          description: unique identifier for enum
          example: 588f7ee98f138b19220041a7
        labelTr:
          description: translations for the label
          $ref: '#/components/schemas/Translations'
    ShareAccess:
      type: object
      required:
      - access
      properties:
        access:
          type: string
          description: access permission level
          enum:
          - NONE
          - LIMITED_READ
          - LIMITED_WRITE
          - STANDARD_READ
          - STANDARD_WRITE
          - COMPENSATION_READ
          - FULL_READ
          - COMP_PLANNING_PARTICIPANT
          - COMPENSATION_WRITE
          - WRITE
          - COMPENSATION_OWNER
          - OWNER
        userId:
          type: string
          description: user id
          example: 5887a7718f138b6a2a0041a7
        groupId:
          type: string
          description: group id
          example: 5887a7718f138b6a2a0041a7
        fields:
          type: string
          description: fields
          example: name,image,title
    DtValue:
      type: object
      properties:
        value:
          type: object
    BuiltInFieldConfig:
      type: object
      required:
      - name
      - hidden
      properties:
        name:
          type: string
          description: reserved codename for the native field
        hidden:
          type: boolean
          description: hidden state of the native field (specific to org)
        places:
          type: integer
          format: int32
          description: decimal places to round native Money fields
    Job:
      type: object
      required:
      - jobId
      - orgId
      - title
      - groupIds
      - fields
      properties:
        jobId:
          type: string
          description: globally unique job id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent organization id
          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
          - SENSITIVE
          - PERSONAL
          - MANAGER
          - HIGH
          - PRIVATE
        relationships:
          type: array
          description: relationship to other jobs
          uniqueItems: true
          items:
            $ref: '#/components/schemas/JobRelationship'
        managerIds:
          type: array
          description: list of managers, from immediate manager upwards
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        groupIds:
          type: array
          description: groups that this job is a member of
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        placement:
          type: string
          description: guidance on placement
          enum:
          - NORMAL
          - ASSISTANT
        employment:
          type: string
          description: employment status
          enum:
          - FULL
          - PART
          - TEMP
          - CONTRACT
          - INTERN
          - EXPAT
        fields:
          type: object
          description: fields containing custom data
          additionalProperties:
            type: object
        startDate:
          type: string
          format: date
          description: for empty jobs, expected start date - for filled jobs, confirmed start date
        startDatePlanned:
          type: string
          format: date
          description: expected start date whether job is open or has been filled - doesn't change when job is filled
        personStartDate:
          type: string
          format: date
          description: if personId is present, the first day of that person in the org after the latest departure (if any)
        personEndDate:
          type: string
          format: date
          description: if personId is present and the person is departing, the last day of that person in the org
        personJobStartDate:
          type: string
          format: date
          description: if personId is present, the first day of that person in the job
        personJobEndDate:
          type: string
          format: date
          description: if personId is present and the person is departing or moving out, the last day of that person in the job
        personId:
          type: string
          description: the person holding this job -- either currently in the job, or upcoming announced hire
          example: 588f7ee98f138b19220041a7
        upcoming:
          type: array
          description: if a HIRE, MOVE, or DEPART are upcoming, the details on those changes - should only include id, type, date, announceDate, personId
          items:
            $ref: '#/components/schemas/UpcomingChange'
        scenarioId:
          type: string
          description: scenario that the job was created in (null if job is on primary timeline)
          example: 588f7ee98f138b19220041a7
        backfillPersonId:
          type: string
          description: the person who most recently held the job, who this represents a backfill for
          example: 588f7ee98f138b19220041a7
    AiAgentConfig:
      type: object
      properties:
        personality:
          type: string
        instructions:
          type: string
        guardrails:
          type: string
        enableMemory:
          type: boolean
        enableMcpServer:
          type: boolean
          description: whether this agent exposes an MCP server endpoint for per-user OAuth access
        enableMcpWrite:
          type: boolean
          description: 'whether this agent''s MCP server may invoke write/mutating tools (e.g. a non-read-only AskAgent delegation). Read-only by default: when unset or false, a tool that mutates on the call is rejected at the MCP edge regardless of the agent''s role/policy. This is defense in depth layered on top of the role, never a grant beyond it.'
        isExternal:
          type: boolean
          description: 'whether this agent is an external (non-ChartHop) client, e.g. Claude Code or ChatGPT. External agents have no ChartHop-side prompt/behavior config: only permissions, MCP, and activity are configurable.'
        approvedPolicyRules:
          type: array
          items:
            $ref: '#/components/schemas/PolicyRule'
        approvalGuidelines:
          type: string
        managerJobId:
          type: string
          example: 588f7ee98f138b19220041a7
        messagingConfig:
          $ref: '#/components/schemas/MessagingConfig'
        contentIds:
          type: array
          description: pinned content document IDs; when merging user and app configs, both lists are unioned (not replaced); validate with validateContentIds before persisting
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        modelTier:
          type: string
          description: requested model tier for the agent; defaults to MEDIUM when not set
          enum:
          - HIGH
          - MEDIUM
          - LOW
        targetedInstructions:
          type: array
          description: audience-scoped instruction snippets injected into the chat prompt when the filter matches the current viewer's person record; size and filter syntax are checked by AgentValidationService before persisting
          items:
            $ref: '#/components/schemas/TargetedInstruction'
    Org:
      type: object
      required:
      - id
      - name
      - slug
      - options
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        customerId:
          type: string
          description: customer for billing processing
          example: 588f7ee98f138b19220041a7
        name:
          type: string
          description: name of organization
          example: Acme Corp
        slug:
          type: string
          description: unique slug of organization
          example: acme-corp
        type:
          type: string
          description: type of organization
          example: PRIVATE
          enum:
          - PRIVATE
          - PUBLIC
          - EDU
          - GOV
          - NONPROFIT
          - DEMO
          - TEST
          - PORTFOLIO
        industry:
          type: string
          description: industry
          example: Software and Internet
        estEmployees:
          type: integer
          format: int32
          description: approximate number of employees
        estRevenue:
          type: integer
          format: int32
          description: approximate amount of revenue
        foundedYear:
          type: string
          description: year of founding
          example: '1998'
        address:
          description: street address
          $ref: '#/components/schemas/Address'
        phone:
          type: string
          description: company phone number in E.164 format
          pattern: ^\+?[1-9]\d{1,14}$
        email:
          type: string
          description: primary contact email
          example: bob@example.com
        url:
          type: string
          format: uri
          description: website URL
        domains:
          type: array
          description: domains used by this org
          items:
            $ref: '#/components/schemas/OrgDomain'
        status:
          type: string
          description: current status of organization
          enum:
          - ACTIVE
          - INACTIVE
          - DISABLED
        imagePath:
          type: string
          description: path to full-sized profile image in storage
          pattern: ^[a-zA-Z0-9._/-]+$
        currencies:
          type: array
          description: types of currencies in use, with the first currency the primary currency
          items:
            type: string
          minItems: 1
          maxItems: 100
        locales:
          type: array
          description: locales supported within the org based on user selection, with the first locale the primary locale (e.g., en_US, en_GB, fr_FR, fr_CA)
          items:
            type: string
        dataResidency:
          type: string
          description: data residency of the org - the db cluster where this org's data resides
          enum:
          - GLOBAL
          - US
          - EU
        stock:
          type: string
          description: stock symbol
          example: GOOG
        timezone:
          type: string
          description: timezone in use
          example: America/New_York
        appTimes:
          type: array
          description: approximate times of day in the org timezone for daily app syncs to run (if unset, syncs will run 2am-8am US Eastern Time)
          example: 09:00
          items:
            type: string
        fiscalStart:
          type: integer
          format: int32
          description: number of months into the calendar year that the fiscal year starts (1 = February, 2 = March)
        headJobId:
          type: string
          description: head of the organization
          example: 588f7ee98f138b19220041a7
        unassignedManagerJobId:
          type: string
          description: Job ID that all jobs with missing manager report to in the organization
          example: 588f7ee98f138b19220041a7
        portfolioParentOrgId:
          type: string
          description: portfolio parent org ID
          example: 588f7ee98f138b19220041a7
        startDate:
          type: string
          format: date
          description: start date of history
        options:
          description: org-public options
          $ref: '#/components/schemas/OrgOptions'
        internalOptions:
          description: internal (ChartHop controlled) options
          $ref: '#/components/schemas/InternalOrgOptions'
        onboarding:
          type: boolean
          description: current onboarding status of an organization, allowing clearing of org
        selfServeImporting:
          type: boolean
          description: completion status of initial import for orgs signed up via self serve
        headCount:
          type: integer
          format: int32
          description: number of total headcount currently in the org
        userCount:
          type: integer
          format: int32
          description: number of non-ChartHop, non-app users in the org
        activeUserCount:
          type: integer
          format: int32
          description: number of non-ChartHop, non-app users in the org active in the past month
        activeAt:
          type: string
          description: last timestamp that any user was active in the org
          example: '2017-01-24T13:57:52Z'
        createId:
          type: string
          description: created by user id
          example: 588f7ee98f138b19220041a7
        createBehalfId:
          type: string
          description: created on behalf of user id
          example: 588f7ee98f138b19220041a7
        createAttribution:
          $ref: '#/components/schemas/Attribution'
        createAt:
          type: string
          description: created timestamp
          example: '2017-01-24T13:57:52Z'
        updateId:
          type: string
          description: last updated by user id
          example: 588f7ee98f138b19220041a7
        updateBehalfId:
          type: string
          description: last updated on behalf of user id
          example: 588f7ee98f138b19220041a7
        updateAttribution:
          $ref: '#/components/schemas/Attribution'
        updateAt:
          type: string
          description: last updated timestamp
          example: '2017-01-24T13:57:52Z'
        destroyAt:
          type: string
          description: timestamp that the org is marked for data destruction
          readOnly: true
          example: '2017-01-24T13:57:52Z'
        destroyId:
          type: string
          description: user who marked the org for data destruction
          readOnly: true
          example: 588f7ee98f138b19220041a7
        destroyedAt:
          type: string
          description: date at which this org was destroyed, can not be modified
          readOnly: true
    FormOptions:
      type: object
      properties:
        notifySubmitter:
          type: boolean
        notifySubmitterManager:
          type: boolean
        notifySelf:
          type: boolean
        notifyManager:
          type: boolean
        notifyUserIds:
          type: array
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        fillValues:
          type: boolean
        enableDraft:
          type: boolean
        peersField:
          type: string
        enableExport:
          type: boolean
        timeToEdit:
          type: string
        endDate:
          type: string
    GroupType:
      type: object
      required:
      - id
      - name
      - fieldName
      - membershipType
      - assignmentType
      - parentTypesAllowed
      - enableApprovals
      - defaultSensitivity
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent organization id
          example: 588f7ee98f138b19220041a7
        name:
          type: string
          description: unique name of group
          example: Engineering
          minItems: 1
          maxItems: 80
        fieldName:
          type: string
          description: field name for field representing membership in this type of group
          example: engineering
          pattern: ^[a-zA-Z][a-zA-Z0-9_]+$
        code:
          type: string
          description: external code identifier of the group type
          example: D123
        requirePositions:
          type: boolean
          description: whether the group requires members to be positions
        description:
          type: string
          description: description of the group type
          minItems: 0
          maxItems: 1000
        membershipType:
          type: string
          description: whether members can be in multiple groups or only a single group of this type
          enum:
          - SINGLE
          - MULTIPLE
        assignmentType:
          type: string
          description: whether members are added by manual assignment or by matching a filter expression (or both)
          enum:
          - ASSIGNED
          - EXPR
          - COMBINATION
        parentTypesAllowed:
          type: string
          description: group types allowed for parent groups
          enum:
          - SAME
          - OTHER
          - BOTH
          - NONE
        otherGroupTypeId:
          type: string
          description: if parents can be another group type the ID of that group type
          example: 588f7ee98f138b19220041a7
        sourceGroupTypeId:
          type: string
          description: for a portfolio mirror, the child org group type this type was replicated from
          example: 588f7ee98f138b19220041a7
        enableApprovals:
          type: boolean
          description: whether approvals can be used when changing membership
        hidden:
          type: boolean
          description: when true, hides groups of this type from the Org Chart Groups view and from profile tags; null is treated as visible
        defaultSensitivity:
          type: string
          description: default sensitivity for groups of this type
          enum:
          - GLOBAL
          - ORG
          - SENSITIVE
          - PERSONAL
          - MANAGER
          - HIGH
          - PRIVATE
        positions:
          type: array
          descri

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