v3

latestSwagger 2.02026-08-067506752.0 MB

form

Create a form

post/v1/org/{orgId}/form

Path parameters

orgIdstring required

Org identifier (either id or slug)

Request body

labelstring required

human-readable full name of form

displayNamestring

display name of form during completion

descriptionstring

description of form

status'ACTIVE' | 'INACTIVE' | 'ARCHIVED' required

status of the form

type'BUILT_IN' | 'CUSTOM'

type of the form

targetType'NONE' | 'PERSON'

target type that the form can be filled out about

targetFilterstring

filter that controls on which profiles this tab will appear

submitFilterstring

filter that controls which respondents can submit this form. The form:submit permission, if present, overrides this filter

responseReadFilterstring

filter that controls who can read the form responses. The formResponse:read permission, if present, overrides this filter

approval'MANAGER' | 'GRAND_MANAGER'

approval needed, if any approval is required

release'SUBMITTER' | 'ADMIN'

whether a release step is involved (subsequent to approval if any)

share'SUBMITTER' | 'ADMIN'

whether sharing form responses is allowed

authorSensitive'ANONYMOUS' | 'PRIVATE' | 'HIGH' | 'MANAGER'

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.

completeMode'MODAL' | 'FULLSCREEN'

appearance of the form during completion

Example request

{
  "label": "Health Index: Q2",
  "displayName": "Health Index",
  "description": "The Engineering department, where engineers develop new technology and products.",
  "blocks": [
    {
      "id": "588f7ee98f138b19220041a7",
      "questionId": "588f7ee98f138b19220041a7"
    }
  ],
  "signature": {
    "fieldId": "588f7ee98f138b19220041a7"
  },
  "options": {
    "notifyUserIds": [
      "588f7ee98f138b19220041a7"
    ]
  },
  "ai": {
    "agentUserId": "588f7ee98f138b19220041a7"
  }
}

Response

form created

idstring required

globally unique id

orgIdstring required

parent organization id

labelstring required

human-readable full name of form

displayNamestring

display name of form during completion

descriptionstring

description of form

status'ACTIVE' | 'INACTIVE' | 'ARCHIVED' required

status of the form

type'BUILT_IN' | 'CUSTOM'

type of the form

targetType'NONE' | 'PERSON'

target type that the form can be filled out about

targetFilterstring

filter that controls on which profiles this tab will appear

submitFilterstring

filter that controls which respondents can submit this form. The form:submit permission, if present, overrides this filter

responseReadFilterstring

filter that controls who can read the form responses. The formResponse:read permission, if present, overrides this filter

approval'MANAGER' | 'GRAND_MANAGER'

approval needed, if any approval is required

release'SUBMITTER' | 'ADMIN'

whether a release step is involved (subsequent to approval if any)

share'SUBMITTER' | 'ADMIN'

whether sharing form responses is allowed

authorSensitive'ANONYMOUS' | 'PRIVATE' | 'HIGH' | 'MANAGER'

completeMode'MODAL' | 'FULLSCREEN'

appearance of the form during completion

createIdstring

created by user id

createBehalfIdstring

created on behalf of user id

createAtstring

created timestamp

updateIdstring

last updated by user id

updateBehalfIdstring

last updated on behalf of user id

updateAtstring

last updated timestamp

deleteIdstring

deleted by user id

deleteBehalfIdstring

deleted on behalf of user id

deleteAtstring

deleted timestamp

Example response

{
  "id": "588f7ee98f138b19220041a7",
  "orgId": "588f7ee98f138b19220041a7",
  "label": "Health Index: Q2",
  "displayName": "Health Index",
  "description": "The Engineering department, where engineers develop new technology and products.",
  "blocks": [
    {
      "id": "588f7ee98f138b19220041a7",
      "questionId": "588f7ee98f138b19220041a7"
    }
  ],
  "signature": {
    "fieldId": "588f7ee98f138b19220041a7"
  },
  "options": {
    "notifyUserIds": [
      "588f7ee98f138b19220041a7"
    ]
  },
  "ai": {
    "agentUserId": "588f7ee98f138b19220041a7"
  },
  "createId": "588f7ee98f138b19220041a7",
  "createBehalfId": "588f7ee98f138b19220041a7",
  "createAttribution": {
    "principalUserId": "588f7ee98f138b19220041a7",
    "agentUserIds": [
      "588f7ee98f138b19220041a7"
    ],
    "eventId": "588f7ee98f138b19220041a7",
    "aiChatId": "588f7ee98f138b19220041a7"
  },
  "createAt": "2017-01-24T13:52Z",
  "updateId": "588f7ee98f138b19220041a7",
  "updateBehalfId": "588f7ee98f138b19220041a7",
  "updateAttribution": {
    "principalUserId": "588f7ee98f138b19220041a7",
    "agentUserIds": [
      "588f7ee98f138b19220041a7"
    ],
    "eventId": "588f7ee98f138b19220041a7",
    "aiChatId": "588f7ee98f138b19220041a7"
  },
  "updateAt": "2017-01-24T13:57:52Z",
  "deleteId": "588f7ee98f138b19220041a7",
  "deleteBehalfId": "588f7ee98f138b19220041a7",
  "deleteAttribution": {
    "principalUserId": "588f7ee98f138b19220041a7",
    "agentUserIds": [
      "588f7ee98f138b19220041a7"
    ],
    "eventId": "588f7ee98f138b19220041a7",
    "aiChatId": "588f7ee98f138b19220041a7"
  },
  "deleteAt": "2017-01-24T13:57:52Z"
}