A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Formstack API is how an app or AI agent works with a Formstack account: listing forms and their fields, reading and creating the submissions a form collects, organizing forms into folders, and registering webhooks that fire when a form is submitted. Access is granted through an access token sent as a Bearer credential, and that token follows the in-app permissions of the Formstack user behind it, with no granular per-endpoint scopes to narrow it further. Formstack can also push a submission to a webhook URL the moment a form is submitted.
How an app or AI agent connects to Formstack determines what it can reach. Access runs through an OAuth 2.0 access token sent as a Bearer credential, and that token follows the in-app permissions of the Formstack user it belongs to.
The v2 REST API answers under https://www.formstack.com/api/v2/ and authenticates with an OAuth 2.0 access token sent as a Bearer credential. It accepts URL-encoded parameters or JSON, and returns JSON by default or XML on request.
The newer v2025 REST API answers under https://www.formstack.com/api/v2025/ and authenticates with a Personal Access Token sent as a Bearer credential, in the form fs_pat_
A webhook registered on a form posts the submission data to a chosen URL in real time as each form is submitted, so an app receives submissions instead of polling for them.
A user authorizes an application, which receives an OAuth 2.0 access token tied to that Formstack user. The token is sent as a Bearer credential and follows the user's in-app permissions, reaching every form, field, and submission that user can see. There are no granular per-endpoint scopes to narrow it.
A Personal Access Token is generated in the Formstack admin area with a name and an optional expiry, then sent as a Bearer credential in the form fs_pat_
The Formstack API is split into areas an agent can act on, such as forms, their fields, the submissions they collect, folders, webhooks, and the confirmation and notification emails a form sends. Each area has its own methods, and a single token reaches all of them across the account.
List the forms in an account, read a single form, create a form, copy a form, and delete a form.
List a form's fields, read a single field, create a field, update a field, and delete a field.
List a form's submissions, read a single submission, create a submission, and delete a submission.
List the folders that organize forms, and create a folder.
List a form's webhooks, create a webhook that posts on submission, and delete a webhook.
List and create the confirmation emails a form sends to the submitter, and the notification emails it sends to the team.
List the partial submissions saved before a form was finished, and read a single partial submission.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
FormsList the forms in an account, read a single form, create a form, copy a form, and delete a form.5 | ||||||
| GET | /api/v2/form.json | List all forms in the account, with paging, folder filtering, and sorting. | read | — | Current | |
An OAuth access token reaches every form the underlying Formstack user can see; there is no per-endpoint scope to narrow it. Acts onform Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/form/{id}.json | Get the details of a single form, including its fields and settings. | read | — | Current | |
Access follows the token's user; there is no per-form scope on the token itself. Acts onform Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/form.json | Create a new form in the account. | write | — | Current | |
A token that can write reaches every form the user can manage; the OAuth grant is account-level. Acts onform Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/form/{id}/copy.json | Create a copy of an existing form. | write | — | Current | |
The copy is created in the same account the token belongs to. Acts onform Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/form/{id}.json | Delete a form from the account. | write | — | Current | |
Deleting removes the form and the submissions stored on it; the token reaches any form the user can manage. Acts onform Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FieldsList a form's fields, read a single field, create a field, update a field, and delete a field.5 | ||||||
| GET | /api/v2/form/{id}/field.json | List all fields on a form. | read | — | Current | |
Fields define what a form asks for; the token's user must be able to see the form. Acts onfield Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/form/{id}/field.json | Add a new field to a form. | write | — | Current | |
Adding a field changes what the form collects from every future submitter. Acts onfield Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/field/{id}.json | Get the details of a single field. | read | — | Current | |
Access follows the token's user and the form the field belongs to. Acts onfield Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/field/{id}.json | Update a field's settings, such as its label, type, or options. | write | — | Current | |
Changing a field changes what the live form asks for. Acts onfield Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/field/{id}.json | Delete a field from a form. | write | — | Current | |
Removing a field removes the data it collected from the form's structure. Acts onfield Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SubmissionsList a form's submissions, read a single submission, create a submission, and delete a submission.4 | ||||||
| GET | /api/v2/form/{id}/submission.json | List the submissions on a form, with paging and date filtering. | read | — | Current | |
Submissions hold whatever people entered, including any personal data; the token reaches every submission on forms the user can see. Acts onsubmission Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/submission/{id}.json | Get the details of a single submission, including its field values. | read | — | Current | |
Returns the data a person entered into the form, which can include personal data. Acts onsubmission Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/form/{id}/submission.json | Create a submission on a form by supplying field values. | write | — | Current | |
Creating a submission can trigger the form's confirmation emails, notifications, and webhooks, the same as a real submitter. Acts onsubmission Permission (capability)None required VersionAvailable since the API’s base version Webhook event form_submissionRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/submission/{id}.json | Delete a submission from a form. | write | — | Current | |
Deleting permanently removes the data a person entered. Acts onsubmission Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FoldersList the folders that organize forms, and create a folder.2 | ||||||
| GET | /api/v2/folder.json | List the folders used to organize forms in the account. | read | — | Current | |
Folders are one way Formstack assigns form permissions to a group of forms. Acts onfolder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/folder.json | Create a folder for organizing forms. | write | — | Current | |
The folder is created in the account the token belongs to. Acts onfolder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList a form's webhooks, create a webhook that posts on submission, and delete a webhook.3 | ||||||
| GET | /api/v2/form/{id}/webhook.json | List the webhooks registered on a form. | read | — | Current | |
Shows where a form sends submission data, which reveals external destinations. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/form/{id}/webhook.json | Create a webhook on a form that posts submission data to a URL on each submission. | write | — | Current | |
Adding a webhook starts sending every future submission to an external URL. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook event form_submissionRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/webhook/{id}.json | Delete a webhook from a form. | write | — | Current | |
Removing a webhook stops the form sending submissions to that URL. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Confirmation & notification emailsList and create the confirmation emails a form sends to the submitter, and the notification emails it sends to the team.4 | ||||||
| GET | /api/v2/form/{id}/confirmation.json | List the confirmation emails a form sends to the submitter. | read | — | Current | |
Shows the messages a form sends back to people who submit it. Acts onconfirmation email Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/form/{id}/confirmation.json | Add a confirmation email that the form sends to the submitter. | write | — | Current | |
Changes what message a submitter receives after submitting. Acts onconfirmation email Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/form/{id}/notification.json | List the notification emails a form sends to the team on submission. | read | — | Current | |
Shows who on the team is emailed when the form is submitted. Acts onnotification email Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/form/{id}/notification.json | Add a notification email that the form sends to the team on submission. | write | — | Current | |
Changes which addresses receive submission data by email. Acts onnotification email Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Partial submissionsList the partial submissions saved before a form was finished, and read a single partial submission.2 | ||||||
| GET | /api/v2/form/{id}/partialsubmission.json | List the partial submissions saved on a form before it was finished. | read | — | Current | |
Partial submissions hold data entered before a person completed the form. Acts onpartial submission Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/partialsubmission/{id}.json | Get the details of a single partial submission. | read | — | Current | |
Returns the partial data a person entered before finishing. Acts onpartial submission Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Formstack can notify an app or AI agent the moment a form is submitted, instead of the app repeatedly asking. A webhook registered on a form posts the submission payload to a chosen URL in real time as each submission arrives.
| Event | What it signals | Triggered by |
|---|---|---|
Form submission | Fires when a form is submitted. Formstack posts the submission data to the webhook URL registered on that form in real time, including data created through the submission endpoint. | /api/v2/form/{id}/submission.json/api/v2/form/{id}/webhook.json |
Formstack limits how much an app or AI agent can call through a daily request quota counted per access token. Going over the quota returns a 429 error until the quota resets.
Formstack counts requests against a daily quota per access token, not per account or per user. On the v2 API the quota is 14,400 calls per access token per day. On the v2025 API the daily quota varies by account plan type. The quota resets daily at midnight, and a call made after the quota is used up returns 429 Too Many Requests.
List endpoints page through results with the page and per_page query parameters, for example form.json with page and per_page. The submission search service, which looks across every form in an account, returns at most 10,000 matching submissions per search.
Requests can be sent as URL-encoded parameters or JSON, and the v2 API returns JSON by default or XML when asked; the v2025 API returns JSON only. No single payload size limit is published across the whole API.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request URI was invalid, or a parameter was malformed. | Correct the path and parameters, then resend the request. |
| 401 | Unauthorized | Valid authentication credentials were not supplied, so the access token is missing, invalid, or expired. | Send a valid access token in the Authorization Bearer header. |
| 403 | Forbidden | The current user does not have access to this method or resource. | Use a token whose Formstack user has permission for the form or action. |
| 404 | Not Found | The resource requested could not be found, such as a form or submission id that does not exist. | Confirm the id and path are correct. |
| 415 | Unsupported Media Type | A valid media type was not used. The API accepts JSON, XML, or HTTP URL-encoded input. | Set a supported Content-Type, such as application/json, on the request. |
| 429 | Too Many Requests | The current access token has hit its daily rate limit. | Wait for the daily quota to reset at midnight, then retry. |
| 500 | Internal Server Error | An error occurred while processing the request. | Retry after a short delay, and contact Formstack support if it persists. |
| 503 | Service Unavailable | The service is temporarily unavailable, such as during maintenance. | Retry after a short delay. |
Formstack runs two API generations side by side. The v2 API uses OAuth 2.0 access tokens, and the newer v2025 API uses Personal Access Tokens; v2 is not being retired.
The v2 REST API authenticates with OAuth 2.0 access tokens sent as a Bearer credential, answers under /api/v2/, accepts URL-encoded parameters or JSON, and returns JSON by default or XML on request. It is rate limited to 14,400 calls per access token per day. Formstack has confirmed v2 is not being retired alongside the newer v2025 API.
Theme management was added to the v2025 API, with methods to view, copy, delete, and assign themes across main accounts and subaccounts. Released on 10 September 2025.
Formstack launched the v2025 Forms API, built on an OpenAPI specification and authenticating with Personal Access Tokens managed in the Formstack admin area rather than OAuth. It answers under /api/v2025/, returns JSON only, and has feature parity with the v2 API. Released on 22 August 2025.
Three subaccount management services were added, for listing subaccounts, copying themes to subaccounts, and duplicating forms into subaccounts. Released on 26 February 2025.
A submission search service was added to look across every form in an account for specific submission values, capped at 10,000 matching submissions per search, supporting GDPR data retention requests. Released on 13 February 2025.
An integration built on v2 keeps working, and can move to v2025 on a schedule that suits it.
Formstack API changelog ↗Bollard AI sits between a team's AI agents and Formstack. A Formstack access token reaches the whole account, so Bollard narrows each agent to exactly the forms and actions it needs, read or write, and checks and logs every call.