Overview
Use the Assignments API when work originates in another system but needs to be carried out or followed up in Mobaro. Begin with a small mapping between the external work order and its Mobaro Assignment.
Agree which system owns the title, assignees, deadlines and status before enabling updates in both directions. This guide covers that integration design; creating and updating Assignments through the API provides the field reference.
At a glance |
|
Who can do this | Integration developers; Organization › Administrate is required to create the API key. |
Where | Configuration › API › API Keys; your integration service |
Works on | Public API |
Availability | Contact your CSM |
💡 Why this matters: Explicit record and field ownership reduces duplicate tasks and stops one system from repeatedly undoing changes made in the other.
Define the mapping
1. Confirm access and identifiers
Use a dedicated API key with the write access needed for Assignment changes. Keep it server-side. Map external site and equipment references to real Mobaro Location and Asset IDs; display names alone are not a reliable key.
2. Choose a workflow
Decide whether the Assignment uses the standard workflow or an Assignment Definition. If using a Definition, fetch and map its actual state IDs. Record which external states correspond to its initial and final states.
3. Assign field ownership
Field | Example ownership decision |
Title and description | External system supplies the original work request |
Assignees | Mobaro supervisor maintains the working team |
Completion state | One agreed system records completion; the other follows |
These are example decisions, not built-in synchronization rules. Implement only the updates you intend to own.
Create and link the Assignment
Send a POST /api/customers/assignments with the required name and target Location, plus the selected Definition and other intended fields. Include an externalId for traceability. Save the returned Mobaro ID alongside the external work-order ID.
Do not assume a repeated POST becomes an update because the same external ID is present. If a create request times out, check for the Assignment before retrying. The API can look up an Assignment by its external ID, but your integration must prevent duplicate creates and retain its ID mapping.
Use the Mobaro Assignment ID for subsequent updates. Avoid sending a complete stale copy back on every change: send only the fields your integration owns. Updating assignees replaces that list; it does not append one person.
Map completion deliberately
Use stateChange when changing state. For a Definition-based Assignment, send the intended Definition state ID. Standard Finished is not a substitute for a Definition’s final state and can instead return the Assignment to its initial state.
🛑 Critical: API writes act with elevated organization access and do not enforce all user-interface workflow checks. Your integration must enforce the intended authority, completion evidence and Definition rules before closing work. Do not use an API state change to bypass the site’s sign-off procedure.
Supply intended priority and deadline explicitly where needed. API creation does not apply every default or required-timeframe rule from the interactive form. See API workflow differences.
Follow later changes
Use webhooks or a suitable polling process to learn about changes, then update the linked record. Make event handling repeatable and prevent a change sent by one system from bouncing back indefinitely.
Decide what deletion means in both systems. Deleted Assignments are not returned by the normal list. Treat deletion events separately and retain enough mapping to identify the external record. Do not delete a work order merely because one filtered API response did not contain it.
Before wider use, test creation, a lost response and retry, reassignment, completion, reopening and deletion with agreed test records. Confirm the final state in both systems.
Best practices
Store both identifiers as soon as creation succeeds.
Use one writer per shared field unless you have an explicit conflict rule.
Keep credentials and operational test records out of examples and logs.
Frequently asked questions
How do I mark an Assignment as finished through the API?
Update stateChange. Standard Assignments use the standard state; Definition-based Assignments need the correct final state ID. See changing Assignment state.
Can the API add a comment to an Assignment?
No. The current public Assignment API can read activities but does not provide an endpoint for posting comments. See supported Assignment operations.
Can I retrieve deleted Assignments through the API?
Not through the normal Assignment list or lookup. Use deletion events and your stored mapping for synchronization. See webhooks.