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.
- Open Settings → API Tokens on the business you want to expose.
- 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.
- 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
| Method | Path | What 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.