Form

GET/api/v1/forms

List_forms

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Query Parameters

q?string

Full-text search query applied to form name and title

status?string

Filter by status (draft, active, paused, deprecated, disabled)

page?integer

1-indexed page number

Formatint64

Range0 <= value

page_size?integer

Page size

Formatint64

Range0 <= value

sort_by?string

Sort field

sort_order?string

Sort order (asc or desc)

Value in

"asc"
"desc"

include_inactive?boolean

Include inactive versions (admin only)

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/forms"

{  "forms": [    {      "approval": {        "approver_role": "string",        "enabled": true,        "kind": "string"      },      "conditional_logic": [        {          "require": [            "string"          ],          "when": "string"        }      ],      "created_at": "2019-08-24T14:15:22Z",      "created_by": "string",      "drafts": {        "enabled": true,        "ttl_seconds": 0      },      "execution": {        "on_valid_submission": [          {            "fsm_name": "string",            "kind": "job",            "payload_template": null,            "queue": "string",            "target_state": "string",            "webhook_id": "string"          }        ]      },      "fields": [        {          "encrypted": true,          "kind": "string",          "label": "string",          "name": "string"        }      ],      "form_id": "string",      "multipart": {        "allowed_content_types": [          "string"        ],        "blob_bucket": "string",        "enabled": true,        "max_file_bytes": 0,        "max_files": 0      },      "name": "string",      "schema": {},      "spam": {        "allow_anonymous": true,        "honeypot_fields": [          "string"        ],        "min_submit_ms": 0      },      "status": "draft",      "submission_count": 0,      "title": "string",      "updated_at": "2019-08-24T14:15:22Z",      "version": 0    }  ],  "pagination": {    "has_more": true,    "page": 0,    "page_size": 0,    "total": 0  }}

POST/api/v1/forms

Register_form

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

approval?null|

conditional_logic?array<>

Conditional required-field rules

drafts?null|

execution?null|

fields?array<>

Field metadata (labels, kinds, encryption flags)

multipart?null|

name*string

Logical form name (e.g. "support.request")

schema*

JSON Schema used to validate submissions

spam?null|

title*string

Human-facing title

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/forms" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "schema": {},    "title": "string"  }'

{  "created_at": "2019-08-24T14:15:22Z",  "form_id": "string",  "name": "string",  "status": "draft",  "version": 0}

GET/api/v1/forms/{form_id}

Get_form

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/forms/string"

{  "approval": {    "approver_role": "string",    "enabled": true,    "kind": "string"  },  "conditional_logic": [    {      "require": [        "string"      ],      "when": "string"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "drafts": {    "enabled": true,    "ttl_seconds": 0  },  "execution": {    "on_valid_submission": [      {        "fsm_name": "string",        "kind": "job",        "payload_template": null,        "queue": "string",        "target_state": "string",        "webhook_id": "string"      }    ]  },  "fields": [    {      "encrypted": true,      "kind": "string",      "label": "string",      "name": "string"    }  ],  "form_id": "string",  "multipart": {    "allowed_content_types": [      "string"    ],    "blob_bucket": "string",    "enabled": true,    "max_file_bytes": 0,    "max_files": 0  },  "name": "string",  "schema": {},  "spam": {    "allow_anonymous": true,    "honeypot_fields": [      "string"    ],    "min_submit_ms": 0  },  "status": "draft",  "submission_count": 0,  "title": "string",  "updated_at": "2019-08-24T14:15:22Z",  "version": 0}

POST/api/v1/forms/{form_id}/drafts

Save_draft

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

draft_id?|

Existing draft id to update; omit to create a new draft

partial_data*

Partial submission data

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/forms/string/drafts" \  -H "Content-Type: application/json" \  -d '{    "partial_data": {}  }'

{  "draft_id": "string",  "expires_at": "2019-08-24T14:15:22Z",  "form_id": "string",  "form_version": 0}

GET/api/v1/forms/{form_id}/drafts/{draft_id}

Get_draft

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

draft_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/forms/string/drafts/string"

{  "draft_id": "string",  "expires_at": "2019-08-24T14:15:22Z",  "form_id": "string",  "form_version": 0,  "partial_data": {},  "subject": "string",  "updated_at": "2019-08-24T14:15:22Z"}

PUT/api/v1/forms/{form_id}/schema

Update_schema

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

fields?array<>|

Optional new field metadata; existing fields are retained when omitted

schema*

New JSON Schema used to validate future submissions

Response Body

`application/json`

curl -X PUT "https://example.com/api/v1/forms/string/schema" \  -H "Content-Type: application/json" \  -d '{    "schema": {}  }'

{  "approval": {    "approver_role": "string",    "enabled": true,    "kind": "string"  },  "conditional_logic": [    {      "require": [        "string"      ],      "when": "string"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "drafts": {    "enabled": true,    "ttl_seconds": 0  },  "execution": {    "on_valid_submission": [      {        "fsm_name": "string",        "kind": "job",        "payload_template": null,        "queue": "string",        "target_state": "string",        "webhook_id": "string"      }    ]  },  "fields": [    {      "encrypted": true,      "kind": "string",      "label": "string",      "name": "string"    }  ],  "form_id": "string",  "multipart": {    "allowed_content_types": [      "string"    ],    "blob_bucket": "string",    "enabled": true,    "max_file_bytes": 0,    "max_files": 0  },  "name": "string",  "schema": {},  "spam": {    "allow_anonymous": true,    "honeypot_fields": [      "string"    ],    "min_submit_ms": 0  },  "status": "draft",  "submission_count": 0,  "title": "string",  "updated_at": "2019-08-24T14:15:22Z",  "version": 0}

POST/api/v1/forms/{form_id}/status

Set_form_status

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

status*string

New status (draft, active, paused, deprecated, disabled)

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/forms/string/status" \  -H "Content-Type: application/json" \  -d '{    "status": "string"  }'

{  "approval": {    "approver_role": "string",    "enabled": true,    "kind": "string"  },  "conditional_logic": [    {      "require": [        "string"      ],      "when": "string"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "drafts": {    "enabled": true,    "ttl_seconds": 0  },  "execution": {    "on_valid_submission": [      {        "fsm_name": "string",        "kind": "job",        "payload_template": null,        "queue": "string",        "target_state": "string",        "webhook_id": "string"      }    ]  },  "fields": [    {      "encrypted": true,      "kind": "string",      "label": "string",      "name": "string"    }  ],  "form_id": "string",  "multipart": {    "allowed_content_types": [      "string"    ],    "blob_bucket": "string",    "enabled": true,    "max_file_bytes": 0,    "max_files": 0  },  "name": "string",  "schema": {},  "spam": {    "allow_anonymous": true,    "honeypot_fields": [      "string"    ],    "min_submit_ms": 0  },  "status": "draft",  "submission_count": 0,  "title": "string",  "updated_at": "2019-08-24T14:15:22Z",  "version": 0}

GET/api/v1/forms/{form_id}/submissions

List_submissions

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

Query Parameters

status?string

Filter by submission status

submitter?string

Filter by submitter subject (admins/owners only)

page?integer

1-indexed page number

Formatint64

Range0 <= value

page_size?integer

Page size

Formatint64

Range0 <= value

sort_by?string

Sort field

sort_order?string

Sort order (asc or desc)

Value in

"asc"
"desc"

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/forms/string/submissions"

{  "pagination": {    "has_more": true,    "page": 0,    "page_size": 0,    "total": 0  },  "submissions": [    {      "anonymous": true,      "attachments": [        {          "blob_id": "string",          "content_type": "string",          "field": "string",          "size_bytes": 0        }      ],      "created_at": "2019-08-24T14:15:22Z",      "data": {},      "execution_status": {        "approval": null,        "fsm": null,        "job": null,        "webhook": null      },      "form_id": "string",      "form_version": 0,      "status": "draft",      "submission_id": "string",      "submitted_by": "string",      "updated_at": "2019-08-24T14:15:22Z",      "validation": {        "errors": [          "string"        ],        "schema_version": 0,        "status": "valid"      }    }  ]}

POST/api/v1/forms/{form_id}/submissions

Create_submission

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

client_metadata?|

Client metadata such as start time (used for spam timing checks)

data*

Submission data validated against the active schema

draft_id?|

Optional draft id to promote and consume

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/forms/string/submissions" \  -H "Content-Type: application/json" \  -d '{    "data": {}  }'

{  "execution_status": {    "approval": null,    "fsm": null,    "job": null,    "webhook": null  },  "form_id": "string",  "form_version": 0,  "status": "draft",  "submission_id": "string"}

POST/api/v1/forms/{form_id}/submissions/batch

Create many submissions for a form in one request

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

A batch of submissions for one form. Each is fully validated and processed independently and fail-fast; the server enforces a per-batch cap.

submissions*array<>

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/forms/string/submissions/batch" \  -H "Content-Type: application/json" \  -d '{    "submissions": [      {        "data": {}      }    ]  }'

{  "count": 0,  "results": [    {      "execution_status": {        "approval": null,        "fsm": null,        "job": null,        "webhook": null      },      "form_id": "string",      "form_version": 0,      "status": "draft",      "submission_id": "string"    }  ]}

POST/api/v1/forms/{form_id}/submissions/multipart

Create_multipart_submission

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

Request Body

multipart/form-data

Multipart form data: JSON data field plus one or more file fields

TypeScript Definitions

Use the request body type in TypeScript.

[index: integer]?integer

Formatint32

Range0 <= value

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/forms/string/submissions/multipart" \  -F 0="0"

{  "execution_status": {    "approval": null,    "fsm": null,    "job": null,    "webhook": null  },  "form_id": "string",  "form_version": 0,  "status": "draft",  "submission_id": "string"}

POST/api/v1/forms/{form_id}/submissions/public

Create_public_submission

Path Parameters

form_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

client_metadata?|

Client metadata such as start time (used for spam timing checks)

data*

Submission data validated against the active schema

draft_id?|

Optional draft id to promote and consume

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/forms/string/submissions/public" \  -H "Content-Type: application/json" \  -d '{    "data": {}  }'

{  "execution_status": {    "approval": null,    "fsm": null,    "job": null,    "webhook": null  },  "form_id": "string",  "form_version": 0,  "status": "draft",  "submission_id": "string"}

GET/api/v1/forms/{form_id}/submissions/{submission_id}

Get_submission

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

submission_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/forms/string/submissions/string"

{  "anonymous": true,  "attachments": [    {      "blob_id": "string",      "content_type": "string",      "field": "string",      "size_bytes": 0    }  ],  "created_at": "2019-08-24T14:15:22Z",  "data": {},  "execution_status": {    "approval": null,    "fsm": null,    "job": null,    "webhook": null  },  "form_id": "string",  "form_version": 0,  "status": "draft",  "submission_id": "string",  "submitted_by": "string",  "updated_at": "2019-08-24T14:15:22Z",  "validation": {    "errors": [      "string"    ],    "schema_version": 0,    "status": "valid"  }}

POST/api/v1/forms/{form_id}/submissions/{submission_id}/retry

Retry_submission

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

submission_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

hook*string

Hook to retry (job, webhook, fsm, approval)

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/forms/string/submissions/string/retry" \  -H "Content-Type: application/json" \  -d '{    "hook": "string"  }'

{  "execution_status": {    "approval": null,    "fsm": null,    "job": null,    "webhook": null  },  "status": "draft",  "submission_id": "string"}

GET/api/v1/forms/{form_id}/versions

List_versions

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/forms/string/versions"

{  "versions": [    {      "created_at": "2019-08-24T14:15:22Z",      "fields": [        {          "encrypted": true,          "kind": "string",          "label": "string",          "name": "string"        }      ],      "form_id": "string",      "schema": {},      "updated_by": "string",      "version": 0    }  ]}

GET/api/v1/forms/{form_id}/versions/{version}

Get_version

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

form_id*string

version*integer

Formatint32

Range0 <= value

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/forms/string/versions/0"

{  "created_at": "2019-08-24T14:15:22Z",  "fields": [    {      "encrypted": true,      "kind": "string",      "label": "string",      "name": "string"    }  ],  "form_id": "string",  "schema": {},  "updated_by": "string",  "version": 0}

200application/json

201application/json

400

403

200application/json

404

200application/json

400

404

200application/json

403

404

200application/json

400

403

404

200application/json

403

404

200application/json

404

202application/json

400

404

409

202application/json

400

404

409

202application/json

400

404

409

202application/json

400

403

404

409

200application/json

403

404

200application/json

400

403

404

200application/json

404

200application/json

404

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`