Overview

The Mobaro API lets other systems create Assignments in Mobaro, update them, move them through their states and delete them. Typical uses are turning tickets from a helpdesk or maintenance system (CMMS) into Assignments, closing an Assignment when the work order is closed elsewhere, and exporting Assignments for reporting.

This article is the integration guide. For how Assignments work in Mobaro, see Understanding the Assignments module. To react when Assignments change, use webhooks: see Using webhooks in Mobaro.

At a glance
Who can do this	An integration with an API key. Reading works with a Read-only key; creating, updating and deleting need a key that isn't Read-only.
Where	`/api/customers/assignments` and `/api/customers/assignmentdefinitions`. Keys: Configuration › API › API Keys
Works on	Public API. Assignments created or changed through the API show in the Backend (web) and Mobile app like any other.
Availability	API access, enabled per organization by Mobaro — ask your CSM

Before you start

Collect the IDs you'll send, with their prefixes:

What	Where to get it
Location (required)	`GET /api/customers/locations` → `locations/…`
Assignees	`GET /api/customers/users` or `/usergroups` → `users/…`, `usergroups/…`
Assignment Definition, its states, categories and priorities	`GET /api/customers/assignmentdefinitions`. Each definition lists its `states` (with `type` Initial, Step or Final), `categories` and `priorities`.
Asset	`GET /api/customers/assets`. It must be on the Assignment's Location.
Pictures	`POST /api/customers/files/create` (multipart form) → `files/…`

See Understanding IDs in Mobaro and Using Assignment Definitions.

Create an Assignment

Send POST /api/customers/assignments. The response is the new ID, for example {"id": "assignments/1847225-A"}. Assignees are notified just as when an Assignment is created in the Backend.

{
  "name": "Replace lap bar sensor, row 3",
  "target": "locations/345678-A",
  "description": "Reported by ticket 4711",
  "assignees": ["usergroups/2233-A"],
  "definition": "assignmentdefinitions/123-A",
  "definitionPriority": "assignmentdefinitionpriorities/45-A",
  "end": "2026-10-02T16:00:00Z",
  "externalId": "TICKET-4711"
}

Field	What to send
`name`, `target`	Required. `target` is the Location ID.
`assignees`	User and User Group IDs. Left out, the Assignment has no assignee.
`definition`	The Assignment Definition. Left out, you create a standard Assignment.
`definitionPriority`, `definitionCategories`	With a definition: a priority ID and category IDs from that definition. IDs that aren't in the definition are dropped.
`priority`, `categories`	Without a definition: `true` for High priority, and Assignment Category names.
`start`, `end`	UTC date-times. They're dropped when the chosen priority's Time frame policy is Disabled.
`asset`	An Asset on the target Location; otherwise it's dropped.
`attachments`	File IDs. Anything that isn't a `files/…` ID is dropped.
`externalId`, `description`, `descriptionIsReadonly`	Your ticket ID, the description, and `true` to stop people editing the description in the Backend and app.

ℹ️ Note: The API doesn't fill in a definition's default priority or deadline, and doesn't enforce a Required Time frame policy. Send definitionPriority, start and end if the Assignment needs them. A new Assignment starts in its definition's Initial state, or Created for a standard Assignment.

Change the state

Send PUT /api/customers/assignments/{id} with a stateChange. The justification description is saved as the resolution when you move the Assignment to a Final state (or Finished), or as the reason when you reopen it.

{
  "stateChange": {
    "state": "assignmentdefinitionstates/678-A",
    "justification": {
      "description": "Sensor replaced and tested",
      "attachments": ["files/abc123"]
    }
  }
}

Assignment with a definition: state is one of that definition's state IDs.
Standard Assignment: state is "Created", "Started" or "Finished", spelled exactly like that.

⚠️ Heads-up: Sending "Created", "Started" or "Finished" to an Assignment that has a definition doesn't finish it: it moves it to the definition's Initial state, and reopens it if it was finished. Always use state IDs for these Assignments.

The API acts as a Super User, so a definition's Who can resolve setting doesn't apply, and Mobaro doesn't check whether a state requires documentation: send a description anyway. For what states mean, see Understanding assignment statuses. PUT /{id}/solve is deprecated; use stateChange.

Update and delete

The same PUT changes other fields. Only the fields you send change; assignees replaces the whole list. Moving an Assignment to another target drops its Asset unless the Asset is on the new Location.

DELETE /api/customers/assignments/{id} deletes it. Add ?comment=… to record why. Deleted Assignments aren't returned by the API; to track deletions, use the Assignments webhook.

Read Assignments

GET /api/customers/assignments returns up to 128 per page. Filter with Status, Definitions, DefinitionStates, Locations, LocationGroups, Priority and CreatedAfter / UpdatedAfter (and …Before); see Mobaro API parameter reference. You can also get one by its ID or externalId. PUT and DELETE need the Mobaro ID, so look it up by externalId first. Each Assignment includes its status, definitionState, assignees and, once finished, its resolution. GET /api/customers/assignments/{id}/activities returns its history, including comments.

Best practices

Set externalId to your ticket number, look Assignments up by it, and store the returned id for updates.
Read the definition's states once and map them to your system's statuses.
Give each integration its own API key and check who changed what in the activity history.
Use webhooks instead of polling to hear about changes made in Mobaro.

Frequently asked questions

Is there an API call to close an assignment?

Yes. Send PUT /api/customers/assignments/{id} with a stateChange: a Final state ID for Assignments with a definition, or "Finished" for standard ones. Add a justification description as the resolution.

How do I add a comment to an assignment through the API?

You can't. There's no endpoint for Assignment comments. You can read existing comments with GET /api/customers/assignments/{id}/activities. Endpoints outside /api/customers don't accept API keys.

Can the API return deleted assignments?

No. Use an Assignments webhook with the Deleted event to track deletions.

Can I get the photos from an assignment?

Not the images themselves. attachments lists file IDs, and GET /api/customers/files/{id} returns each file's type, size, categories and comments, not its content.

Our integration closed assignments, but they show as created again. Why?

It probably sent "Finished" to Assignments that use a definition. That moves them to the Initial state. Send the ID of a Final state instead.

Creating and updating Assignments through the API