Migrating from Forms to Flows

As the legacy Forms endpoints are deprecated, new integrations should use Flows. For an introduction to Flows and how they work, see the Flows guide. A Flow can handle subscriptions, unsubscriptions, profile updates, and landing pages, but it is not a drop-in replacement with the same ID and request data. Plan the migration for each form and use case.

Deprecation status

The legacy Forms endpoints are deprecated and will be switched off after a transition period. Until then, they continue to work for existing integrations. New CleverReach accounts (created since 3rd of September 2026) only use Flows, so an integration that only supports Forms cannot serve these customers. We will announce the end-of-life date at least 6 months in advance in the Changelog. Subscribe to the RSS feed to get notified.

Endpoint Mapping

The table below maps legacy Forms endpoints to the closest Flow routes and highlights important differences to consider during migration.

Legacy endpoint	Flow route	Migration notes
GET /v3/forms	GET /flow/flow	Returns the authenticated client's Flows. Optionally filter by playbook and sort with order and dir.
GET /v3/groups/:id/forms	GET /flow/flow	The Flow list has no group ID filter. Read each Flow's details and check setup.groupid. Filter in your application if needed.
GET /v3/forms/:id	GET /flow/flow/{flow_id}	Use the new Flow ID. A Form ID and a Flow ID are separate entities and cannot be used interchangeably.
GET /v3/forms/:id/code	GET /flow/flow/{flow_id}/embedded	Returns HTML code if the Flow supports embedding. Check the Flow and the result before replacing the existing embed code.
POST /v3/forms/:group_id/ createfromtemplate/:type	POST /flow/flow	Not functionally equivalent. A Flow is created with data such as name, playbook, and setup. Recreate the form configuration and steps in a suitable Flow.
POST /v3/forms/:id/ send/:type	POST /flow/flow/{flow_id}/send	Not a 1:1 replacement. The endpoint only sends a confirmation email. For deactivation, use a Flow with the playbook type unsubscribe.

Migration Steps and Checklist

These steps guide developers through migrating an existing Forms integration to Flows.

1. Find every /v3/forms call in your software and identify their purpose
2. Continue to read and support saved Forms selections. When editing an existing setup, show its current selection and let the customer switch to a Flow. Do not offer Forms for new configurations. New accounts no longer have legacy Forms, so Forms-only setups cannot serve them.
3. No new scope is required: the existing oa_forms scope grants access to all Flow Endpoints. Customers do not need to reconnect your integration. Use the connected customer's authorization to list their Flows with GET /flow/flow, then let the customer select a Flow they configured in their CleverReach account. You can also create a new Flow with POST /flow/flow, using the appropriate name, playbook, and setup.
4. Save the selected Flow ID in the customer's integration settings. Form IDs and Flow IDs are different and must not be treated as interchangeable. Check setup.groupid with GET /flow/flow/{flow_id} if your integration needs to verify the target group
5. Replace the relevant Forms API calls with Flow routes. Support embedded code or public Flow routes where appropriate, and update your Flow event and webhook handling
6. Test signup, DOI, unsubscribe, consent data, and error cases with a test customer account. Explain how customers can configure and select their own Flows, then retire Forms support only according to the API's deprecation lifecycle

Sending a Confirmation Email

The legacy request included type (activate or deactivate) in the path and an email address in the request body. The Flow endpoint is more specific: POST /flow/flow/{flow_id}/send only sends a confirmation email. Its schema includes receiver_id and doidata.

Each Flow has its own confirmation email. The Flow you address with flowid determines which email is sent, so there is no separate parameter to select an email. Customers edit the email in the Flow settings in their CleverReach account. If a customer needs different confirmation emails, for example per sign-up source, they need a separate Flow for each.

For the complete Double Opt-In workflow, including preparing an inactive receiver and attaching consent data, see the Double Opt-In guide.

Key Differences

• Different IDs: Manage Form and Flow IDs separately. Get Flow IDs from GET /flow/flow and map them explicitly.
• One confirmation email per Flow: The Flow ID determines which confirmation email is sent. See Sending a Confirmation Email.
• Different group assignment: The documented Flow list does not provide a group ID filter. The assignment is available in the Flow details (setup.groupid).
• No drop-in form template endpoint: POST /flow/flow creates Flow data. The legacy template call does not automatically recreate all form settings and steps.
• Embedding is optional: According to its description, GET /flow/flow/{flow_id}/embedded works only if the Flow supports embedding.
• Events change: The deprecated form.* events are replaced by flow.created, flow.updated, and flow.deleted. Update your event subscriptions and handlers accordingly. See Flow events.