Skip to content

API Reference

Basin provides a REST API that allows you to programmatically access and manage your form data. Use the API to build custom integrations, automate workflows, or incorporate Basin data into your own applications.

View Full API Documentation (Swagger)

Plan availability

API access is included on Growth, Pro, and Agency plans. See Plan Comparison.

Authentication

All API requests require authentication using an API key. Basin supports two types of API keys:

Key Type Scope Use Case
Account API Key All forms and projects in your account that you can access Backend integrations, admin dashboards
Form API Key Single form only Limited access integrations, Zapier, client projects

For detailed authentication setup, see our Authentication & Tokens guide.

Forms API Capabilities

Can forms be created through the public API?

Yes. POST /api/v1/forms creates a form under a project you own or administer. You can also list, show, update, and destroy forms.

Which form attributes are returned / accepted by the API?

The forms endpoints expose configuration fields such as:

  • Identity and routing: uuid, name, timezone, project_id, redirect_url, redirect page branding fields
  • Notifications and autoresponse settings: notification emails/CC/BCC, subjects, from names, autoreply fields, mail template IDs
  • Spam and protection: honeypot, CAPTCHA flags, duplicate_filter, content_blacklist, allowed_domains, blocked_domains, smtp_email_validation
  • Branding and retention: logo, button colors, retention_days, dashboard button visibility
  • Custom email sending domain fields (domain_id, domain_email) on Pro and above

For the full schema, use the Swagger API Reference.

Can Form Studio fields be created through the API?

No. There is no public API to create or edit Form Studio field definitions. Build and edit Form Studio forms in the Basin dashboard UI.

Can the Form Studio field schema be retrieved?

No documented public endpoint returns a Form Studio field schema for arbitrary forms. Do not assume endpoints such as /api/v1/forms/:id/fields or /api/v1/forms/:id/schema exist unless they appear in the Swagger docs.

The documented /api/v1/form_views endpoints expose read-only records from the legacy Form Builder (Form.io). A legacy form_view schema is not a Form Studio schema.

Which Form Studio operations are UI-only?

These are managed in the Basin dashboard (not via the public forms CRUD API):

  • Adding, removing, or reordering Form Studio fields
  • Editing Form Studio themes and survey structure
  • Publishing hosted Form Studio embeds beyond the fields exposed on the form record

Can tags be assigned while initially posting a submission?

No. Public API submission endpoints support index, show, update, and destroy — not create. Submission updates permit state fields such as spam, read, and trash. Lead tags and rules are configured in the dashboard; there is no API parameter to assign tags when a visitor first posts a submission to your form endpoint.

Visitor submissions still arrive through your normal form endpoint (POST /f/:id), not through the authenticated submissions API create action.

What is the difference between account- and form-scoped API keys?

Account keys can access all forms and projects available to the account. Form keys can access only one form. Find account keys under Account Settings → API Settings and form keys under Form → Integrations → API.

API Endpoints Overview

Resource Description
/api/v1/forms Create, list, show, update, and destroy forms
/api/v1/submissions List, retrieve, update, and destroy submissions
/api/v1/projects Create, list, show, update, and destroy projects
/api/v1/form_webhooks Create, list, show, update, and destroy form webhooks
/api/v1/domains List domains available to the authenticated account
/api/v1/form_views List and retrieve legacy Form Builder (Form.io) views

The public Swagger specification does not document APIs for creating or managing Basin Chat, Basin-hosted AI Sites, or Form Studio field schemas. Use the Basin dashboard for those products.

For complete endpoint documentation including request/response schemas, see the Swagger API Reference.

Need Help?