Formstep · Schema
Response
Every response is a JSON object with an `ok` field: the success envelope when `ok` is `true`, the error envelope when it is `false`.
FormsAutomationData CollectionWorkflow IntegrationSoftware-as-a-Service
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/formstep-io/json-schema/formstep-io-response-schema.json",
"title": "Response",
"description": "Every response is a JSON object with an `ok` field: the success envelope when `ok` is `true`, the error envelope when it is `false`.",
"x-generated": "2026-11-08",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/formstep-io-openapi.json#/components/schemas/Response",
"oneOf": [
{
"$ref": "#/$defs/SuccessEnvelope"
},
{
"$ref": "#/$defs/ErrorEnvelope"
}
],
"$defs": {
"AnalyticsGetResult": {
"title": "analytics.get result",
"type": "object",
"required": [
"formId",
"period",
"totalEvents",
"metrics",
"breakdown"
],
"properties": {
"formId": {
"type": "string"
},
"period": {
"type": "object",
"description": "Both `null` for all time.",
"required": [
"from",
"to"
],
"properties": {
"from": {
"type": [
"integer",
"null"
]
},
"to": {
"type": [
"integer",
"null"
]
}
}
},
"totalEvents": {
"type": "integer",
"description": "Raw event row count before deduplication into unique visitors."
},
"metrics": {
"type": "object",
"required": [
"views",
"uniqueVisitors",
"engaged",
"submissions",
"engagementRate",
"completionRate",
"bounceRate"
],
"properties": {
"views": {
"type": "integer"
},
"uniqueVisitors": {
"type": "integer"
},
"engaged": {
"type": "integer"
},
"submissions": {
"type": "integer"
},
"engagementRate": {
"type": "number",
"description": "0–100."
},
"completionRate": {
"type": "number",
"description": "0–100."
},
"bounceRate": {
"type": "number",
"description": "0–100."
}
}
},
"breakdown": {
"type": "object",
"description": "Unique visitors per value. A visitor counts once per value, like `metrics.uniqueVisitors`, however many events they sent.",
"required": [
"byBrowser",
"byCountry",
"byDevice",
"bySource"
],
"properties": {
"byBrowser": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"byCountry": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"byDevice": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"bySource": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
}
},
"events": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Present when `includeEvents` is `true`."
}
}
},
"AnswersByKey": {
"type": "object",
"additionalProperties": true,
"description": "Answers keyed by field key. A choice answer is its option key, a matrix `{ \"row_key\": \"column_key\" }`, a repeating group an array of instances."
},
"CustomDomain": {
"type": "object",
"required": [
"id",
"hostname"
],
"properties": {
"id": {
"type": "string",
"description": "Custom domain ID, for `shareLinks.update`."
},
"hostname": {
"type": "string"
}
}
},
"DisplayByKey": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "The same keys as `answers`, as readable text."
},
"DocumentsCreateResult": {
"title": "documents.create result",
"type": "object",
"required": [
"id",
"name",
"contentType",
"size",
"uploadUrl",
"expiresAt"
],
"properties": {
"id": {
"type": "string",
"description": "Document ID to reference as `documents[].documentId` in `requests.create`."
},
"name": {
"type": "string"
},
"contentType": {
"type": "string"
},
"size": {
"type": "integer"
},
"uploadUrl": {
"type": "string",
"description": "Presigned `PUT` URL.",
"format": "uri"
},
"expiresAt": {
"type": "integer",
"description": "Unix timestamp in milliseconds."
}
}
},
"ErrorCode": {
"type": "string",
"description": "Closed set: a new failure mode never adds a code, it adds a `details.reason`. Branch on `code` for the HTTP-level outcome and on `details.reason` for the fix.",
"enum": [
"VALIDATION_ERROR",
"UNAUTHORIZED",
"FORBIDDEN",
"NOT_FOUND",
"CONFLICT",
"RATE_LIMITED",
"UPGRADE_REQUIRED",
"METHOD_NOT_FOUND",
"INTERNAL_ERROR"
]
},
"ErrorDetails": {
"type": "object",
"description": "Present whenever the server can name the cause.",
"required": [
"reason"
],
"properties": {
"reason": {
"type": "string",
"description": "The specific cause, e.g. `UNKNOWN_FIELD_KEY`."
},
"field": {
"type": "string",
"description": "The offending parameter, dotted for nesting."
},
"validKeys": {
"type": "array",
"items": {
"type": "string"
}
},
"validValues": {
"type": "array",
"items": {
"type": "string"
},
"description": "The option values a choice question accepts."
},
"expectedType": {
"type": "string"
},
"feature": {
"type": "string",
"description": "On `UPGRADE_REQUIRED`."
},
"retryAfterMs": {
"type": "integer",
"description": "On a throttled call."
}
}
},
"ErrorEnvelope": {
"type": "object",
"required": [
"ok",
"error"
],
"properties": {
"ok": {
"const": false
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"$ref": "#/$defs/ErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable message."
},
"details": {
"$ref": "#/$defs/ErrorDetails"
}
}
}
}
},
"EventEnvelope": {
"type": "object",
"description": "The envelope a webhook subscription or request callback receives.",
"required": [
"id",
"type",
"createdAt",
"apiVersion",
"test",
"data"
],
"properties": {
"id": {
"type": "string",
"description": "Event ID. Samples use a fixed placeholder."
},
"type": {
"type": "string",
"description": "Dotted event type, e.g. `submission.completed` or `request.completed`."
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"apiVersion": {
"type": "string",
"description": "Payload version, e.g. `2026-09-24`."
},
"test": {
"type": "boolean",
"description": "`true` on samples and test requests."
},
"data": {
"type": "object",
"additionalProperties": true,
"description": "The event body. Submission fields are documented in the webhooks reference (https://docs.formstep.io/developers/webhooks-reference#payload), the request block on the callbacks page (https://docs.formstep.io/requests/callbacks#payload)."
}
}
},
"FieldListField": {
"type": "object",
"required": [
"key",
"type",
"title",
"required",
"prefillable"
],
"properties": {
"key": {
"type": "string",
"description": "Field key to address the field by in `prefill`, `context`, and `answers`."
},
"type": {
"type": "string",
"description": "The value shape `prefill` must supply, or `hidden` for a context field."
},
"title": {
"type": "string"
},
"required": {
"type": "boolean"
},
"prefillable": {
"type": "boolean",
"description": "`false` for a field nobody can supply a value for (file, signature, payment, appointment, documents), hidden fields, and calculated fields."
},
"conditional": {
"const": true,
"description": "Present when a logic rule decides whether the recipient sees this field."
},
"context": {
"const": true,
"description": "Present on a hidden field: its value belongs in `context`, never in `prefill`."
},
"calculated": {
"const": true,
"description": "Present on a calculated field: read it back in `answers`; nothing can send it."
},
"options": {
"type": "array",
"items": {
"$ref": "#/$defs/SlotKey"
},
"description": "Choice questions: send the option `key`, not its label."
},
"rows": {
"type": "array",
"items": {
"$ref": "#/$defs/SlotKey"
},
"description": "Matrix only."
},
"columns": {
"type": "array",
"items": {
"$ref": "#/$defs/SlotKey"
},
"description": "Matrix only. A matrix takes `{ \"row_key\": \"column_key\" }`."
},
"documents": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
}
}
},
"description": "Documents block only: the authored files every respondent already sees."
}
}
},
"FieldListGroup": {
"type": "object",
"description": "A repeating group, addressed as a whole with `[{ \"member_key\": value }]` instances.",
"required": [
"key",
"type",
"repeating",
"members"
],
"properties": {
"key": {
"type": "string"
},
"type": {
"const": "group"
},
"repeating": {
"const": true
},
"members": {
"type": "array",
"items": {
"$ref": "#/$defs/FieldListField"
}
}
}
},
"FieldsListResult": {
"title": "fields.list result",
"type": "object",
"required": [
"published",
"items",
"hasMore"
],
"properties": {
"published": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/$defs/FieldListField"
},
{
"$ref": "#/$defs/FieldListGroup"
}
]
}
},
"hasMore": {
"const": false
}
}
},
"Folder": {
"type": "object",
"required": [
"id",
"name",
"workspaceId",
"parentId",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"description": "Folder ID."
},
"name": {
"type": "string"
},
"workspaceId": {
"type": "string"
},
"parentId": {
"type": [
"string",
"null"
],
"description": "Parent folder ID, or `null` at workspace root."
},
"createdAt": {
"type": "integer",
"description": "Unix timestamp in milliseconds."
}
}
},
"FoldersCreateResult": {
"title": "folders.create result",
"allOf": [
{
"$ref": "#/$defs/Folder"
},
{
"type": "object",
"required": [
"alreadyExisted"
],
"properties": {
"alreadyExisted": {
"type": "boolean"
}
}
}
]
},
"FoldersDeleteResult": {
"title": "folders.delete result",
"type": "object",
"required": [
"folderId",
"deletedFolderIds",
"deletedFormIds",
"message"
],
"properties": {
"folderId": {
"type": "string"
},
"deletedFolderIds": {
"type": "array",
"items": {
"type": "string"
}
},
"deletedFormIds": {
"type": "array",
"items": {
"type": "string"
}
},
"message": {
"type": "string"
}
}
},
"FoldersListResult": {
"title": "folders.list result",
"type": "object",
"required": [
"items",
"nextCursor",
"hasMore",
"canPaginate"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/$defs/Folder"
}
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Pass back as `cursor` to read the next page. `null` on the last page."
},
"hasMore": {
"type": "boolean",
"description": "Whether more items exist after this page."
},
"canPaginate": {
"type": "boolean",
"description": "`false` when `hasMore` is true but no cursor can resume (fuzzy search)."
}
}
},
"FoldersUpdateResult": {
"title": "folders.update result",
"type": "object",
"additionalProperties": true,
"description": "The published reference does not document this result shape; treat it as an open object."
},
"FormSettingsGetResult": {
"title": "formSettings.get result",
"type": "object",
"required": [
"settings",
"isDefault",
"availableEmailDomains",
"defaultFromAddress",
"payment"
],
"properties": {
"formId": {
"type": "string"
},
"settings": {
"type": "object",
"additionalProperties": true,
"description": "The effective settings, with defaults filled in."
},
"isDefault": {
"type": "boolean",
"description": "`true` when the form has no saved settings yet and you are seeing the defaults."
},
"availableEmailDomains": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"hostname"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as `emailDomainId`."
},
"hostname": {
"type": "string"
},
"fromAddress": {
"type": "string"
}
}
},
"description": "Verified email domains you can pass as `emailDomainId`."
},
"defaultFromAddress": {
"type": "string"
},
"payment": {
"type": "object",
"additionalProperties": true,
"description": "Whether Stripe is connected. Connecting it is a dashboard step."
}
}
},
"FormSettingsUpdateResult": {
"title": "formSettings.update result",
"type": "object",
"additionalProperties": true,
"description": "The published reference does not document this result shape; treat it as an open object."
},
"FormSummary": {
"type": "object",
"required": [
"id",
"name",
"folderId",
"workspaceId",
"isPublished",
"publishedAt",
"unpublishedAt",
"createdAt",
"lastEditedAt",
"emoji"
],
"properties": {
"id": {
"type": "string",
"description": "Form ID."
},
"name": {
"type": "string"
},
"folderId": {
"type": [
"string",
"null"
],
"description": "Folder ID, or `null` at workspace root."
},
"workspaceId": {
"type": "string"
},
"isPublished": {
"type": "boolean"
},
"publishedAt": {
"type": [
"integer",
"null"
],
"description": "Unix timestamp in milliseconds."
},
"unpublishedAt": {
"type": [
"integer",
"null"
],
"description": "Unix timestamp in milliseconds."
},
"createdAt": {
"type": "integer",
"description": "Unix timestamp in milliseconds."
},
"lastEditedAt": {
"type": [
"integer",
"null"
],
"description": "Unix timestamp in milliseconds."
},
"emoji": {
"type": [
"string",
"null"
]
}
}
},
"FormsCreateResult": {
"title": "forms.create result",
"type": "object",
"required": [
"id",
"name",
"workspaceId",
"folderId",
"isPublished",
"createdAt",
"previewUrl"
],
"properties": {
"id": {
"type": "string",
"description": "Form ID."
},
"name": {
"type": "string"
},
"workspaceId": {
"type": "string"
},
"folderId": {
"type": [
"string",
"null"
]
},
"isPublished": {
"type": "boolean"
},
"createdAt": {
"type": "integer",
"description": "Unix timestamp in milliseconds."
},
"previewUrl": {
"type": "string",
"format": "uri"
}
}
},
"FormsDeleteResult": {
"title": "forms.delete result",
"type": "object",
"additionalProperties": true,
"description": "The published reference does not document this result shape; treat it as an open object. A form already in trash returns `alreadyTrashed: true` and keeps its original trash date.",
"properties": {
"alreadyTrashed": {
"type": "boolean"
}
}
},
"FormsGetResult": {
"title": "forms.get result",
"allOf": [
{
"$ref": "#/$defs/FormSummary"
},
{
"type": "object",
"required": [
"questions",
"hasContent",
"cover",
"logo",
"isDeleted",
"trashedAt",
"previewUrl"
],
"properties": {
"questions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"inputType": {
"type": "string"
},
"title": {
"type": "string"
},
"metadata": {
"type": [
"object",
"null"
],
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"hasContent": {
"type": "boolean"
},
"cover": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"logo": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"isDeleted": {
"type": "boolean"
},
"trashedAt": {
"type": [
"integer",
"null"
],
"description": "Unix timestamp in milliseconds."
},
"previewUrl": {
"type": "string",
"description": "A preview link that shows live edits.",
"format": "uri"
}
}
}
]
},
"FormsListResult": {
"title": "forms.list result",
"type": "object",
"required": [
"items",
"nextCursor",
"hasMore",
"canPaginate"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/$defs/FormSummary"
}
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Pass back as `cursor` to read the next page. `null` on the last page."
},
"hasMore": {
"type": "boolean",
"description": "Whether more items exist after this page."
},
"canPaginate": {
"type": "boolean",
"description": "`false` when `hasMore` is true but no cursor can resume (fuzzy search)."
}
}
},
"FormsPublishResult": {
"title": "forms.publish result",
"type": "object",
"additionalProperties": true,
"description": "The published reference does not document this result shape; treat it as an open object. An already-published form returns `alreadyPublished: true`.",
"properties": {
"alreadyPublished": {
"type": "boolean"
}
}
},
"FormsRestoreResult": {
"title": "forms.restore result",
"type": "object",
"additionalProperties": true,
"description": "The published reference does not document this result shape; treat it as an open object. A form that is not in trash returns `alreadyRestored: true`.",
"properties": {
"alreadyRestored": {
"type": "boolean"
}
}
},
"FormsUnpublishResult": {
"title": "forms.unpublish result",
"type": "object",
"additionalProperties": true,
"description": "The published reference does not document this result shape; treat it as an open object. A form that is not published returns `alreadyUnpublished: true`.",
"properties": {
"alreadyUnpublished": {
"type": "boolean"
}
}
},
"FormsUpdateResult": {
"title": "forms.update result",
"type": "object",
"required": [
"id",
"name",
"folderId",
"emoji"
],
"properties": {
"id": {
"type": "string",
"description": "Form ID."
},
"name": {
"type": "string"
},
"folderId": {
"type": [
"string",
"null"
]
},
"emoji": {
"type": [
"string",
"null"
]
},
"cover": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Returned only when you sent `cover`."
},
"logo": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Returned only when you sent `logo`."
},
"noChange": {
"const": true,
"description": "Added when the payload matched the current state on every scalar field."
}
}
},
"IdleWindow": {
"type": "string",
"enum": [
"12h",
"1d",
"3d",
"1w"
]
},
"MeGetResult": {
"title": "me.get result",
"type": "object",
"required": [
"id",
"email",
"name"
],
"properties": {
"id": {
"type": "string"
},
"email": {
"type": [
"string",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
}
}
},
"MethodsListResult": {
"title": "methods.list result",
"type": "object",
"required": [
"methods"
],
"properties": {
"methods": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"RequestDeliveryStatus": {
"type": "string",
"description": "`not_requested` until an invitation is queued, then `queued` → `sent` or `failed`, and `bounced` once the mail provider reports a hard bounce or a complaint.",
"enum": [
"not_requested",
"queued",
"sent",
"failed",
"bounced"
]
},
"RequestOutcome": {
"type": "string",
"description": "The recipient's verdict from a decision question.",
"enum": [
"approve",
"decline",
"changes"
]
},
"RequestStatus": {
"type": "string",
"enum": [
"pending",
"completed",
"expired",
"canceled"
]
},
"RequestSummary": {
"type": "object",
"description": "A request without its link, answers, and timeline: a `requests.list` item.",
"required": [
"id",
"workspaceId",
"formId",
"formSnapshotId",
"submissionId",
"status",
"outcome",
"createdVia",
"isTest",
"recipient",
"language",
"externalId",
"metadata",
"context",
"prefill",
"readonlyKeys",
"documents",
"delivery",
"deliveryStatus",
"hasCallback",
"callbackFailedAt",
"expiresAt",
"createdAt",
"updatedAt",
"openedAt",
"startedAt",
"lastActivityAt",
"completedAt",
"expiredAt",
"canceledAt",
"canceledBy",
"cancelReason",
"reminderStep",
"remindersSent",
"reminderDueAt"
],
"properties": {
"id": {
"type": "string",
"description": "Request ID."
},
"workspaceId": {
"type": "string"
},
"formId": {
"type": "string"
},
"formSnapshotId": {
"type": "string",
"description": "The published form version the request is pinned to."
},
"submissionId": {
"type": [
"string",
"null"
]
},
"status": {
"$ref": "#/$defs/RequestStatus"
},
"outcome": {
"oneOf": [
{
"$ref": "#/$defs/RequestOutcome"
},
{
"type": "null"
}
],
"description": "`null` on anything but a completed request whose recipient picked one of the three."
},
"createdVia": {
"type": "string",
"enum": [
"api",
"mcp",
"dashboard"
]
},
"isTest": {
"type": "boolean",
"description": "Created with `test: true`."
},
"recipient": {
"type": "object",
"required": [
"email",
"name"
],
"properties": {
"email": {
"type": [
"string",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
}
}
},
"language": {
"type": "string"
},
"externalId": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"context": {
"type": "object",
"additionalProperties": true
},
"prefill": {
"type": "object",
"additionalProperties": true
},
"readonlyKeys": {
"type": "array",
"items": {
"type": "string"
}
},
"documents": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"name",
"size",
"contentType"
],
"properties": {
"field": {
"type": "string"
},
"name": {
"type": "string"
},
"size": {
"type": "integer"
},
"contentType": {
"type": "string"
}
}
},
"description": "Per-request documents."
},
"delivery": {
"type": "string",
"enum": [
"none",
"email"
]
},
"deliveryStatus": {
"$ref": "#/$defs/RequestDeliveryStatus"
},
"hasCallback": {
"type": "boolean",
"description": "Whether a callback URL is set. The URL itself is never returned."
},
"callbackFailedAt": {
"type": [
"integer",
"null"
],
"description": "Set while this request's callback has run out of attempts; cleared once one gets through or you replay it."
},
"expiresAt": {
"type": "integer",
"description": "Unix timestamp in milliseconds."
},
"createdAt": {
"type": "integer",
"description": "Unix timestamp in milliseconds."
},
"updatedAt": {
"type": "integer",
"description": "Unix timestamp in milliseconds."
},
"openedAt": {
"type": [
"integer",
"null"
],
"description": "Unix timestamp in milliseconds."
},
"startedAt": {
"type": [
"integer",
"null"
],
"description": "Unix timestamp in milliseconds."
},
"lastActivityAt": {
"type": [
"integer",
"null"
],
"description": "Unix timestamp in milliseconds."
},
"completedAt": {
"type": [
"integer",
"null"
],
"description": "Unix timestamp in milliseconds."
},
"expiredAt": {
"type": [
"integer",
"null"
],
"description": "Unix timestamp in milliseconds."
},
"canceledAt": {
"type": [
"integer",
"null"
],
"description": "Unix timestamp in
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://artifacts.apis.io/formstep-io/json-schema/formstep-io-response-schema.json
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/formstep-io-response"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.