Developers
Build on Fieldmox. Same rules as the app.
Connect an AI assistant, call Fieldmox from your own code, or get a webhook when something changes. Every request runs as a real user, in one team, with that user's permissions.
-
MCP server
For ChatGPT, Claude, Cursor and any MCP client. The user signs in through OAuth and picks the team the connection works in.
-
Agent sign-up
For agents without a browser. The agent registers itself, sends the user a link and a code, and waits for them to approve it.
-
API keys
For your own scripts and servers. An admin creates a key in Settings and your code sends it with each request.
-
Webhooks
Fieldmox calls your URL when a job, invoice, quote or client changes. Every delivery is signed.
Endpoints
Everything runs on one API origin, api.fieldmox.com.
- MCP server (Streamable HTTP)
-
https://api.fieldmox.com/api/mcp - OAuth issuer
-
https://api.fieldmox.com/api/auth - Protected resource metadata
-
https://api.fieldmox.com/.well-known/oauth-protected-resource - Agent Auth discovery
-
https://api.fieldmox.com/.well-known/agent-configuration - Health
-
https://api.fieldmox.com/health
MCP server
Give an AI assistant your jobs, quotes and invoices.
The Fieldmox MCP server speaks Streamable HTTP and uses OAuth 2.1. Clients register themselves with Dynamic Client Registration, and public clients with PKCE (S256) are accepted, so there's no client ID to request from us.
The user signs in during the OAuth redirect, or creates an account there. If they belong to more than one team, they pick one, and the token works in that team only.
Using ChatGPT or Claude? Follow the setup guide.
Scopes
| Scope | Grants |
|---|---|
| heffl:actions:read | Read tools |
| heffl:actions:write | Create, update and delete tools, within the user's role and approval rules |
| offline_access | Refresh tokens, so the connection stays signed in |
| openid profile email | Who the user is |
What the tools cover
The tool list is built from the same actions the Fieldmox app uses. A tool only appears if the user's role allows it.
-
Field service
Jobs, visits, properties and sites, tasks, and the timeline on any record.
-
Clients
Companies and contacts, comments, tags, sources and service zones.
-
Sales
Leads and lead stages, pipelines, quotations and lost reasons.
-
Money
Invoices, payments received, products and tax rates.
-
Email and documents
Send email, read email threads, and create documents from your templates.
-
Custom objects
Any custom object your team has set up, with its own fields.
Four helper tools let an agent find its way: heffl_search_actions, heffl_describe_action, heffl_validate_action and heffl_whoami.
Every tool returns the same envelope:
{ "ok": true, "data": … }
{ "ok": false, "error": { "code": "…", "message": "…" } } Agent sign-up
For agents that run without a browser.
Fieldmox is an Agent Auth Protocol provider. An agent registers with an Ed25519 key, asks only for the capabilities it needs, and gets back a link and a short code for the user.
The user opens the link, signs in or creates an account, checks the code matches, picks a team and approves. The agent can then call the same tools as the MCP server.
The user doesn't need a Fieldmox account beforehand. An agent can sign them up, but a person always approves it, and every account has a verified email.
- 1
Discover
GET /.well-known/agent-configuration lists every endpoint and the supported key algorithm.
- 2
Register
POST /api/auth/agent/register with a signed host JWT, the capabilities you want and the user's email.
- 3
Hand off
Send the user the approval link and the XXXX-XXXX code. Never enter the code for them.
- 4
Call
Once approved, POST /api/auth/capability/execute with a short-lived agent JWT.
- The full flow, with request examples and error handling, is in auth.md.
API keys
Call Fieldmox from your own code.
An admin creates a key in Settings → Developer. Fieldmox shows the key once, so store it somewhere safe. Send it in the x-api-key header.
A key reaches the same actions as the MCP server. List them from the catalog, then invoke one by name with its input.
API keys and webhooks are included in the Unlimited plan.
# What can this key do?
curl https://api.fieldmox.com/api/actions/catalog \
-H "x-api-key: $FIELDMOX_API_KEY"
# Run one action
curl https://api.fieldmox.com/api/actions/leads.create/invoke \
-H "x-api-key: $FIELDMOX_API_KEY" \
-H "content-type: application/json" \
-d '{ "input": { … } }' GET /api/actions/catalog/{name} returns one action's input schema. Results use the same ok / error envelope as MCP.
Webhooks
Hear about changes the moment they happen.
Add a webhook in Settings → Developer, choose the events you want, and use Test to send a sample delivery.
Deliveries follow the Standard Webhooks spec. Each one carries webhook-id, webhook-timestamp and webhook-signature headers, signed with HMAC-SHA256 using your whsec_ secret. Any Standard Webhooks library can verify them.
Events
- Leads
-
- lead.created
- lead.updated
- lead.deleted
- lead.stageChanged
- Deals
-
- deal.created
- deal.updated
- deal.deleted
- deal.stageChanged
- Contacts
-
- contact.created
- contact.updated
- contact.deleted
- contact.stageChanged
- Companies
-
- company.created
- company.updated
- company.deleted
- company.stageChanged
- Quotations
-
- quotation.created
- quotation.updated
- quotation.deleted
- quotation.statusChanged
- Jobs
-
- job.created
- job.updated
- job.deleted
- job.statusChanged
- Invoices
-
- invoice.created
- invoice.updated
- invoice.deleted
- invoice.statusChanged
- invoice.paid
- Payments and forms
-
- payment.received
- form.response.created
For agents reading this page
Machine-readable descriptions of everything above. Every page on this site also has a markdown version, served when you request it with Accept: text/markdown.
Building something on Fieldmox?
Tell us what you're making. The people who build the API answer, and we'd like to hear what's missing.