Charthop form-response API

openapi: 3.2.0
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access Form Response API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: form-response
paths:
  /v1/org/{orgId}/form-response:
    get:
      tags:
      - form-response
      summary: Return form responses by form
      operationId: findFormResponses
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formId
        in: query
        description: Form id to filter by
        required: false
        schema:
          type: string
      - name: assessmentId
        in: query
        description: Assessment id to filter by
        required: false
        schema:
          type: string
      - name: submitPersonId
        in: query
        description: Person id to filter by (person who submitted the form)
        required: false
        schema:
          type: string
      - name: targetId
        in: query
        description: Target id to filter by
        required: false
        schema:
          type: string
      - name: submitPersonFilter
        in: query
        description: Filter to apply on the submitter
        required: false
        schema:
          type: string
      - name: targetFilter
        in: query
        description: Filter to apply on the target
        required: false
        schema:
          type: string
      - name: fromId
        in: query
        description: FormResponse id to start paginating from
        required: false
        schema:
          type: string
      - name: fromSubmitAt
        in: query
        description: Submit timestamp to start from (inclusive)
        required: false
        schema:
          type: string
      - name: untilSubmitAt
        in: query
        description: Submit timestamp to go until (exclusive)
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: desc
        in: query
        description: Whether to return results sorted in descending timestamp order
        required: false
        schema:
          type: boolean
      - 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
      - name: returnFormVersions
        in: query
        description: Return form versions (question ids / text) alongside the responses
        required: false
        schema:
          type: boolean
      - name: format
        in: query
        description: Data format to use; default is json, can also use json-extended or json-readable
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsWithFormVersions'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/form-response/count:
    get:
      tags:
      - form-response
      summary: Return the total count of form responses
      operationId: getFormResponseCount
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formId
        in: query
        description: Form id to filter by
        required: false
        schema:
          type: string
      - name: assessmentId
        in: query
        description: Assessment id to filter by
        required: false
        schema:
          type: string
      - name: submitPersonFilter
        in: query
        description: Filter to apply on the submitter
        required: false
        schema:
          type: string
      - name: targetFilter
        in: query
        description: Filter to apply on the target
        required: false
        schema:
          type: string
      - name: fromSubmitAt
        in: query
        description: Submit timestamp to start from (inclusive)
        required: false
        schema:
          type: string
      - name: untilSubmitAt
        in: query
        description: Submit timestamp to go until (exclusive)
        required: false
        schema:
          type: string
      - name: questionId
        in: query
        description: Question id to filter by
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormResponseCount'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/form-response/export:
    post:
      tags:
      - form-response
      summary: Export form responses
      operationId: exportFormResponses
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormResponsesExportOptions'
        required: true
  /v1/org/{orgId}/form-response/import:
    post:
      tags:
      - form-response
      summary: Import form response data from CSV file
      operationId: importCsv
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formId
        in: query
        description: Form id to update
        required: false
        schema:
          type: string
      - name: skipErrors
        in: query
        description: Whether to skip erroneous rows, or reject the entire upload if any are invalid (default)
        required: true
        schema:
          type: boolean
      - name: createEnumValues
        in: query
        description: Whether to create enum values on the fly on questions if they don't previously exist
        required: true
        schema:
          type: boolean
      - name: importFromProcessId
        in: query
        description: Import a file from another process, instead of directly uploading it
        required: false
        schema:
          type: string
      - name: parentProcessId
        in: query
        description: Parent process id to attach to
        required: false
        schema:
          type: string
      responses:
        '200':
          description: import started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: bad request
        '401':
          description: not authorized
        '403':
          description: permission denied
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
  /v1/org/{orgId}/form-response/import/download-template:
    get:
      tags:
      - form-response
      summary: Download a CSV template for a form import
      operationId: downloadImportCsvTemplate
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formId
        in: query
        description: Form id
        required: false
        schema:
          type: string
      responses:
        '200':
          description: success
        '400':
          description: bad request
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/form-response/{formResponseId}:
    get:
      tags:
      - form-response
      summary: Return a particular form response by id
      operationId: getFormResponse
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formResponseId
        in: path
        description: FormResponse id
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: Data format to use for answers; default is json, can also use json-extended or json-readable
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormResponse'
        '400':
          description: bad request
        '404':
          description: not found
    patch:
      tags:
      - form-response
      summary: Update an existing form response's metadata, such as shareAccess information
      operationId: updateFormResponse
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formResponseId
        in: path
        description: FormResponse id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: successful operation
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFormResponse'
        description: FormResponse data to update
        required: true
    post:
      tags:
      - form-response
      summary: Update an existing form response's answers without re-submitting
      operationId: updateFormResponseAnswers
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formResponseId
        in: path
        description: FormResponse id
        required: true
        schema:
          type: string
      - name: submit
        in: query
        description: If true, will re-submit the form response
        required: false
        schema:
          type: boolean
      responses:
        '204':
          description: successful operation
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: object
        description: FormResponse data to update
        required: true
    delete:
      tags:
      - form-response
      summary: Delete a form response
      operationId: deleteFormResponse
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formResponseId
        in: path
        description: FormResponse id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: successful operation
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/form-response/{formResponseId}/approve:
    post:
      tags:
      - form-response
      summary: Approve a form response
      operationId: approveFormResponse
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formResponseId
        in: path
        description: Form response id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: successful operation
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormResponseApproval'
        description: Approval details
  /v1/org/{orgId}/form-response/{formResponseId}/export:
    get:
      tags:
      - form-response
      summary: Export a particular form response as a PDF document
      operationId: exportFormResponse
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formResponseId
        in: path
        description: Form response id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: bad request
        '404':
          description: not found
  /v1/org/{orgId}/form-response/{formResponseId}/reject:
    post:
      tags:
      - form-response
      summary: Reject a form response
      operationId: rejectFormResponse
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formResponseId
        in: path
        description: Form response id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: successful operation
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormResponseApproval'
        description: Approval details
  /v1/org/{orgId}/form-response/{formResponseId}/release:
    post:
      tags:
      - form-response
      summary: Release a form response
      operationId: releaseFormResponse
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formResponseId
        in: path
        description: Form response id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: successful operation
        '400':
          description: bad request
        '404':
          description: not found
  /v1/org/{orgId}/form-response/{formResponseId}/request-changes:
    post:
      tags:
      - form-response
      summary: Request changes for a form response
      operationId: requestChangesOnFormResponse
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: formResponseId
        in: path
        description: Form response id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: successful operation
        '400':
          description: bad request
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormResponseApproval'
        description: Approval details
components:
  schemas:
    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
    LogData:
      type: object
      required:
      - level
      - at
      - data
      properties:
        level:
          type: string
          enum:
          - INFO
          - WARN
          - ERROR
        at:
          type: string
          description: created timestamp
          example: '2017-01-24T13:57:52Z'
        message:
          type: string
        data:
          type: object
          additionalProperties:
            type: object
    FormVersionInfo:
      type: object
      required:
      - id
      - label
      - displayName
      - questions
      properties:
        id:
          type: string
          example: 588f7ee98f138b19220041a7
        label:
          type: string
        displayName:
          type: string
        displayNameTr:
          $ref: '#/components/schemas/Translations'
        questions:
          type: array
          items:
            $ref: '#/components/schemas/FormQuestionInfo'
    FormResponse:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent organization id
          example: 588f7ee98f138b19220041a7
        externalId:
          type: string
          description: if the response was imported from an external system, the unique identifier of the response from that system
          example: google:1234567890
        formId:
          type: string
          description: form id that the response is a response for
          example: 588f7ee98f138b19220041a7
        formVersionId:
          type: string
          description: form version id that the response is a response for
          example: 588f7ee98f138b19220041a7
        submitPersonId:
          type: string
          description: person id who filled out the form response (null if anonymous)
          example: 588f7ee98f138b19220041a7
        submitUserId:
          type: string
          description: user id who filled out the form response (can be null if anonymous or imported data)
          example: 588f7ee98f138b19220041a7
        submitAttribution:
          description: attribution information, if an agent completed the form on behalf of a principal
          $ref: '#/components/schemas/Attribution'
        changeId:
          type: string
          description: change id, if the form response is linked to a DATA change
          example: 588f7ee98f138b19220041a7
        assessmentId:
          type: string
          description: assessment id, if the form response is related to an assesment
          example: 588f7ee98f138b19220041a7
        createProcessId:
          type: string
          description: process id, if the form response was created from an import process
          example: 588f7ee98f138b19220041a7
        updateProcessId:
          type: string
          description: process id, if the form response was updated from an import process
          example: 588f7ee98f138b19220041a7
        shareAccess:
          type: array
          description: list of share access, if the form response has been shared with anyone
          items:
            $ref: '#/components/schemas/ShareAccess'
        authorSensitive:
          type: string
          description: sensitivity level of the author of the form response, if it differs from the form response
          enum:
          - ANONYMOUS
          - PRIVATE
          - HIGH
          - MANAGER
        authorData:
          type: object
          description: demographic field data connected with the author of the form response
          additionalProperties:
            type: object
        targetEntityId:
          type: string
          description: target entity id -- the entity that the form response is about
          example: 588f7ee98f138b19220041a7
        targetEntityType:
          type: string
          description: target entity type -- the entity that the form response is about
          enum:
          - NONE
          - PERSON
        answers:
          type: array
          description: list of answers in the form response
          items:
            $ref: '#/components/schemas/FormResponseAnswer'
        submitAt:
          type: string
          description: timestamp that the form response was submitted
        approvalAt:
          type: string
          description: timestamp that the form response was approved
        approvalId:
          type: string
          description: user id who approved the form response
          example: 588f7ee98f138b19220041a7
        approvalNote:
          type: string
          description: note left by the user who approved -- this is for backwards compatibility with the old approval system
        releaseAt:
          type: string
          description: timestamp that the form response was released
        releaseId:
          type: string
          description: user id who released the form response
          example: 588f7ee98f138b19220041a7
        fileId:
          type: string
          description: if the form response was exported into a file for signature, the id of that file
          example: 588f7ee98f138b19220041a7
        signAt:
          type: string
          description: timestamp that the form response's associated file was fully signed
        signerUserIds:
          type: array
          description: user ids who signed the form response, if it was signed
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        status:
          type: string
          description: status of form response
          enum:
          - ACTIVE
          - PROPOSED
          - REJECTED
          - AWAITING_CHANGES
          - UNRELEASED
        commentCount:
          type: integer
          format: int32
          description: number of comments
        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'
    FormResponseAnswer:
      type: object
      required:
      - id
      - questionId
      properties:
        id:
          type: string
          example: 588f7ee98f138b19220041a7
        questionId:
          type: string
          example: 588f7ee98f138b19220041a7
        value:
          type: object
        type:
          type: string
          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
          enum:
          - SINGLE
          - LIST
          - SET
    FormResponseCount:
      type: object
      required:
      - totalCount
      - filteredCount
      properties:
        totalCount:
          type: integer
          format: int32
        filteredCount:
          type: integer
          format: int32
    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'
    Translations:
      type: object
      required:
      - values
      properties:
        values:
          type: object
          additionalProperties:
            type: string
    FormQuestionInfo:
      type: object
      required:
      - id
      - question
      properties:
        id:
          type: string
          example: 588f7ee98f138b19220041a7
        question:
          type: string
        questionTr:
          $ref: '#/components/schemas/Translations'
    ResultsWithFormVersions:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FormResponse'
        next:
          type: string
          example: 588f7ee98f138b19220041a7
        access:
          type: array
          items:
            $ref: '#/components/schemas/ResultsAccess'
        formVersions:
          type: array
          items:
            $ref: '#/components/schemas/FormVersionInfo'
    UpdateFormResponse:
      type: object
      properties:
        shareAccess:
          type: array
          description: list of share access, if the form response has been shared with anyone
          items:
            $ref: '#/components/schemas/ShareAccess'
    FormResponseApproval:
      type: object
      properties:
        message:
          type: string
    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
    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
          description: process type
        status:
          type: string
          description: current status of process
          enum:
          - PENDING
          - RUNNING
          - DONE
          - ERROR
        filePath:
          type: string
          description: data file path
        logPath:
          type: string
          description: data log path
        runUserId:
          type: string
          description: user id who is running the process
          example: 588f7ee98f138b19220041a7
        parentProcessId:
          type: string
          description: process id of parent process
          example: 588f7ee98f138b19220041a7
        createId:
          type: string
          description: created by user id (user who requested the process run)
          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'
        startAt:
          type: string
          description: started at timestamp
          example: '2017-01-24T13:57:52Z'
        endAt:
          type: string
          description: ended at timestamp
          example: '2017-01-24T13:57:52Z'
        message:
          type: string
          description: status or error message
        progress:
          type: number
          format: double
          description: percent progress so far
        internalError:
          type: string
          description: internal-only error message
        options:
          type: object
          description: options passed to the process
        results:
          type: object
          description: results summary for the process
          additionalProperties:
            type: object
        logDataList:
          type: array
          description: list of log data that occurred during running of this process
          items:
            $ref: '#/components/schemas/LogData'
        state:
          type: object
          description: process-specific state data
        summary:
          type: string
          description: human-readable, searchable summary of what this process did
        appId:
          type: string
          description: app id of the process
          example: 588f7ee98f1

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