For developers

Agency API

All FormHam developer documentation — HTML forms, the embed, webhooks and integrations.

One credential across every client site you look after. Pull leads into your own CRM or warehouse, reconcile what you bill against what actually arrived, and create a client's form as part of standing the site up rather than by hand afterwards.

Part of the Agency and Enterprise plans, and off until you switch it on. See pricing.

Turning it on

Three steps, all in the app, none of which need us.

  1. Open Settings → API Tokens on the business you want to expose.
  2. Switch Agency API on. It is off by default on every account, including ones already on a plan that includes it — the API reads the leads your clients' customers submitted, so nobody gets it by inheriting a plan change.
  3. Create a token with the Agency API scope. A plugin or integration token will not work here, deliberately: those live in client sites and third-party automation platforms, and none of them should become a key to this.

Do it once per business, or once on each and hold several tokens — a token may be pinned to a single client, which is how you hand one to that client's own developer without giving them the other forty-nine.

Authentication

Send the token as a bearer header on every request. There is no other auth method.

curl https://app.formham.co.uk/api/agency/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Start with /me. It answers the three questions a 403 elsewhere would leave open: whether your token is right, which businesses it covers, and — in businesses_unavailable — why any of yours are missing, so a client site that silently drops out of a nightly sync explains itself instead of just vanishing.

Endpoints

MethodPathWhat it does
GET /api/agency/v1/app/businesses Businesses. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/business/members Business Members. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/business/members Add Business Member. Uses the same fields, validation and role permissions as the app.
DELETE /api/agency/v1/app/business/members/{userId} Remove Business Member. Uses the same fields, validation and role permissions as the app.
PATCH /api/agency/v1/app/business/members/{userId} Update Business Member Role. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/dashboard Dashboard. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/onboarding-progress Onboarding Progress. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/forms Forms. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/forms/{id} Show Form. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/forms/{id}/webhook-secret Webhook Secret. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/forms/{id}/notifications Form Notifications. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/submissions Submissions. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/submissions/{id} Show Submission. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/submissions/{id}/notes Notes. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/logs Logs. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/logs/failed-count Logs Failed Count. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/business Business. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/billing Billing. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/sending-domain Sending Domain. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/tokens Tokens. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/customer-api Customer Api. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/mailing-lists Mailing Lists. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/mailing-list-destination-providers Mailing List Destination Providers. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/mailing-lists/{id}/subscribers Mailing List Subscribers. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/billing/sites Sites. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/forms Create Form. Uses the same fields, validation and role permissions as the app.
PATCH /api/agency/v1/app/forms/{id} Update Form. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/forms/{id}/test Test Form. Uses the same fields, validation and role permissions as the app.
DELETE /api/agency/v1/app/forms/{id} Destroy Form. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/forms/{id}/duplicate Duplicate Form. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/forms/{id}/webhook-secret/rotate Rotate Webhook Secret. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/forms/{id}/notifications Create Form Notification. Uses the same fields, validation and role permissions as the app.
PATCH /api/agency/v1/app/forms/{id}/notifications/{notificationId} Update Form Notification. Uses the same fields, validation and role permissions as the app.
DELETE /api/agency/v1/app/forms/{id}/notifications/{notificationId} Delete Form Notification. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/logs/{id}/retry Retry Log. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/submissions/{id}/notes Add Note. Uses the same fields, validation and role permissions as the app.
DELETE /api/agency/v1/app/submissions/{id}/notes/{noteId} Delete Note. Uses the same fields, validation and role permissions as the app.
PUT /api/agency/v1/app/submissions/{id}/lead-status Set Status. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/submissions/bulk/lead-status Bulk Lead Status. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/submissions/{id}/release Release. Uses the same fields, validation and role permissions as the app.
PATCH /api/agency/v1/app/business Update Business. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/notification-recipients/replace Replace Recipient. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/tokens Create Token. Uses the same fields, validation and role permissions as the app.
DELETE /api/agency/v1/app/tokens/{id} Revoke Token. Uses the same fields, validation and role permissions as the app.
PATCH /api/agency/v1/app/customer-api Update Customer Api. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/mailing-lists Create Mailing List. Uses the same fields, validation and role permissions as the app.
PATCH /api/agency/v1/app/mailing-lists/{id} Update Mailing List. Uses the same fields, validation and role permissions as the app.
DELETE /api/agency/v1/app/mailing-lists/{id} Delete Mailing List. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/mailing-lists/{id}/destinations Create Mailing List Destination. Uses the same fields, validation and role permissions as the app.
PATCH /api/agency/v1/app/mailing-lists/{id}/destinations/{destinationId} Update Mailing List Destination. Uses the same fields, validation and role permissions as the app.
DELETE /api/agency/v1/app/mailing-lists/{id}/destinations/{destinationId} Delete Mailing List Destination. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/mailing-lists/{id}/destinations/{destinationId}/backfill Backfill Mailing List Destination. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/billing/client-workspaces Create Client Workspace. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/billing/checkout Start Checkout. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/billing/close-workspace Close Workspace. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/account/delete Delete Account. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/submissions/export Export Submissions. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/forms/{id}/export/panel App\ Http\ Controllers\ Panel Submission Export Controller. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/submissions/erase-by-email Erase By Email. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/submissions/{id}/erase Erase Submission. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/submissions/bulk/delete Bulk Delete. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/mailing-lists/{id}/export Export Mailing List. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/mailing-lists/{id}/export/all Export Panel Mailing List. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/sending-domain Provision Sending Domain. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/sending-domain/verify Verify Sending Domain. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/forms/{id}/webhook-test Test Webhook. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/plugin-token Issue Plugin Token. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/app/submission-files/{submissionFile} Attachment. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/download-plugin Plugin. Uses the same fields, validation and role permissions as the app.
POST /api/agency/v1/app/billing/portal Billing Portal. Uses the same fields, validation and role permissions as the app.
GET /api/agency/v1/me Who this token is, which businesses it covers, and why any of yours are missing.
GET /api/agency/v1/businesses Every client business this token can reach.
GET /api/agency/v1/usage Submission counts per business for a month. Takes ?month=YYYY-MM.
GET /api/agency/v1/forms Forms across every reachable business. Filter with ?business_id= and ?is_active=.
POST /api/agency/v1/forms Create a form on one of your businesses. Needs business_id and name; fields are optional.
GET /api/agency/v1/forms/{uuid} One form, with its field list.
PATCH /api/agency/v1/forms/{uuid} Rename a form, pause it, or change where it notifies. Use /app/forms/{id} for the full app settings.
GET /api/agency/v1/submissions Leads across every reachable business. Cursor-paginated; filter with ?since=, ?until=, ?form_uuid=, ?business_id=.
GET /api/agency/v1/submissions/{receiptId} One lead by its receipt id, with the delivery attempts made for it.
DELETE /api/agency/v1/submissions/{receiptId} Permanently delete one lead with its files and delivery logs (owner/admin). 204 when gone, also on repeat; 404 if unknown or out of scope.

Paging

Lists are cursor-paginated, not offset-paginated, and that is the point of them rather than a detail. Pass cursor and you get rows after that id; the response carries next_cursor and has_more, and next_cursor is null on the last page. Store the last cursor you saw and a nightly sync resumes exactly where it stopped.

Offset paging would not survive an active form: a lead arriving between your request for page two and page three pushes a row from one to the other, and the sync never sees it. Keyset paging cannot do that.

GET https://app.formham.co.uk/api/agency/v1/submissions?limit=200&since=2026-09-01T00:00:00Z
GET https://app.formham.co.uk/api/agency/v1/submissions?limit=200&cursor=41822

limit defaults to 100 and tops out at 500. Timestamps are ISO 8601 — remember to URL-encode them, or the + in an offset arrives as a space.

What a lead looks like

Exactly what the outbound webhook delivers, minus the two keys that only mean something to a hook receiver. That is on purpose: if you map your CRM fields against a delivered webhook and then backfill history through this API, both have to give you the same keys, or the backfill writes blanks into records nobody looks at again.

Submitted answers are flattened into data by the same code the webhook uses, so a form whose plugin nests values under form_fields and one that posts them at the top level offer the same question under the same name.

Held leads

Submissions held for review are excluded by default, matching the webhook. A held lead has been delivered to nobody and may yet be deleted as spam, so syncing one creates a CRM contact for a bot. Pass include_quarantined=1 if you would rather triage them yourself; each row carries quarantined and quarantine_reason.

Rate limits

120 requests a minute and 3,000 an hour, counted per token rather than per account or per IP — so several client syncs from one build box do not spend each other's budget, and one runaway job cannot starve the rest. Over the limit you get a 429 with a Retry-After header.

Manage your clients through the API

The /app endpoints expose the customer app's business settings, team management, forms and notifications, submissions, delivery logs and retries, mailing lists and destinations, sending domains, billing, API tokens, exports and erasure actions. They call the same actions as the app, with the same validation, role permissions, billing rules and audit records.

These requests need an Agency API bearer token. Select the client with X-Business-Id or business_id. A token pinned to one business selects that business automatically; it cannot be used for another client, even when its owner belongs to both. An account-wide token requires an explicit business selection. Conflicting selectors are rejected. Each selected business must still have an eligible plan and API access enabled.

curl -X PATCH https://app.formham.co.uk/api/agency/v1/app/business \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Business-Id: 123" \
  -d '{"name":"Updated client name","contact_email":"enquiries@example.com"}'

The /app endpoints use the app's numeric resource IDs and response formats; the existing sync endpoints use form UUIDs, receipt IDs and cursor pagination. Create or update a form's complete settings through /app/forms rather than the smaller sync payload. To update notification rules, use /app/forms/{id}/notifications/{notificationId}.

POST /app/billing/portal returns a portal_url for the human to open. POST /app/download-plugin downloads a configured plugin package and issues plugin credentials; GET /app/submission-files/{submissionFile} downloads an attachment from the selected business. None of these requests needs browser cookies or a CSRF token.

DELETE actions remove notification rules, team memberships, mailing lists, destinations or API tokens, according to the same permissions as the app. Submission erasure uses the explicit /app/submissions/{id}/erase and /app/submissions/erase-by-email actions. A form can be paused with is_active: false. Platform administration is separate from this customer API.

App action limits apply in addition to the per-token API budget: standard writes allow 30 requests per minute, exports and checkout 12, and external provisioning and credential issuance 6. Team actions retain the app's limits. Respect Retry-After on a 429. Tokens can expire or be revoked; replacing a token does not remove webhook subscriptions.

When access stops

Four things are checked on every request, not just when the token is minted: the token carries the Agency API scope, the business still has the API switched on, its plan still includes the API, and you are still a member of it. A token cannot outlive the entitlement it was issued under — so if a client site drops out of your sync, /me will tell you which of the four changed.

Switching the API off is itself an effective revocation: every token stops immediately, and they keep working again if you switch it back on. Revoke them individually on the same screen if you want them gone for good.

Versioning

The version is in the path because the payload is a contract — your field mappings and your stored copy of our identifiers are built against these keys. We add keys to v1; we do not rename or remove them. Anything that would break a mapping is a new version.

Something missing?

This is a young surface and we would rather hear what you need than guess. hello@formham.co.uk.