swagger: '2.0'
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access org-config API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
host: localhost
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: org-config
paths:
  /v1/org/{orgId}/config:
    get:
      tags:
      - org-config
      summary: Return config for a given org
      operationId: getOrgConfig
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/OrgConfig'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: internal server error
    post:
      tags:
      - org-config
      summary: Create an org config if it doesn't exist
      operationId: createOrgConfig
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: Org config to create
        required: true
        schema:
          $ref: '#/definitions/CreateOrgConfig'
      responses:
        '201':
          description: successful operation
          schema:
            $ref: '#/definitions/OrgConfig'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: internal server error
    patch:
      tags:
      - org-config
      summary: Update an existing org config
      operationId: updateOrgConfig
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: Sort data to update
        required: true
        schema:
          $ref: '#/definitions/UpdateOrgConfig'
      responses:
        '204':
          description: successful operation
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: internal server error
definitions:
  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
  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: '#/definitions/BuiltInCategoryMap'
      builtinFieldConfig:
        type: array
        description: Org configuration for built-in fields
        uniqueItems: true
        items:
          $ref: '#/definitions/BuiltInFieldConfig'
      compensationBandsConfig:
        description: Org configuration for compensation bands tiers, multipliers, and job levels
        $ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/Attribution'
      deleteAt:
        type: string
        description: deleted timestamp
        example: '2017-01-24T13:57:52Z'
      grantConfiguration:
        type: array
        description: Org Grant Configuration
        uniqueItems: true
        items:
          $ref: '#/definitions/GrantAlias'
  StartingSalaryConfig:
    type: object
    required:
    - type
    - effectiveDate
    properties:
      type:
        type: string
        description: Starting salary calculation type
        enum:
        - BAND_MINIMUM
        - BAND_QUARTER
        - BAND_MIDPOINT
        - CUSTOM_PERCENTILE
      customPercentile:
        type: integer
        format: int32
        description: Custom percentile value (0-100) when type is CUSTOM_PERCENTILE
      effectiveDate:
        type: string
        format: date
        description: Effective date for this configuration
      includeEquityTarget:
        type: boolean
        description: Whether to include equity target in starting compensation
      includeVariableComp:
        type: boolean
        description: Whether to include variable compensation in starting compensation
  CompensationBandsConfig:
    type: object
    required:
    - annualizedSalaries
    - hourlySalaries
    - hoursPerWeek
    - weeksPerYear
    - hasTargetSalary
    - hasLocationMultiplier
    - currencyRounding
    properties:
      annualizedSalaries:
        type: boolean
        description: whether annualized salaries are used
      annualizedSalariesType:
        type: string
        description: how annualized salaries are represented
      hourlySalaries:
        type: boolean
        description: whether hourly salaries are used
      hourlySalariesType:
        type: string
        description: how hourly salaries are represented
      hoursPerWeek:
        type: number
        description: how many hours per week to use when calculating comp bands
      weeksPerYear:
        type: number
        description: how many weeks per year to use when calculating comp bands
      hasTargetSalary:
        type: boolean
        description: target salary within a comp band
      targetSalaryType:
        type: string
        description: how target salaries are represented
      equityFormat:
        type: string
        description: equity format
      refreshEquityFormat:
        type: string
        description: refresh grant equity format
      variableBonusFormat:
        type: string
        description: variable bonus format
      tiersNotMappedToCodes:
        type: boolean
        description: whether or not the tiers are mapped to fields. after we migrate all the tiers to be mapped, this flag can be removed
      firstTier:
        type: string
        description: the org's first tier for their comp bands
      secondTier:
        type: string
        description: the org's second tier for their comp bands
      thirdTier:
        type: string
        description: the org's third tier for their comp bands
      hasLocationMultiplier:
        type: boolean
        description: whether the org's location data is used as multipliers
      jobLevelSource:
        type: string
        description: the source for the band job levels
      marketJobLevelSystem:
        type: string
        description: comparable market job level system
      currencyRounding:
        type: array
        description: currency rounding settings in the UI
        uniqueItems: true
        items:
          $ref: '#/definitions/Money'
      hasMigratedBands:
        type: boolean
        description: has migrated V1 bands
      startingSalaryConfig:
        description: Starting salary configuration for all comp bands in the org
        $ref: '#/definitions/StartingSalaryConfig'
  UpdateOrgConfig:
    type: object
    properties:
      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: '#/definitions/BuiltInCategoryMap'
      builtinFieldConfig:
        type: array
        description: Org configuration for built-in fields
        uniqueItems: true
        items:
          $ref: '#/definitions/BuiltInFieldConfig'
      compensationBandsConfig:
        description: Org configuration for compensation bands tiers, multipliers, and job levels
        $ref: '#/definitions/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: '#/definitions/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
      grantConfiguration:
        type: array
        description: Org Grant Configuration
        uniqueItems: true
        items:
          $ref: '#/definitions/GrantAlias'
  GrantAlias:
    type: object
    required:
    - grantType
    - enabled
    properties:
      alias:
        type: string
      grantType:
        type: string
        enum:
        - ISO
        - NSO
        - RSU
        - SAR
        - PERFORMANCE_SHARES
        - PHANTOM_STOCK
        - RSA
      enabled:
        type: boolean
  SmartCurrencyOption:
    type: object
    required:
    - name
    - enabled
    properties:
      name:
        type: string
        description: codename for the option
        enum:
        - PERSON_HOME_ADDRESS_COUNTRY
        - JOB_LOCATION_COUNTRY
        - JOB_CURRENCY
      enabled:
        type: boolean
        description: determines if this option should be used
  Attribution:
    type: object
    properties:
      principalUserId:
        type: string
        example: 588f7ee98f138b19220041a7
      agentUserIds:
        type: array
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      eventId:
        type: string
        example: 588f7ee98f138b19220041a7
      aiChatId:
        type: string
        example: 588f7ee98f138b19220041a7
      aiToolUseId:
        type: string
      channel:
        type: string
        enum:
        - WEB
        - MOBILE
        - SLACK
        - TEAMS
        - MCP
  CreateOrgConfig:
    type: object
    required:
    - orgId
    properties:
      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: '#/definitions/BuiltInCategoryMap'
      builtinFieldConfig:
        type: array
        description: Org configuration for built-in fields
        uniqueItems: true
        items:
          $ref: '#/definitions/BuiltInFieldConfig'
      compensationBandsConfig:
        description: Org configuration for compensation bands tiers, multipliers, and job levels
        $ref: '#/definitions/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: '#/definitions/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
      grantConfiguration:
        type: array
        description: Org Grant Configuration
        uniqueItems: true
        items:
          $ref: '#/definitions/GrantAlias'
  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