Formitize

Formitize

Formitize is a field-service operations stack: CRM clients and sites, schedulable jobs, job type templates, sales quotes tasks and leads, asset registers, mobile form templates, scheduler and workflow definitions, and submitted inspection reports. Australian accounts typically use the AU service host.

Hierarchy

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

Sales (when enabled): quotes, tasks, and pipeline leads — not the legacy CRM lead list (that surface is not implemented on the current API version).

Operations: job type templates, scheduler calendar, workflow definitions, field users and teams, qualifications, and scheduler resources (resources require explicit permission on the connected credential).

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. List or fetch by optional contact_id / location_id; upsert and delete on the same client-scoped paths.
3. Jobs — list open jobs (optional status filter) or fetch one job by id for status, assignee, due date, and attached forms. Use job history for audit timeline on a known job_id.
4. Job types — list templates before interpreting recurring work.
5. Sales — list or fetch quotes (quote_id), tasks (task_id), and CRM leads (lead_id) with pagination; upsert and delete on the same resources; use extra_fields for module-specific columns.
6. Scheduler & workflows — scheduler entries for calendar dispatch; workflow definitions and workflow templates; upsert/delete when automations are managed via API.
7. Field users & qualifications — agents and teams for assignment; qualifications list and upsert/delete when Admin exposes them on the token.
8. Resources — list and manage scheduler resources when the credential includes Resources permission.
9. Webhooks — list and configure outbound job webhooks when integrations are enabled.
10. Assets — list asset schemas (optional schema_id for one definition), then list or fetch assets within a schema id.
11. Forms — list form templates; search submitted forms by query, form_id, and page, or fetch by submitted_id / job_id; upsert or delete submissions.
12. Lookup databases — list database names, then list/upsert/delete rows within a named lookup database.
13. Invoices — list, fetch, upsert, and delete invoice summaries when billing modules are enabled.

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 — create with billingName; update by client id. Deactivate via dedicated deactivate client or extra_fields status: inactive.
• Contact upsert — create or update under a parent client_id.
• Contact delete — delete by client id + contact id.
• Location upsert — create or update under a parent client_id.
• Location delete — delete by client id + location id.
• Job upsert — omit id to create (needs title, agent, and client.billingName or existing client). Pass numeric id to update title, notes, status, assignees, or attached forms.
• Job delete — destructive and idempotent by job id.
• Job type upsert — create with title or name; delete by job type id.
• Quote / task / lead upsert — create or update by resource id; delete by id query param.
• Workflow / scheduler / qualification / resource — create and delete when modules are enabled on the token.
• Invoice upsert — create or update invoice rows; delete by id.
• Lookup row upsert — create or update rows in a named lookup database; delete by row id.
• Webhook upsert — register callback URL; delete by webhook id.
• Submitted form delete — delete by submitted form id.
• Asset upsert — create or update within an asset schema; schema-specific columns vary — use extra_fields for schema-defined keys.
• Asset delete — delete by schema id + asset id.
• Submitted form upsert — create or 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 top-level contact and location lists are not implemented — always use client-scoped contact and location reads and writes.
• Pipeline leads use the sales lead tools — do not use the legacy CRM lead list.
• Resources require explicit permission on the credential; otherwise the service returns a no-permission error.
• Credential permissions are scoped in Formitize Admin; missing module permission surfaces as a payload error message.