Update form
PATCH /forms/{form}. Parameters, permissions, request and response schemas.
PATCH /forms/{form}
Update form. Requires the REST write token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.
Authentication
Use a team API key as Authorization: Bearer YOUR_API_KEY. The token ability and the user’s role must both allow this operation. See authentication.
{
"ability": "write",
"team": "Token-bound Team",
"authorization": "Additional role, entity-policy and plan requirements vary by operation.",
"billing": "Blocked billing mode rejects writes with 402."
}Parameters
| Name | Location | Required | Description |
|---|---|---|---|
form | path | Yes | The form ID |
form
{
"type": "integer",
"minimum": 1
}Request body
The request body is optional.
application/json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255
},
"description": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string",
"enum": [
"widget",
"inline",
"link"
],
"title": "FormType"
},
"status": {
"type": "string",
"enum": [
"draft",
"active",
"paused",
"archived"
],
"title": "FormStatus"
},
"project_id": {
"type": "integer"
},
"settings": {
"description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.",
"anyOf": [
{
"type": "object",
"additionalProperties": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
}
},
{
"type": "array",
"items": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
}
},
{
"type": "null"
}
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"description": {
"type": [
"string",
"null"
]
},
"order": {
"type": "integer"
},
"questions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"type": {
"type": "string",
"enum": [
"multiple_choice_single",
"multiple_choice_multi",
"rating",
"nps",
"short_text",
"long_text",
"yes_no",
"emoji_reaction",
"welcome_screen",
"thank_you_screen"
],
"title": "FormQuestionType"
},
"title": {
"type": "string",
"maxLength": 500
},
"description": {
"type": [
"string",
"null"
]
},
"options": {
"type": [
"array",
"null"
],
"items": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
},
"description": "Question options retained as JSON. The editor uses strings or objects with value and label.",
"example": [
"Delivery time",
"Shipping cost"
]
},
"settings": {
"description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.",
"anyOf": [
{
"type": "object",
"additionalProperties": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
}
},
{
"type": "array",
"items": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
}
},
{
"type": "null"
}
]
},
"order": {
"type": "integer"
}
},
"required": [
"type",
"title"
]
}
}
}
}
}
},
"title": "UpdateFormRequest"
}{
"name": "Checkout delivery estimate",
"description": null,
"project_id": 101
}Example request
curl --request PATCH 'https://api.example.test/api/forms/1' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"name":"Checkout delivery estimate","description":null,"project_id":101}'Examples use fictional data. Replace resource IDs and the API host with your environment’s values.
Responses
200
FormResource
Content type: application/json.
{
"type": "object",
"properties": {
"data": {
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"public_id": {
"type": "string"
},
"project_id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string",
"enum": [
"widget",
"inline",
"link"
],
"title": "FormType"
},
"status": {
"type": "string",
"enum": [
"draft",
"active",
"paused",
"archived"
],
"title": "FormStatus"
},
"settings": {
"description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.",
"anyOf": [
{
"type": "object",
"additionalProperties": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
}
},
{
"type": "array",
"items": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
}
},
{
"type": "null"
}
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"form_id": {
"type": "integer"
},
"title": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
},
"order": {
"type": "integer"
},
"questions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"form_id": {
"type": "integer"
},
"form_step_id": {
"type": [
"integer",
"null"
]
},
"type": {
"type": "string",
"enum": [
"multiple_choice_single",
"multiple_choice_multi",
"rating",
"nps",
"short_text",
"long_text",
"yes_no",
"emoji_reaction",
"welcome_screen",
"thank_you_screen"
],
"title": "FormQuestionType"
},
"title": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"options": {
"type": [
"array",
"null"
],
"items": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
},
"description": "Question options retained as JSON. The editor uses strings or objects with value and label.",
"example": [
"Delivery time",
"Shipping cost"
]
},
"settings": {
"description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.",
"anyOf": [
{
"type": "object",
"additionalProperties": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
}
},
{
"type": "array",
"items": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
}
},
{
"type": "null"
}
]
},
"order": {
"type": "integer"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"id",
"form_id",
"form_step_id",
"type",
"title",
"description",
"options",
"settings",
"order",
"created_at",
"updated_at"
],
"title": "FormQuestionResource"
}
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"id",
"form_id",
"title",
"description",
"order",
"created_at",
"updated_at"
],
"title": "FormStepResource"
}
},
"questions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"form_id": {
"type": "integer"
},
"form_step_id": {
"type": [
"integer",
"null"
]
},
"type": {
"type": "string",
"enum": [
"multiple_choice_single",
"multiple_choice_multi",
"rating",
"nps",
"short_text",
"long_text",
"yes_no",
"emoji_reaction",
"welcome_screen",
"thank_you_screen"
],
"title": "FormQuestionType"
},
"title": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"options": {
"type": [
"array",
"null"
],
"items": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
},
"description": "Question options retained as JSON. The editor uses strings or objects with value and label.",
"example": [
"Delivery time",
"Shipping cost"
]
},
"settings": {
"description": "JSON object or array. Object keys depend on the provider, form question, or configuration being stored.",
"anyOf": [
{
"type": "object",
"additionalProperties": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
}
},
{
"type": "array",
"items": {
"description": "An arbitrary JSON value retained by a metadata/settings field.",
"oneOf": [
{
"type": "null"
},
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
}
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
}
}
]
}
},
{
"type": "null"
}
]
},
"order": {
"type": "integer"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"id",
"form_id",
"form_step_id",
"type",
"title",
"description",
"options",
"settings",
"order",
"created_at",
"updated_at"
],
"title": "FormQuestionResource"
}
},
"responses_count": {
"type": "integer"
},
"submitted_responses_count": {
"type": "integer",
"minimum": 0
},
"partial_responses_count": {
"type": "integer",
"minimum": 0
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"id",
"public_id",
"project_id",
"name",
"description",
"type",
"status",
"settings",
"created_at",
"updated_at"
],
"title": "FormResource"
},
{
"type": "object",
"required": [
"steps"
]
}
]
}
},
"required": [
"data"
]
}{
"data": {
"id": 101,
"public_id": "example-101",
"project_id": 101,
"name": "Checkout delivery estimate",
"description": null,
"type": "widget",
"status": "draft",
"settings": null,
"steps": [
{
"id": 101,
"form_id": 101,
"title": null,
"description": null,
"order": 1,
"created_at": null,
"updated_at": null
}
],
"created_at": null,
"updated_at": null
}
}401
Unauthenticated
Content type: application/json.
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}{
"message": "The request could not be completed."
}402
The Team is in read-only billing mode.
Content type: application/json.
{
"type": "object",
"properties": {
"error": {
"type": "string",
"const": "subscription_required"
},
"mode": {
"type": "string",
"const": "blocked"
},
"message": {
"type": "string",
"example": "Your team is in read-only mode. Update billing to make changes."
},
"grace_period_ends_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"required": [
"error",
"mode",
"message",
"grace_period_ends_at"
]
}{
"error": "subscription_required",
"mode": "blocked",
"message": "Your team is in read-only mode. Update billing to make changes.",
"grace_period_ends_at": null
}403
Authorization error
Content type: application/json.
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}{
"message": "The request could not be completed."
}404
Not found
Content type: application/json.
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error overview."
}
},
"required": [
"message"
]
}{
"message": "The request could not be completed."
}422
Validation error
Content type: application/json.
{
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Errors overview."
},
"errors": {
"type": "object",
"description": "A detailed description of each field that failed validation.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"required": [
"message",
"errors"
]
}{
"message": "The request could not be completed.",
"errors": {
"name": [
"The name field is required."
]
}
}429
Rate limit exceeded. Honor Retry-After before retrying.
Response headers:
{
"Retry-After": {
"description": "Seconds before retrying.",
"schema": {
"type": "integer"
}
}
}Content type: application/json.
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Too Many Attempts."
}
},
"required": [
"message"
]
}{
"message": "Too Many Attempts."
}See API conventions for error handling, rate limits, pagination, and uploads.