Formitize MCP Server

Formitize

Formitize is a field-service operations stack: CRM clients and sites, schedulable jobs, asset registers, mobile form templates, and submitted inspection reports. Australian accounts typically use service.formitize.com.au; the REST surface is version 2 under /api/rest/v2.

Hierarchy

Account → CRM clients (billingName) → locations & contacts → jobs (assigned to users/queues) → attached forms → submitted form rows → assets (per asset schema) → invoices.

Jobs can auto-create clients when client.billingName is supplied on create. Asset data is always scoped to an asset schema id — list schemas before listing assets.

Operational order

1. Clients — list CRM clients (page) or fetch one by client_id (billing, embedded contact/location ids).
2. Contacts & locations — always scoped to a client_id via nested CRM paths (crm/client/{id}/contact/ and .../location/). List or fetch by optional contact_id / location_id; upsert and delete on the same nested paths.
3. Jobs — list open jobs (optional status filter) or fetch one job by id for status, assignee, due date, and attached forms/history.
4. Assets — list asset schemas (optional schema_id for one definition), then list or fetch assets within a schema id.
5. Forms — list form templates; search submitted forms via form/submit/list/ (query, form_id, page) or fetch by submitted_id / job_id; upsert submissions when pushing inspection answers.
6. Lookup databases — list lookup DB names used by form dropdown fields.
7. Invoices — list invoice summaries when billing modules are enabled on the account.

Job status codes (for filters)

Comma-separated status on job list: 1 Created, 2 Assigned, 3 Accepted, 4 Finished, 6 Rejected, 8 Rescheduled.

Write semantics

• Client upsert — POST JSON to crm/client/ (create) or crm/client/{id} (update). billingName is the primary create field. Deactivate via extra_fields status: inactive.
• Contact upsert — POST crm/client/{client_id}/contact/ (create) or .../contact/{contact_id} (update).
• Contact delete — DELETE crm/client/{client_id}/contact/{contact_id}.
• Location upsert — POST crm/client/{client_id}/location/ (create) or .../location/{location_id} (update).
• Location delete — DELETE crm/client/{client_id}/location/{location_id}.
• Job upsert — POST JSON to job/. Omit id to create (needs title, agent, and client.billingName or existing client). Pass numeric id in the body to update title, notes, status, assignees, or attached forms.
• Job delete — DELETE with id query param; destructive and idempotent.
• Asset upsert — POST JSON to asset/{schema_id}/ or asset/{schema_id}/{asset_id}; schema-specific columns vary — use extra_fields for schema-defined keys.
• Asset delete — DELETE asset/{schema_id}/{asset_id}.
• Submitted form upsert — POST form/submit/ (create) or form/submit/{submitted_id} (update); pass formID, jobID, and answer fields via extra_fields.

Assign agent to -1 for queue-style jobs any field user can pick up.

Gotchas

• Responses wrap data in a top-level payload key; tools return the unwrapped payload.
• Job and submitted-form list responses are maps keyed by id — tools normalize to items arrays.
• Empty accounts return {} or [] for lists; that is not an auth failure.
• Flat crm/contact/ and crm/location/ paths are not implemented on v2 — always use nested crm/client/{client_id}/... paths.
• API tokens are permission-scoped in Formitize Admin → API → API Tokens; missing module permission surfaces as a payload error message.