# Forms API > The forms surface lets integrations manage capture points outside the app. This guide explains when to list, create, update, or delete forms, how forms depend on fields and tags, and how to change live forms without breaking website signups. - Human page: https://mailrith.com/developers/forms - Category: API Resources - Reading time: 6 min read ## What this guide covers Manage Mailrith capture forms from external builders, migrations, and admin tools. ## Manage Forms Forms are Mailrith capture points that collect subscriber information. A form can be shown on a website, embedded in a flow, or managed as part of a migration from another email platform. Use the public forms API when an external builder, migration script, agency tool, or internal admin system needs to manage Mailrith forms without asking a user to click through the app. Forms usually depend on subscriber fields, tags, and consent choices. Review those dependencies before creating or updating forms programmatically. 1. List existing forms before creating a replacement, especially during migration work. 2. Confirm required tags and custom fields already exist in the workspace. 3. Create or update the form using the public schema from [API Reference](https://mailrith.com/developers/api-reference.md). 4. Return the saved form ID to your external system so it can keep a stable reference. 5. Ask a Mailrith user to test the live form path as described in [Forms](https://mailrith.com/docs/forms.md). 6. Do not delete an old form until the old website embed or signup link has been removed. - List forms when an integration needs to inventory existing capture points. - Create forms when another system owns form setup and needs to keep Mailrith in sync. - Update forms when the external source of truth changes copy, fields, tags, or enabled state. - Delete forms only when the capture point has intentionally been removed and no active website or workflow still depends on it. ## Endpoint Overview `GET /v1/forms` returns forms in the authenticated workspace. Item endpoints let you inspect, update, or delete one form. `POST /v1/forms` creates a form. Build the payload from the OpenAPI schema so fields, settings, and enabled state match what Mailrith expects. If a form writes to custom fields or applies tags, make sure those fields and tags exist before creating the form. That keeps the form usable as soon as it is saved. Related OpenAPI operation groups: - Forms **List Forms** ```bash curl "https://api.mailrith.com/v1/forms?limit=25" \ -H "Authorization: Bearer mrk_example_secret_key" ``` ## Change Forms Safely Forms are often connected to live websites. A programmatic form update can affect new subscribers immediately, so treat form changes as user-facing changes even when the API call itself is small. Before deleting or replacing a form, confirm where it is embedded, which tags it applies, which custom fields it collects, and what the fallback plan is if the connected website has not been updated yet. - Prefer updating a form in place when existing embeds must keep working. - Create a new form when the new capture flow has a different purpose or consent path. - Keep form names descriptive so users can identify them in the Mailrith app. - After changing a form, submit a test subscriber through the real embed or integration path. ## Related Guides - [Custom Fields API](https://mailrith.com/developers/custom-fields.md): Custom fields define the typed workspace schema shared by subscribers, forms, and segments. This guide explains how to choose field types, map external data, create definitions, and avoid breaking forms or reports with unsafe schema changes. - [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the core subscriber write surface in `v1`. This guide explains when to list, when to upsert, how Mailrith chooses the workspace, what to include in an upsert body, and when to use async imports instead of many single requests. - [Webhook Subscriptions API](https://mailrith.com/developers/webhook-subscriptions.md): Webhook subscriptions let external systems receive Mailrith events for syncs, dashboards, fulfillment, and audit trails. This guide explains when to use webhooks, how to manage subscriptions, why the signing secret must be stored immediately, and how receivers should verify and deduplicate deliveries.