CMMS API Reference
This page provides a customer-facing reference structure for CMMS integration surfaces. Use it for integration planning and handoff. Exact endpoint availability, payload shape, and provider mappings depend on the deployed product scope and customer-approved integration mode.
API Surface Map
Prerequisites
| Requirement | Why it matters |
|---|---|
| Deployment scope | Endpoint availability depends on enabled modules and customer integration scope |
| Service identity | API calls need scoped credentials and audit records |
| Data contract | Work-order, asset, status, priority, SLA, and attachment fields must be mapped |
| Ownership rule | Read, draft, handoff, and write-back modes need separate approval |
| Error handling | Retries, partial failures, duplicate prevention, and sync exceptions need a defined policy |
| Test environment | Integration tests should run outside production before go-live |
Source Data Inputs
| Input | Use |
|---|---|
| Work-order payload | Create, update, search, assign, or close work-order records |
| Asset reference | Links work orders to MDM asset and location identity |
| Provider reference | Preserves downstream source system, native ID, and sync state |
| Attachment payload | Links files and evidence to ECM |
| Status transition payload | Supports lifecycle updates and review records |
| Webhook event | Notifies FactVerse or provider systems about changes |
| Error payload | Records rejected fields, provider response, retry state, and owner action |
Common Resource Groups
| Resource group | Use |
|---|---|
| Work orders | Read, create, update, assign, comment, attach, complete, close, reopen, or cancel records |
| Worker execution | Support field task views, progress updates, issue reports, evidence upload, and closeout |
| Operations read model | Read normalized work-order, asset, provider, status, audit, and sync state |
| Attachments and evidence | Link ECM documents, photos, service reports, and closeout packages |
| Provider connectors | Configure and monitor imports, exports, webhooks, and synchronization jobs |
| Status mapping | Maintain provider status, priority, and lifecycle mappings |
| Audit and sync logs | Review imports, handoffs, write-back attempts, retries, and failures |
Example Contract Fields
| Field | Purpose |
|---|---|
common_work_order_id | FactVerse work-order reference |
provider_id | Source CMMS, EAM, contractor system, or integration profile |
source_work_order_id | Native provider work-order ID |
asset_ref | MDM asset, equipment, location, or system reference |
source_status | Provider status value |
common_status | FactVerse lifecycle state |
priority | Normalized priority |
source_priority | Provider priority value |
sla_due_at | Due time used for operations review |
sync_state | Imported, pending, synchronized, retrying, rejected, or stale |
last_synced_at | Latest successful synchronization time |
Webhook and Sync Events
| Event type | Use |
|---|---|
work_order.created | New provider or FactVerse record enters the integration scope |
work_order.updated | Status, assignment, priority, or description changed |
work_order.completed | Field execution is complete and closeout review can begin |
work_order.closed | Closeout state is finalized |
attachment.added | New file or evidence record is available |
sync.failed | Import, handoff, or write-back needs review |
mapping.exception | Field, status, or asset mapping needs steward action |
Event names are planning references. Use runtime discovery and deployed integration documentation to confirm the names available in a customer environment.
Error Handling
| Error class | Review action |
|---|---|
| Authentication | Check service identity, credential, environment, and provider allowlist |
| Authorization | Check scope, provider role, tenant boundary, and action level |
| Validation | Check required fields, enum values, timestamp format, and payload schema |
| Identity | Check asset reference, alias mapping, MDM state, and retired assets |
| Conflict | Check source revision, transition rule, duplicate prevention, and ownership |
| Provider unavailable | Check retry policy, queue state, and customer escalation path |
Expected Output
An API handoff should include:
- endpoint or connector list in scope;
- credential and scope matrix;
- payload fields and examples approved by the customer;
- status, priority, and SLA mapping;
- webhook or synchronization behavior;
- error and retry policy;
- test cases and acceptance criteria.
Validation Checklist
- Read endpoints return expected tenant and provider scope.
- Create or draft behavior produces an audit record.
- Status updates follow approved transition rules.
- Attachments link to ECM and the target work order.
- Failed writes are visible in sync history.
- API tests include authentication, authorization, validation, conflict, and retry cases.