Charthop form API

swagger: '2.0'
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access form API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
host: localhost
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: form
paths:
  /v1/org/{orgId}/form:
    get:
      tags:
      - form
      summary: Return all forms in the organization paginated
      operationId: findForms
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: status
        in: query
        description: Status to filter by
        required: false
        type: string
        enum:
        - ACTIVE
        - INACTIVE
        - ARCHIVED
      - name: from
        in: query
        description: Form id to start paginating from
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        type: integer
        format: int32
      - name: returnAccess
        in: query
        description: 'Return access information -- pass a list of actions to check, for example: create,update,delete'
        required: false
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsForm'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
    post:
      tags:
      - form
      summary: Create a form
      operationId: createForm
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: Form data to create
        required: true
        schema:
          $ref: '#/definitions/CreateForm'
      responses:
        '201':
          description: form created
          schema:
            $ref: '#/definitions/Form'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/form/available:
    get:
      tags:
      - form
      summary: Return all active forms applicable to a particular entity
      operationId: getAvailableForms
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: targetId
        in: query
        description: Target id
        required: false
        type: string
      - name: targetType
        in: query
        description: Target type
        required: false
        type: string
        enum:
        - NONE
        - PERSON
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsFormSummary'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/form/delete:
    delete:
      tags:
      - form
      summary: Delete forms
      operationId: deleteForms
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: Form ids
        required: true
        schema:
          type: array
          items:
            type: string
            example: 588f7ee98f138b19220041a7
      responses:
        '204':
          description: forms deleted
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/form/person/{personId}:
    get:
      tags:
      - form
      summary: Return all active forms applicable to a particular person
      operationId: findFormsForPerson
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: personId
        in: path
        description: Person id
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsForm'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/form/status:
    post:
      tags:
      - form
      summary: Update status for existing forms
      operationId: updateFormStatus
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: Form data to update
        required: true
        schema:
          $ref: '#/definitions/FormStatusUpdateRequest'
      responses:
        '200':
          description: form status updated
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/form/{formId}:
    get:
      tags:
      - form
      summary: Return a particular form by id
      operationId: getForm
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Form'
        '400':
          description: bad request
        '404':
          description: not found
    patch:
      tags:
      - form
      summary: Update an existing form
      operationId: updateForm
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id
        required: true
        type: string
      - name: body
        in: body
        description: Form data to update
        required: true
        schema:
          $ref: '#/definitions/UpdateForm'
      responses:
        '204':
          description: form updated
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    delete:
      tags:
      - form
      summary: Delete a form
      operationId: deleteForm
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id
        required: true
        type: string
      responses:
        '204':
          description: form deleted
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    post:
      tags:
      - form
      summary: Submit data from a form
      operationId: legacySubmitForm
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Org id
        required: true
        type: string
      - name: body
        in: body
        description: Form data to submit
        required: true
        schema:
          $ref: '#/definitions/FormSubmitRequest'
      responses:
        '204':
          description: form submitted
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/form/{formId}/collect:
    post:
      tags:
      - form
      summary: Collect data for an existing form, sending emails and chat notifications to people being requested
      operationId: collectFormData
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id
        required: true
        type: string
      - name: body
        in: body
        description: Details on the data collection
        required: false
        schema:
          $ref: '#/definitions/FormCollectRequest'
      responses:
        '201':
          description: form collection started
          schema:
            $ref: '#/definitions/FormCollectionResponse'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/form/{formId}/draft:
    get:
      tags:
      - form
      summary: Get the current state of form draft data
      operationId: getFormDraft
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id
        required: true
        type: string
      - name: personId
        in: query
        description: Person id
        required: false
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/PartialFormDraft'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/form/{formId}/duplicate:
    post:
      tags:
      - form
      summary: Duplicate a form
      operationId: duplicateForm
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id to duplicate
        required: true
        type: string
      - name: body
        in: body
        description: Form duplication options
        required: true
        schema:
          $ref: '#/definitions/DuplicateFormOptions'
      responses:
        '201':
          description: successful operation
          schema:
            $ref: '#/definitions/Form'
        '400':
          description: invalid data
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/form/{formId}/preview-render:
    post:
      tags:
      - form
      summary: Render a preview of a form
      operationId: renderPreviewForm
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id
        required: true
        type: string
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/FormPreviewRenderRequest'
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/FormRender'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/form/{formId}/remind:
    post:
      tags:
      - form
      summary: Sends reminder for a form with existing tasks, sending emails/chat notifications to people being requested
      operationId: remindFormData
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id
        required: true
        type: string
      - name: body
        in: body
        description: Details on the data collection
        required: false
        schema:
          $ref: '#/definitions/FormCollectRequest'
      responses:
        '201':
          description: form reminder started
          schema:
            $ref: '#/definitions/Process'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/form/{formId}/render:
    get:
      tags:
      - form
      summary: Render a form for display
      operationId: renderForm
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id
        required: true
        type: string
      - name: targetId
        in: query
        description: Target id
        required: false
        type: string
      - name: targetType
        in: query
        description: Target type
        required: false
        type: string
        enum:
        - NONE
        - PERSON
      - name: formResponseId
        in: query
        description: Form response id, if editing a prior form response
        required: false
        type: string
      - name: formResponseChangeId
        in: query
        description: Form response change id, if editing a prior form response (deprecated)
        required: false
        type: string
      - name: formVersionId
        in: query
        description: Form version id, if rendering a previous version of the form
        required: false
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/FormRender'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/form/{formId}/rerender/question/{updateQuestionId}:
    post:
      tags:
      - form
      summary: Re-render form blocks based on changes to the form values
      operationId: rerenderForm
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id
        required: true
        type: string
      - name: updateQuestionId
        in: path
        description: The question id that is being updated to trigger the re-render
        required: true
        type: string
      - name: targetId
        in: query
        description: Target id
        required: false
        type: string
      - name: targetType
        in: query
        description: Target type
        required: false
        type: string
        enum:
        - NONE
        - PERSON
      - name: formVersionId
        in: query
        description: Form version id, if rendering a previous version of the form
        required: false
        type: string
      - name: body
        in: body
        description: Form data to submit
        required: true
        schema:
          type: object
          additionalProperties:
            type: object
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/FormRerender'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/form/{formId}/submit:
    post:
      tags:
      - form
      summary: Submit data from a form
      operationId: submitForm
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id
        required: true
        type: string
      - name: targetId
        in: query
        description: Target id
        required: false
        type: string
      - name: targetType
        in: query
        description: Target type
        required: false
        type: string
        enum:
        - NONE
        - PERSON
      - name: body
        in: body
        description: Form data to submit
        required: true
        schema:
          type: object
          additionalProperties:
            type: object
      responses:
        '204':
          description: form submitted
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/form/{formId}/submit/draft:
    post:
      tags:
      - form
      summary: Submit data from a form draft
      operationId: submitFormDraft
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: formId
        in: path
        description: Form id
        required: true
        type: string
      - name: targetId
        in: query
        description: Target id
        required: false
        type: string
      - name: targetType
        in: query
        description: Target type
        required: false
        type: string
        enum:
        - NONE
        - PERSON
      - name: body
        in: body
        description: Form data to submit
        required: true
        schema:
          type: object
          additionalProperties:
            type: object
      responses:
        '201':
          description: form draft submitted
          schema:
            $ref: '#/definitions/FormDraft'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
definitions:
  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
  FormPreviewRenderRequest:
    type: object
    required:
    - form
    - blocks
    properties:
      targetId:
        type: string
        example: 588f7ee98f138b19220041a7
      targetType:
        type: string
        enum:
        - NONE
        - PERSON
      form:
        $ref: '#/definitions/PartialForm'
      blocks:
        type: array
        items:
          $ref: '#/definitions/FormPreviewBlock'
  PartialQuestion:
    type: object
    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: '#/definitions/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: '#/definitions/EnumValue'
      places:
        type: integer
        format: int32
        description: number of decimal places for numeric values
      options:
        description: validation options
        $ref: '#/definitions/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: '#/definitions/Attribution'
      createAt:
        type: string
        description: created timestamp
        example: '2017-01-24T13:57:52Z'
      updateId:
        type: string
        description: last updated by user id
        example: 588f7ee98f138b19220041a7
      updateBehalfId:
        type: string
        description: last updated on behalf of user id
        example: 588f7ee98f138b19220041a7
      updateAttribution:
        $ref: '#/definitions/Attribution'
      updateAt:
        type: string
        description: last updated timestamp
        example: '2017-01-24T13:57:52Z'
      deleteId:
        type: string
        description: deleted by user id
        example: 588f7ee98f138b19220041a7
      deleteBehalfId:
        type: string
        description: deleted on behalf of user id
        example: 588f7ee98f138b19220041a7
      deleteAttribution:
        $ref: '#/definitions/Attribution'
      deleteAt:
        type: string
        description: deleted timestamp
        example: '2017-01-24T13:57:52Z'
  CreateForm:
    type: object
    required:
    - label
    - blocks
    - status
    properties:
      label:
        type: string
        description: human-readable full name of form
        example: 'Health Index: Q2'
        minItems: 1
        maxItems: 255
      displayName:
        type: string
        description: display name of form during completion
        example: Health Index
        minItems: 1
        maxItems: 255
      displayNameTr:
        description: display name of form, translated
        $ref: '#/definitions/Translations'
      description:
        type: string
        description: description of form
        example: The Engineering department, where engineers develop new technology and products.
        minItems: 0
        maxItems: 1000
      blocks:
        type: array
        description: ordered list of blocks being collected in this form
        items:
          $ref: '#/definitions/FormBlock'
      status:
        type: string
        description: status of the form
        enum:
        - ACTIVE
        - INACTIVE
        - ARCHIVED
      type:
        type: string
        description: type of the form
        enum:
        - BUILT_IN
        - CUSTOM
      targetType:
        type: string
        description: target type that the form can be filled out about
        enum:
        - NONE
        - PERSON
      targetFilter:
        type: string
        description: filter that controls on which profiles this tab will appear
      submitFilter:
        type: string
        description: filter that controls which respondents can submit this form. The form:submit permission, if present, overrides this filter
      responseReadFilter:
        type: string
        description: filter that controls who can read the form responses. The formResponse:read permission, if present, overrides this filter
      approval:
        type: string
        description: approval needed, if any approval is required
        enum:
        - MANAGER
        - GRAND_MANAGER
      release:
        type: string
        description: whether a release step is involved (subsequent to approval if any)
        enum:
        - SUBMITTER
        - ADMIN
      releaseMessageChannel:
        description: the message channel to be used for release notifications
        $ref: '#/definitions/MessageChannelConfig'
      share:
        type: string
        description: whether sharing form responses is allowed
        enum:
        - SUBMITTER
        - ADMIN
      shareMessageChannel:
        description: the message channel to be used for sharing notifications
        $ref: '#/definitions/MessageChannelConfig'
      autoShare:
        type: array
        description: list of automatic sharing to be done after submission
        items:
          $ref: '#/definitions/AutoShare'
      autoShareMessageChannel:
        description: the message channel to be used for automatic sharing notifications
        $ref: '#/definitions/MessageChannelConfig'
      submitterEdit:
        description: post-submission editing permissions for the submitter
        $ref: '#/definitions/FormEditAccess'
      approverEdit:
        description: post-submission editing permissions for the approver
        $ref: '#/definitions/FormEditAccess'
      signature:
        description: if the form response should generate a PDF which should be sent for signature, these settings are used
        $ref: '#/definitions/FormSignatureConfig'
      authorSensitive:
        type: string
        description: view sensitivity for the author of this form - the level of view access required to view the createId and updateId fields. If null, the author's identity is always visible as long as the viewer can read the form response. If set to PRIVATE, the author's identity is stored in ChartHop, but protected such that even users with sensitive access cannot access the data. If set to ANONYMOUS, the author's identity is not stored in ChartHop at all.
        enum:
        - ANONYMOUS
        - PRIVATE
        - HIGH
        - MANAGER
      options:
        description: options, such as notification settings
        $ref: '#/definitions/FormOptions'
      completeMode:
        type: string
        description: appearance of the form during completion
        enum:
        - MODAL
        - FULLSCREEN
      ai:
        description: AI form completion and assistance settings
        $ref: '#/definitions/FormAiConfig'
  Translations:
    type: object
    required:
    - values
    properties:
      values:
        type: object
        additionalProperties:
          type: string
  FormRerender:
    type: object
    required:
    - blocks
    - visibleBlockIds
    properties:
      blocks:
        type: array
        items:
          $ref: '#/definitions/FormRenderBlock'
      visibleBlockIds:
        type: array
        items:
          type: string
          example: 588f7ee98f138b19220041a7
  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
  ResultsForm:
    type: object
    required:
    - data
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/Form'
      next:
        type: string
      access:
        type: array
        items:
          $ref: '#/definitions/ResultsAccess'
  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
  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: '#/definitions/Attribution'
      createAt:
        type: string
        description: created timestamp
        example: 

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