API Overview

The FormWise External API lets you manage the end users of your Storefronts from your own systems. The headline use case is bring-your-own-billing: you take payment anywhere (your own checkout, an invoice, a partner platform), then call the API to create the account, assign plans, and grant access - no Stripe Connect required.

The API is versioned under /api/v1. Once published, the v1 surface only changes additively - fields are added, never renamed or removed.

Base URL: https://builder.formwise.ai/api/v1

Authentication

Every request carries an organization API key as a bearer token:

curl https://builder.formwise.ai/api/v1/end-users \
  -H "Authorization: Bearer fw_live_..."

Keys are organization-wide - one key works across every Storefront and Suite in your organization.

Creating a key

1. Open any Storefront and go to its Webhooks page.
2. In the Provisioning API card, name the key (for example "Production - Zapier") and click Create key.
3. Copy the secret immediately. It is shown exactly once - FormWise stores only a hash, so a lost secret can't be recovered. Create a new key instead.

Each key shows its display prefix (fw_live_xxxx), creation date, and when it was last used. Revoking a key takes effect immediately - requests using it start failing with api_key_revoked. An organization can hold up to 20 active keys.

Scopes

Keys are created with both scopes today; the API enforces them per endpoint, so future keys can be read-only.

Requests and responses

• Request bodies are JSON (Content-Type: application/json).
• Every response - success or error - carries an X-Request-Id header. Include it when contacting support about a specific call.
• Errors use one stable envelope: { "error": { "code": "...", "message": "..." } }. Branch on code; message is human-readable text and may change. See Errors for the full code table.

Rate limits

Each key may make 120 requests per minute (sliding 60-second window). Exceeding the limit returns 429 with a Retry-After header giving the number of seconds to wait.

Quickstart

Create an end user with a plan in one call:

curl -X POST https://builder.formwise.ai/api/v1/end-users \
  -H "Authorization: Bearer fw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "fullName": "Sam Customer",
    "tierPlanIds": ["<tier-plan-uuid>"]
  }'

The person then signs in to your Storefront with that email address using a one-time code - there is no password to distribute. Find plan IDs with GET /tier-plans or from the plan editor in the dashboard.

OpenAPI specification

The full machine-readable spec is available at https://builder.formwise.ai/api/v1/openapi.json -- use it to generate typed clients or import the API into your tooling. The reference pages below are generated from the same spec.

The surface covers the full lifecycle: create or update by email (adding plans and grants is a re-POST -- it's idempotent), inspect and list, adjust bonus credits, and take access away again -- remove a plan, remove a grant, or revoke the whole identity.