Charthop assessment API

openapi: 3.2.0
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop 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…
      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.
      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:
    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
    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'
    FieldOptions:
      type: object
      properties:
        min:
          type: string
          description: minimum value, for numeric and date fields
        max:
          type: string
          description: maximum value, for numeric and date fields
        minItems:
          type: integer
          format: int32
        maxItems:
          type: integer
          format: int32
        stackRank:
          type: boolean
        step:
          type: number
        enableEditDialog:
          type: boolean
        requiredJobField:
          type: boolean
        excludeTargetPersonId:
          type: boolean
        maxLength:
          type: integer
          format: int32
        readOnly:
          type: boolean
        includeFormer:
          type: boolean
        effectiveDated:
          type: boolean
        unique:
          type: boolean
        required:
          type: boolean
    AssessmentTaskSummary:
      type: object
      required:
      - summaryMap
      properties:
        summaryMap:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AssessmentTaskFormSummary'
    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'
    AssessmentTaskFormSummary:
      type: object
      required:
      - submitTaskDoneCount
      - submitTaskPendingCount
      - submitTaskSkippedCount
      - submitTaskExpiredCount
      - formResponseProposedCount
      - formResponseAwaitingChangesCount
      - formResponseUnreleasedCount
      - formResponseRejectedCount
      - formResponseActiveCount
      - formResponseActiveDoneCount
      - formResponseActiveApprovedCount
      - formResponseActiveReleasedCount
      - submitUserCount
      - targetPersonCount
      - uniqueUserCount
      properties:
        submitTaskDoneCount:
          type: integer
          format: int32
          description: Number of FORM_SUBMIT tasks that are marked as DONE
        submitTaskPendingCount:
          type: integer
          format: int32
          description: Number FORM_SUBMIT tasks that are PENDING
        submitTaskSkippedCount:
          type: integer
          format: int32
          description: Number FORM_SUBMIT tasks that are SKIPPED
        submitTaskExpiredCount:
          type: integer
          format: int32
          description: Number FORM_SUBMIT tasks that are EXPIRED
        formResponseProposedCount:
          type: integer
          format: int32
          description: Number of form responses that are proposed and awaiting approval
        formResponseAwaitingChangesCount:
          type: integer
          format: int32
          description: Number of form responses that have had changes requested and are awaiting changes
        formResponseUnreleasedCount:
          type: integer
          format: int32
          description: Number of form responses that are unreleased
        formResponseRejectedCount:
          type: integer
          format: int32
          description: Number of form responses that are rejected
        formResponseActiveCount:
          type: integer
          format: int32
          description: Number of form responses that are active
        formResponseActiveDoneCount:
          type: integer
          format: int32
          description: Number of form responses that are active (but neither released or approved)
        formResponseActiveApprovedCount:
          type: integer
          format: int32
          description: Number of form responses that are active and approved (but weren't released)
        formResponseActiveReleasedCount:
          type: integer
          format: int32
          description: Number of form responses that are active and released
        submitUserCount:
          type: integer
          format: int32
          description: Number of unique submitter users
        targetPersonCount:
          type: integer
          format: int32
          description: Number of unique target persons
        uniqueUserCount:
          type: integer
          format: int32
          description: Number of total users involved, between submitters and targets
    AccessAction:
      type: object
      required:
      - action
      properties:
        action:
          type: string
        fields:
          type: array
          uniqueItems: true
          items:
            type: string
        types:
          type: array
          uniqueItems: true
          items:
            type: string
    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'
    FormEditAccess:
      type: object
      properties:
        allow:
          type: string
          enum:
          - ALWAYS
          - WHILE_PROPOSED
          - UNTIL_ACTIVE
          - WHILE_ASSESSMENT_ACTIVE
          - TIME_LIMIT
        timeLimitSecs:
          type: integer
          format: int64
    BulkFormResponsesOptions:
      type: object
      properties:
        messageChannel:
          $ref: '#/components/schemas/MessageChannelConfig'
    MessageChannelConfig:
      type: object
      required:
      - channels
      - alwaysEmail
      properties:
        channels:
          type: array
          items:
            type: string
            enum:
            - EMAIL
            - CHAT
            - CHAT_SLACK
            - CHAT_TEAMS
        alwaysEmail:
          type: boolean
    CreateAssessment:
      type: object
      required:
      - label
      - type
      properties:
        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'
    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
    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
      

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