swagger: '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 host: localhost schemes: - https - http consumes: - application/json produces: - application/json tags: - name: form-response paths: /v1/org/{orgId}/form-response: get: tags: - form-response summary: Return form responses by form operationId: findFormResponses 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: query description: Form id to filter by required: false type: string - name: assessmentId in: query description: Assessment id to filter by required: false type: string - name: submitPersonId in: query description: Person id to filter by (person who submitted the form) required: false type: string - name: targetId in: query description: Target id to filter by required: false type: string - name: submitPersonFilter in: query description: Filter to apply on the submitter required: false type: string - name: targetFilter in: query description: Filter to apply on the target required: false type: string - name: fromId in: query description: FormResponse id to start paginating from required: false type: string - name: fromSubmitAt in: query description: Submit timestamp to start from (inclusive) required: false type: string - name: untilSubmitAt in: query description: Submit timestamp to go until (exclusive) required: false type: string - name: limit in: query description: Number of results to return required: false type: integer format: int32 - name: desc in: query description: Whether to return results sorted in descending timestamp order required: false type: boolean - name: returnAccess in: query description: 'Return access information -- pass a list of actions to check, for example: create,update,delete' required: false type: string - name: returnFormVersions in: query description: Return form versions (question ids / text) alongside the responses required: false type: boolean - name: format in: query description: Data format to use; default is json, can also use json-extended or json-readable required: false type: string responses: '200': description: successful operation schema: $ref: '#/definitions/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 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: query description: Form id to filter by required: false type: string - name: assessmentId in: query description: Assessment id to filter by required: false type: string - name: submitPersonFilter in: query description: Filter to apply on the submitter required: false type: string - name: targetFilter in: query description: Filter to apply on the target required: false type: string - name: fromSubmitAt in: query description: Submit timestamp to start from (inclusive) required: false type: string - name: untilSubmitAt in: query description: Submit timestamp to go until (exclusive) required: false type: string - name: questionId in: query description: Question id to filter by required: false type: string responses: '200': description: successful operation schema: $ref: '#/definitions/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 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 required: true schema: $ref: '#/definitions/FormResponsesExportOptions' responses: '200': description: successful operation schema: $ref: '#/definitions/Process' '400': description: bad request '401': description: not authorized '404': description: not found /v1/org/{orgId}/form-response/import: post: tags: - form-response summary: Import form response data from CSV file operationId: importCsv consumes: - multipart/form-data produces: - application/json parameters: - name: file in: formData required: false type: file - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: formId in: query description: Form id to update required: false type: string - name: skipErrors in: query description: Whether to skip erroneous rows, or reject the entire upload if any are invalid (default) required: true 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 type: boolean - name: importFromProcessId in: query description: Import a file from another process, instead of directly uploading it required: false type: string - name: parentProcessId in: query description: Parent process id to attach to required: false type: string responses: '200': description: import started schema: $ref: '#/definitions/Process' '400': description: bad request '401': description: not authorized '403': description: permission denied /v1/org/{orgId}/form-response/import/download-template: get: tags: - form-response summary: Download a CSV template for a form import operationId: downloadImportCsvTemplate 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: query description: Form id required: false 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 consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: formResponseId in: path description: FormResponse id required: true 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 type: string responses: '200': description: successful operation schema: $ref: '#/definitions/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 consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: formResponseId in: path description: FormResponse id required: true type: string - name: body in: body description: FormResponse data to update required: true schema: $ref: '#/definitions/UpdateFormResponse' responses: '204': description: successful operation '400': description: invalid data '401': description: not authorized '403': description: permission denied '404': description: not found post: tags: - form-response summary: Update an existing form response's answers without re-submitting operationId: updateFormResponseAnswers consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: formResponseId in: path description: FormResponse id required: true type: string - name: submit in: query description: If true, will re-submit the form response required: false type: boolean - name: body in: body description: FormResponse data to update required: true schema: type: object additionalProperties: type: object responses: '204': description: successful operation '400': description: invalid data '401': description: not authorized '403': description: permission denied '404': description: not found delete: tags: - form-response summary: Delete a form response operationId: deleteFormResponse consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: formResponseId in: path description: FormResponse id required: true 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 consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: formResponseId in: path description: Form response id required: true type: string - name: body in: body description: Approval details required: false schema: $ref: '#/definitions/FormResponseApproval' responses: '204': description: successful operation '400': description: bad request '404': description: not found /v1/org/{orgId}/form-response/{formResponseId}/export: get: tags: - form-response summary: Export a particular form response as a PDF document operationId: exportFormResponse consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: formResponseId in: path description: Form response id required: true type: string responses: '200': description: successful operation schema: $ref: '#/definitions/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 consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: formResponseId in: path description: Form response id required: true type: string - name: body in: body description: Approval details required: false schema: $ref: '#/definitions/FormResponseApproval' responses: '204': description: successful operation '400': description: bad request '404': description: not found /v1/org/{orgId}/form-response/{formResponseId}/release: post: tags: - form-response summary: Release a form response operationId: releaseFormResponse consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: formResponseId in: path description: Form response id required: true 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 consumes: - application/json produces: - application/json parameters: - name: orgId in: path description: Org identifier (either id or slug) required: true type: string - name: formResponseId in: path description: Form response id required: true type: string - name: body in: body description: Approval details required: false schema: $ref: '#/definitions/FormResponseApproval' responses: '204': description: successful operation '400': description: bad request '404': description: not found definitions: 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: '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' 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: '#/definitions/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: 588f7ee98f138b19220041a7 uuid: type: string description: unique ID of the process at queue time example: 84db3c6e-0877-4436-8af1-768c06b29586 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 ResultsAccess: type: object required: - allowed properties: ids: type: array uniqueItems: true items: type: string example: 588f7ee98f138b19220041a7 allowed: type: array uniqueItems: true items: $ref: '#/definitions/AccessAction' FormResponseCount: type: object required: - totalCount - filteredCount properties: totalCount: type: integer format: int32 filteredCount: type: integer format: int32 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: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/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' FormResponsesExportOptions: type: object properties: formId: type: string example: 588f7ee98f138b19220041a7 assessmentId: type: string example: 588f7ee98f138b19220041a7 submitPersonFilter: type: string targetPersonFilter: type: string fromSubmitAt: type: string untilSubmitAt: type: string submitPersonFields: type: array items: type: string targetPersonFields: type: array items: type: string format: type: string splitColumns: type: boolean FormQuestionInfo: type: object required: - id - question properties: id: type: string example: 588f7ee98f138b19220041a7 question: type: string questionTr: $ref: '#/definitions/Translations' Translations: type: object required: - values properties: values: type: object additionalProperties: 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 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 UpdateFormResponse: type: object properties: shareAccess: type: array description: list of share access, if the form response has been shared with anyone items: $ref: '#/definitions/ShareAccess' ResultsWithFormVersions: type: object required: - data properties: data: type: array items: $ref: '#/definitions/FormResponse' next: type: string example: 588f7ee98f138b19220041a7 access: type: array items: $ref: '#/definitions/ResultsAccess' formVersions: type: array items: $ref: '#/definitions/FormVersionInfo' FormVersionInfo: type: object required: - id - label - displayName - questions properties: id: type: string example: 588f7ee98f138b19220041a7 label: type: string displayName: type: string displayNameTr: $ref: '#/definitions/Translations' questions: type: array items: $ref: '#/definitions/FormQuestionInfo' 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 FormResponseApproval: type: object properties: message: type: string