Charthop assessment API

openapi: 3.2.0
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access Assessment API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: assessment
paths:
  /v1/org/{orgId}/assessment:
    get:
      tags:
      - assessment
      summary: Return all assessments in the organization paginated
      operationId: findAssessments
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: type
        in: query
        description: Type of assessment to filter by
        required: false
        schema:
          type: string
          enum:
          - REVIEW
          - COMP_REVIEW
          - SURVEY
      - name: from
        in: query
        description: Assessment 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: ids
        in: query
        description: List of ids to filter by
        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/ResultsAssessment'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
    post:
      tags:
      - assessment
      summary: Create a assessment
      operationId: createAssessment
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '201':
          description: assessment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assessment'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAssessment'
        description: Assessment data to create
        required: true
  /v1/org/{orgId}/assessment/bulk/delete:
    post:
      tags:
      - assessment
      summary: Delete a set of assessments
      operationId: bulkDeleteAssessments
      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: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                example: 588f7ee98f138b19220041a7
        description: List of assessment ids to delete
        required: true
  /v1/org/{orgId}/assessment/bulk/duplicate:
    post:
      tags:
      - assessment
      summary: Duplicate a set of assessments
      operationId: bulkDuplicateAssessments
      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: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                example: 588f7ee98f138b19220041a7
        description: List of assessment ids to duplicate
        required: true
  /v1/org/{orgId}/assessment/bulk/move:
    post:
      tags:
      - assessment
      summary: Update the types of a set of assessments
      operationId: bulkChangeAssessmentTypes
      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: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkChangeAssessmentTypesBody'
        description: List of assessment ids to update and the new type
        required: true
  /v1/org/{orgId}/assessment/{assessmentId}:
    get:
      tags:
      - assessment
      summary: Return a particular assessment by id
      operationId: getAssessment
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: assessmentId
        in: path
        description: Assessment id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assessment'
        '400':
          description: bad request
        '404':
          description: not found
    patch:
      tags:
      - assessment
      summary: Update an existing assessment
      operationId: updateAssessment
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: assessmentId
        in: path
        description: Assessment id
        required: true
        schema:
          type: string
      - name: silent
        in: query
        description: Suppress notification emails
        required: true
        schema:
          type: boolean
      responses:
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAssessment'
        description: Assessment data to update
        required: true
    delete:
      tags:
      - assessment
      summary: Delete a assessment
      operationId: deleteAssessment
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: assessmentId
        in: path
        description: Assessment id
        required: true
        schema:
          type: string
      responses:
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/assessment/{assessmentId}/approve:
    post:
      tags:
      - assessment
      summary: Release all un-approved responses for a form of an assessment
      operationId: approveFormResponses
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: assessmentId
        in: path
        description: Assessment id
        required: true
        schema:
          type: string
      - name: formId
        in: query
        description: Form id
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkFormResponsesOptions'
  /v1/org/{orgId}/assessment/{assessmentId}/calibration/person:
    get:
      tags:
      - assessment
      summary: Retrieve all persons who were targets of form submissions, retrieving both fields as well as question responses. This endpoint is typically used for calibrations.
      operationId: findCalibrationPersons
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: assessmentId
        in: path
        description: Assessment id
        required: true
        schema:
          type: string
      - name: filter
        in: query
        description: Filter to apply
        required: false
        schema:
          type: string
      - name: fields
        in: query
        description: Fields to retrieve
        required: false
        schema:
          type: string
      - name: questionIds
        in: query
        description: Question ids to retrieve
        required: false
        schema:
          type: string
      - name: date
        in: query
        description: Date to search as of
        required: false
        schema:
          type: string
          format: date
      - 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: splitColumns
        in: query
        description: Whether to split complex columns, used for tabular data formats
        required: false
        schema:
          type: boolean
      responses:
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/assessment/{assessmentId}/complete:
    post:
      tags:
      - assessment
      summary: Complete a assessment
      operationId: completeAssessment
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: assessmentId
        in: path
        description: Assessment id
        required: true
        schema:
          type: string
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assessment'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/assessment/{assessmentId}/form/{formId}/expire:
    post:
      tags:
      - assessment
      summary: Expire all pending tasks for a form of an assessment
      operationId: expireAssessmentFormTasks
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: assessmentId
        in: path
        description: Assessment id
        required: true
        schema:
          type: string
      - name: formId
        in: path
        description: Form id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/assessment/{assessmentId}/forms-questions:
    get:
      tags:
      - assessment
      summary: Return an overview of the forms and questions used in the assessment. If the user has read access to the assessment, then the forms and questions are visible, even if they would not otherwise be visible on their own
      operationId: getAssessmentFormsAndQuestions
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: assessmentId
        in: path
        description: Assessment id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssessmentFormsAndQuestions'
        '400':
          description: bad request
        '404':
          description: not found
  /v1/org/{orgId}/assessment/{assessmentId}/reactivate:
    post:
      tags:
      - assessment
      summary: Reactivate a assessment
      operationId: reactivateAssessment
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: assessmentId
        in: path
        description: Assessment id
        required: true
        schema:
          type: string
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assessment'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/assessment/{assessmentId}/release:
    post:
      tags:
      - assessment
      summary: Release all un-released responses for a form of an assessment
      operationId: releaseFormResponses
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: assessmentId
        in: path
        description: Assessment id
        required: true
        schema:
          type: string
      - name: formId
        in: query
        description: Form id
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkFormResponsesOptions'
  /v1/org/{orgId}/assessment/{assessmentId}/task-summary:
    get:
      tags:
      - assessment
      summary: Return a summary of the tasks for a given assessment
      operationId: getAssessmentTaskSummary
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: assessmentId
        in: path
        description: Assessment id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssessmentTaskSummary'
        '401':
          description: unauthorized
components:
  schemas:
    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'
    BulkFormResponsesOptions:
      type: object
      properties:
        messageChannel:
          $ref: '#/components/schemas/MessageChannelConfig'
    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
    Assessment:
      type: object
      required:
      - id
      - orgId
      - label
      - slug
      - type
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent organization id
          example: 588f7ee98f138b19220041a7
        label:
          type: string
          description: human-readable label of assessment
          example: Engineering Budget Q2 2019
          minItems: 1
          maxItems: 255
        slug:
          type: string
          description: unique slug of assessment
          example: engineering-budget-q2-2019
          minItems: 1
          maxItems: 40
        type:
          type: string
          description: type of assessment
          enum:
          - REVIEW
          - COMP_REVIEW
          - SURVEY
        fields:
          type: object
          description: assessment fields (description)
          additionalProperties:
            type: object
        shareAccess:
          type: array
          description: users who have been granted access to this assessment
          items:
            $ref: '#/components/schemas/ShareAccess'
        sensitive:
          type: string
          description: view sensitivity of this assessment
          enum:
          - GLOBAL
          - ORG
          - SENSITIVE
          - PERSONAL
          - MANAGER
          - HIGH
          - PRIVATE
        color:
          type: string
          description: color of assessment
          pattern: ^#[a-f0-9]{6}$
        startDate:
          type: string
          format: date
          description: Date this assessment begins. In the context of REVIEW goals, the date the review cycle begins.
        endDate:
          type: string
          format: date
          description: Date this assessment ends, or is completed. In the context of REVIEW assessment, the date the review cycle ends.
        status:
          type: string
          description: status of this assessment - DRAFT, ACTIVE, DONE
          enum:
          - DRAFT
          - ACTIVE
          - DONE
        doneAt:
          type: string
          description: timestamp when the status of this assessment was set to done
          example: '2017-01-24T13:57:52Z'
        taskCount:
          type: integer
          format: int32
          description: number of tasks associated with this assessment
          example: '12'
        taskDoneCount:
          type: integer
          format: int32
          description: number of tasks associated with this assessment that are done
          example: '3'
        peopleIncludedCount:
          type: integer
          format: int32
          description: number of people included in this assessment
          example: '12'
        query:
          type: string
          description: Query for which people/jobs can be included in the review.
        showDatesInCalendar:
          type: boolean
          description: True if user wants dates to show on company calendar
          example: 'true'
        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'
    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
    FormEditAccess:
      type: object
      properties:
        allow:
          type: string
          enum:
          - ALWAYS
          - WHILE_PROPOSED
          - UNTIL_ACTIVE
          - WHILE_ASSESSMENT_ACTIVE
          - TIME_LIMIT
        timeLimitSecs:
          type: integer
          format: int64
    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'
    AutoShare:
      type: object
      required:
      - access
      - shareWith
      properties:
        access:
          type: string
          enum:
          - NONE
          - LIMITED_READ
          - LIMITED_WRITE
          - STANDARD_READ
          - STANDARD_WRITE
          - COMPENSATION_READ
          - FULL_READ
          - COMP_PLANNING_PARTICIPANT
          - COMPENSATION_WRITE
          - WRITE
          - COMPENSATION_OWNER
          - OWNER
        shareWith:
          type: string
    MessageChannelConfig:
      type: object
      required:
      - channels
      - alwaysEmail
      properties:
        channels:
          type: array
          items:
            type: string
            enum:
            - EMAIL
            - CHAT
            - CHAT_SLACK
            - CHAT_TEAMS
        alwaysEmail:
          type: boolean
    AssessmentFormsAndQuestions:
      type: object
      required:
      - forms
      - questions
      properties:
        forms:
          type: array
          items:
            $ref: '#/components/schemas/Form'
        questions:
          type: array
          items:
            $ref: '#/components/schemas/Question'
    DueDate:
      type: object
      required:
      - type
      - dueDay
      - dueTime
      properties:
        type:
          type: string
          enum:
          - EXACT
          - RELATIVE
        dueDay:
          type: string
          description: due day, in either relative (-7d) or exact (YYYY-MM-DD) format
        dueTime:
          type: string
          description: due time, which is a LocalTime
    FormAiConfig:
      type: object
      required:
      - enableRead
      - enableWrite
      properties:
        enableRead:
          type: boolean
        enableWrite:
          type: boolean
        agentUserId:
          type: string
          example: 588f7ee98f138b19220041a7
        instructions:
          type: string
        label:
          type: string
        agentSubmit:
          type: string
          description: 'whether AI agents are allowed to submit this form: null/absent (never), CHAT (only when in an interactive chat with a human), AUTO (also when running autonomously). Defaults to never.'
          enum:
          - CHAT
          - AUTO
    FormSignatureConfig:
      type: object
      required:
      - signers
      properties:
        signers:
          type: array
          items:
            type: string
        messageChannel:
          $ref: '#/components/schemas/MessageChannelConfig'
        message:
          type: string
        dueDate:
          $ref: '#/components/schemas/DueDate'
        isSkippable:
          type: boolean
        fieldId:
          type: string
          example: 588f7ee98f138b19220041a7
    Question:
      type: object
      required:
      - id
      - question
      - type
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent organization id (empty if global)
          example: 588f7ee98f138b19220041a7
        question:
          type: string
          description: text of the question
          example: What is your favorite color?
        questionTr:
          description: translations for the question text
          $ref: '#/components/schemas/Translations'
        fieldId:
          type: string
          description: if the question is linked to a field, the id of that field. Any question responses will be automatically saved to the field
          example: 588f7ee98f138b19220041a7
        type:
          type: string
          description: datatype of the question
          enum:
          - ADDRESS
          - AUDIO
          - BOOLEAN
          - COMP
          - COMPOUND
          - COMP_BAND
          - CONTACTS
          - CURRENCY
          - DATE
          - DECIMAL
          - ELAPSED_DAYS
          - ELAPSED_MONTHS
          - ELAPSED_YEARS
          - EMAIL
          - ENUM
          - ENUM_EXPR
          - ENUM_MULTI
          - ENUM_SCALE
          - EXPR
          - FILE
          - GROUP
          - GROUPS
          - GROUP_ASSIGNMENTS
          - GROUP_TYPE
          - GROUP_POSITION_ASSIGNMENTS
          - IMAGE
          - INTEGER
          - JOB
          - JOB_CODE
          - JOBS
          - JOB_TIER
          - LIST
          - MAP
          - MONEY
          - NAME
          - OBJECT
          - PAY_INTERVAL
          - PERCENT
          - PERSON
          - PERSONS
          - PHONE
          - STOCKGRANT
          - STRING
          - TABLE_REF
          - TEXT
          - TIMEOFF
          - TIMESTAMP
          - TRACKED_GROUP
          - URL
          - USER
          - VARIABLE_COMP
          - VARIABLE_COMPS
        plural:
          type: string
          description: plural type of the question datatype (either SINGLE, LIST, or SET)
          enum:
          - SINGLE
          - LIST
          - SET
        values:
          type: array
          description: possible values (enum type only)
          items:
            $ref: '#/components/schemas/EnumValue'
        places:
          type: integer
          format: int32
          description: number of decimal places for numeric values
        options:
          description: validation options
          $ref: '#/components/schemas/FieldOptions'
        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'
    Process:
      type: object
      required:
      - id
      - orgId
      - label
      - type
      - status
      - runUserId
      - createId
      - createAt
      - options
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent org id
          example: 588f7ee98f138b19220041a7
        label:
          type: string
          description: human-readable label that identifies this process
        type:
          type: string
      

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