Fieldmox by Heffl

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. 1

    Discover

    GET /.well-known/agent-configuration lists every endpoint and the supported key algorithm.

  2. 2

    Register

    POST /api/auth/agent/register with a signed host JWT, the capabilities you want and the user's email.

  3. 3

    Hand off

    Send the user the approval link and the XXXX-XXXX code. Never enter the code for them.

  4. 4

    Call

    Once approved, POST /api/auth/capability/execute with a short-lived agent JWT.

  5. 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.

Mox on site, checking equipment and logging it on his phone

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.