Overview
Connect Mobaro to a maintenance, HR or other system without creating duplicate records or overwriting the wrong fields. This guide uses an Assignment sync as an example; your integration owns its mapping, conflict handling and recovery.
At a glance |
|
Who can do this | Integration developers; writes need a key without Read-only |
Where | Your integration and |
Works on | Public API; Backend (web) for setup |
Availability | API access, enabled per organization by Mobaro — ask your CSM |
⚠️ Heads-up: API keys have organization-wide access. A read-only key blocks writes; a full-access key acts with Super User access. Use a dedicated server-side key and confirm the intended test organization. See API access scopes.
Design the synchronization
1. Choose the supported operations
List each read and write your workflow needs, then check the endpoint overview and live API documentation. Only /api/customers is the supported public API. Do not substitute an internal Backend endpoint for a missing operation.
Authenticate with x-api-key; send Content-Type: application/json for JSON bodies. APIs and webhooks have separate availability. Polling is valid when webhooks are not enabled or are not part of your integration.
2. Assign ownership to each field
Example field | Owner | Integration rule |
External ticket ID | Other system | Store as |
Description | Other system | Update only when the source description changes. |
Assignees | Mobaro team | Do not include in routine external updates. |
Status | Agreed workflow | Map each direction explicitly; define who resolves conflicts. |
Make this agreement before coding. A timestamp alone does not establish which system has authority. If both sides may edit a field, define a deterministic rule or send conflicts for review.
3. Create a durable identity map
Store the source ID, organization, Mobaro ID, last applied values and last successful operation in your integration. For Assignments, GET /api/customers/assignments/{id} can look up an External ID. Use the returned Mobaro ID for updates and deletes. See Understanding IDs and the Assignment API guide.
Treat lookup-then-create as a workflow, not an atomic upsert guarantee. Serialize work for the same source record. If a create times out, reconcile the outcome before trying again; concurrent workers can both see a missing record.
Apply changes safely
4. Map the Assignment state
Read GET /api/customers/assignmentdefinitions and map the relevant definition’s state IDs and type values (Initial, Step, Final). For a standard Assignment, the status names are Created, Started and Finished.
🛑 Critical: For an Assignment with a definition, send the intended definition state ID. Sending a standard status name can return it to its Initial state and reopen finished work. Check the definition and read the Assignment back after the change.
PUT https://app.mobaro.com/api/customers/assignments/1847225-A
x-api-key: YOUR_API_KEY
Content-Type: application/json
{
"stateChange": {
"state": "assignmentdefinitionstates/678-A",
"justification": {
"description": "Work completed and verified in the source system.",
"attachments": []
}
}
}The state ID is fictional: replace it with an allowed state from your definition. Send only fields your integration owns. An Assignment update changes supplied fields; supplied collections such as assignees replace the whole collection. Do not send an empty list to mean “leave unchanged.”
5. Prevent changes from bouncing back
Compare the desired values with the latest known values before writing. Record what your integration applied. When the same values return through a webhook or polling, recognize them as already synchronized and skip another write. Do not rely on event timing alone to identify your own changes.
Serialize changes per mapped record. Before a write, re-read fields that affect your conflict rule. This reduces accidental overwrites but is not a server-side lock or compare-and-swap guarantee. Keep unresolved conflicts visible to an owner.
6. Handle retries and deletions
Situation | Response |
400 / 401 / 403 / 404 | Inspect the response and endpoint context. Correct validation, identity or access; do not blindly retry. |
429 or temporary failure | Use capped backoff and jitter. For writes, first establish whether the change already applied. |
Timeout after a create | Mark the outcome unknown; inspect the source mapping and destination before any repeat. |
Deletion event | Apply the agreed archive/remove policy. A later GET may return 404; retain a deletion marker to prevent old events recreating data. |
API requests are limited to 10 per second per key; some writes have lower limits. Read errors and retries for endpoint exceptions. Assignments lists exclude deleted records, so polling alone is not a deletion feed.
For webhook integrations, validate signatures, save accepted work durably and handle duplicates and out-of-order events. Acknowledge within five seconds. See Using webhooks. For API-only integrations, define a separate reconciliation process; webhook retry behavior does not explain an API-only failure.
Test both directions
Create once, repeat the same input and confirm no duplicate.
Update a field owned by each system and verify the other side does not overwrite it.
Finish a defined Assignment and confirm the Final state survives the next sync.
Simulate a timeout after a successful write and verify that recovery does not create another record.
Replay an older event after a newer change or deletion and verify the agreed result.
Compare source and destination records periodically; log unresolved differences.
Best practices
Keep mappings and checkpoints in durable storage.
Log record IDs, operation outcomes and correlation IDs without credentials or unnecessary personal data.
Use a named integration owner and a documented pause/recovery procedure.
Frequently asked questions
Our integration closed an Assignment, but it reopened. Why?
Check the exact write payload and Assignment definition. A standard status sent to a defined Assignment can move it to the Initial state. Also check later writes from either system. The symptom alone does not identify which request caused it.
Does an External ID make a create request safe to repeat?
No. Do not treat External ID as an idempotency guarantee. Keep a durable mapping, serialize work for each source record and reconcile unknown outcomes before creating again.
Can the integration add Assignment comments?
No public Assignment-comment write endpoint is available. A state change can include a justification description. See Creating and updating Assignments.
Do we need webhooks for a two-way integration?
No. You can poll supported endpoints. Webhooks help detect supported changes and deletions, but require separate availability and a receiver. Choose the transport explicitly and design recovery for it.