The API described here allows you to automate actions between Mobility Work CMMS and any other system you use, whether you want to be notified when something happened in Mobility Work CMMS (with the webhooks), or update it with information coming from a different source (with API HTTP endpoints).

The use of the API is subject to the terms of services and fair usage.

To be able to access its functionalities, you need an API key that can be provided upon request (see later for details).

Some features are available with a limited usage or only to specific subscription plans. Each endpoint will indicate which subscription plan.

For instance, an endpoint available to all plans:

For instance, an endpoint limited to some plans:

You can request an API key or subscribe to a higher plan:

• by sending an email to sales@mobility-work.com
• by contacting your CSM

Any endpoint listed in this documentation with the label POST, PUT or GET can be called directly to execute a single action.

• POST endpoints will generally create a new object in the CMMS.
• PUT endpoints will generally update information already in the CMMS.
• GET endpoints will allow you to retrieve information from the CMMS.

You'll want to use these endpoints when you want to update information inside Mobility Work CMMS from a different system or application (update your stock or create a task for example), or want to retrieve information from Mobility Work CMMS.

To call one of these endpoints, you'll need to send an HTTPS request to https://api.mobility-work.com followed by the path of the endpoint you want to reach.

Each call to an HTTP endpoint must provide a valid API key for authentication purposes (see Authentication for more information).

For example, if you want to schedule a task, as stated by the endpoint documentation, you'll need to make a POST call to https://api.mobility-work.com/partners/v1/tasks/ providing a valid payload for the call.

Using a cURL call, it would look like:

curl -i -X POST \
  https://api.mobility-work.com/partners/v1/tasks \
  -H 'Api-Key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
  "equipment": <your-equipment-identifier>,
  "description": "My task",
  "startDateTime": "2022-01-11T09:00:00+00:00",
  "endDateTime": "2022-01-11T10:00:00+00:00",
  "allDay": false,
  "assignees": [
    3,
    "john.doe@example.com"
  ]
}'

Every endpoint lists the mandatory and optional parameters you'll need to include in your payload to be able to perform the task.

Note that, for some fields, different formats of data or identifiers can be given, depending on what's the most convenient to you. (For example, in the previous call, you can see that users can be represented by an id or an e-mail address).

For POST and PUT requests, once sent, and if no error was met, the server should respond with a simple 201 http code response, with no payload, unless stated otherwise in the endpoint documentation.

For GET requests, the server should respond with a 200 http code and the payload should contain the requested information in the format provided in the endpoint documentation.

The exact format and headers needed by the endpoints will be discussed later in this documentation.

Any endpoint with the label Event is a webhook. It allows you to be notified when a specific event happens on Mobility Work CMMS when subscribed to it.

You'll need to use webhooks whenever you need a different system or application to be updated with information originating from Mobility Work CMMS.

To be able to use webhooks, you will need to create an HTTPS endpoint that Mobility Work CMMS API will be able to call whenever the event happens, and implement, on your side, the desired behavior upon reception, on your other system or application.

To configure a webhook, you'll then need to go to the integrations settings for your network, select the event you want to subscribe to, and provide the URL of the endpoint the webhook will send the information to.

For example, if you want to be notified for every spare part consumption, you can configure a webhook that will call your endpoint every time it happens, providing the following data:

{
  "_type": "SparePartWasConsumedWebhook",
  "_event": "SparePartWasConsumed",
  "_sentAt": "2022-06-02T14:31:06+00:00",
  "emittedAt": "2023-02-08T23:00:00+00:00",
  "_metadata": "",
  "task": { [...] },
  "sparePart": { [...] },
  "location": { [...] },
  "initiator": { [...] },
  "consumed": {
    "_type": "SparePartConsumption",
    "quantity": 3,
    "previousStock": 116
  },
  "networkId": <your-network-uuid>
}

Your endpoint must then respond with the HTTP code 200, otherwise, the webhook call will be marked as failed and retried afterwards.

Every webhook can be sent with a signature allowing you to verify the source of the call.

To identify resources, you are often given a choice between providing the "native" ID or an "external reference" (also called "item code") for equipments.

Native ID

Native IDs are the internal IDs used and generated by Mobility Work CMMS. The can be numbers or UUIDS. You can retrieve them in the CMMS web app in the URL, but you have no control over them and they can't be modified.

External References

External References are a string of characters you can specify for some of the resources available in the API. These can be automatically generated by the system, but can be modified by you so that it can reflect a more common reference for you, for example the ID the same resource has in a different system you use.

⚠️ For some endpoints, the external reference field can hold a different name, but works as listed before (eg. for Equipments, external references are named item code).

Which one to use

When given the choice (every endpoint can give you different options), it is often more relevant to use the external reference as it is easier for you to keep track of it.

Furthermore, for some endpoints, you are given the choice of the format in which sending the identifier of the resource : when available, you should favor the object format, as it allows to specify the type of the reference you are providing the API and prevent confusion.

For example:

{
  "type": "externalReference",
  "value": "<your-external-reference"
}

All requests day must be sent using JSON format. To make sure the server understands it correctly, add a Content-Type header to your request with the value application/json.

For example:

POST /partners/v1/tasks
Content-Type: application/json
{
  "description": "Replace motor part"
}

While not mandatory, it's highly recommended to provide a User-Agent header which includes your network name.

For instance, for network Factory Inc., using cURL, the request should look like:

POST /partners/v1/tasks
User-Agent: curl/1.2.3 Factory Inc.
[...]

The format of the request is documented for every endpoint and must be followed. All required parameters must be provided. Optional parameters can be omitted.

If a request does not follow the expected schema, a 400 http code response will be returned providing every invalid or missing information in its payload.

Requests can be sent using a minified format or a pretty/beautify format. The API won't make any difference of processing as long as the request is valid. However, it is recommended to use the minified format to reduce bandwidth usage.

It means that:

{
  "description": "Replace motor part"
}

and:

{"description":"Replace motor part"}

hold strictly the same information and can be used interchangeably.

All responses will be sent using JSON format.

If a request is successful, the following status codes can be returned :

• 200 or 201 when the request is treated immediately
• 202 when the request is accepted and will be processed asynchronously

If a request does not follow the expected format, contains invalid data or any other reason that results in an error, a 4xx response code will be returned. The response will provide information about what is missing or invalid.

For example:

{
  "http_status_code": 400,
  "code": "400044",
  "message": "The request payload is not valid.",
  "extended_message": {
    "global_errors": [],
    "property_errors": {
      "/description": [
        {
          "messageKey": "error.payload.min_length",
          "parameters": {
            "min": 3,
            "length": 1
          }
        }
      ],
      "/equipment": [
        {
          "messageKey": "error.payload.equipment.unknown",
          "parameters": {
            "type": "native",
            "value": 99999
          }
        }
      ],
      "/assignees/0": [
        {
          "messageKey": "error.payload.assignees.unknown",
          "parameters": {
            "type": "email",
            "value": "jason.doe@example.com"
          }
        }
      ],
      "/assignees/1": [
        {
          "messageKey": "error.payload.assignees.unknown",
          "parameters": {
            "type": "email",
            "value": "john.doe@example.com"
          }
        }
      ]
    }
  },
  "more_info_url": null
}

informs that:

• the description given doesn't satisfies the min length constraint of 3 characters
• the given equipment has not been found in the network data
• the users with e-mail adresses jason.doe@example.com and john.doe@example.com are not members of the network

and:

{
  "http_status_code": 401,
  "code": "401001",
  "message": "Authentication error",
  "extended_message": {
    "global_errors": [
      {
        "messageKey": "Invalid Api Key.",
        "parameters": {}
      }
    ],
    "property_errors": {}
  },
  "more_info_url": null
}

informs that the given credentials (API key) are not valid.

⚠️ If the http response code is 5xx, the error is on the Mobility Server side, and should not happen. However, if that happens to you, please re-try the exact same call a few minutes later, or contact the support for help at help@mobility-work.com.

The documentation will always show JSON using a pretty/beautify format for readability. However, the API will always returns using a minified format to reduce the response size.

Some API tools like Postman or Insomnia can show responses in pretty/beautify format by default.

Every HTTP request must be performed providing a valid API Key. Each API Key is associated to a single network providing an access to all features available on the network subscription plan.

To authenticate against the API endpoints with your API key, you need to send your API key using the Api-Key HTTP header.

For example :

POST /partners/v1/tasks
Api-Key: 913a8f7cef6ff084f1635511b9c7d07c3bab2816
[...]

To get an API Key, send an email to sales@mobility-work.com or contact your CSM.

The documentation is also available on every endpoints in the security section under the section Security/ApiKey.

Note that when calling any endpoint of this documentation using the request tool in the right side-bar, the API Key field needs to be filled with a valid API key.

API Key Management

Your API Key must remain completely secret and taken care of as any other authentication secret, like a password. It is considered as a major vulnerability if it were to be divulgated to an unauthorized party.

If you think your API key is compromized, contact your CSM or Support directly to invalidate your API key and get a new one that will need to be provided for your API calls instead of the compromized one.

When using webhooks, you'll likely need to be sure the calls made to your endpoint come from an authorized source.

To answer this necessity, every webhook call performed by Mobility Work CMMS API contains a signature that allows your endpoint to verify the origin of the request it received, as long as you have enabled the feature by setting a secret key when configuring your webhook.

The signature is sent using the HTTP header X-MW-Signature and provides a timestamp, a nonce, and the signature allowing you to compute it on your side, compare it, and make sure it originated from Mobility Work.

For example:

POST <your-endpoint-url>
Api-Key: t=1660338149,nonce=752c14ea195c460bac3c3b7896975ee9fd15eeb7,signature=0b218e3166231b8b44ed11b5401d4de5e7e79d3e7d51415338a3e76df29372ba
[...]

The details on how to use it and some examples of implementation are provided on every endpoint documentation under the section Security/WebhookSigningKey.

When deploying your integrations with the Mobility Work API, it is always a good idea to keep logs of the calls you made to the API (and responses sent by our server) or the calls the API sent to your webhook endpoints. It allows you to track directly errors that could have happened, and be able to fix any problem that have been found. And if that's an error on the API side, it allows you to send us information that are critical to resolve the issue.

When you want to update several resources, you should always do it in the least amount of requests possible. Each bulk update API endpoint will give you the maximum of resources you can include in your request.

If the number of updates you want to make is lower than this number, you should do it in just one request. If it's greater than it, split it in different requests.

If, before deploying your integrations with our API on your production data, you need a testing environment, contact your CSM who will be able to set-up a sandbox network to experiment on before using your real network data.

If you have any issue with the API, the first step is to analyze the response to your request sent by the API. As described in "API Responses & Errors", if your request is malformed, you'll have all the necessary information to debug your request and be able to fix it.

Tools like Postman or Insomnia can greatly help you during the debug phase as they allow you to send your requests and see the responses in a more human readable way and provide tooling to make it easy for you to sens requests.

If, despite the response message, you have any issue with the API, you can contact the support. Note that, when contacting support, it is deeply appreciated to provide any log, request or response (including headers but without the API key) to help us resolve your issue in the fastest way. If you're not able to provide these information to us, at least try to send us the Request-Id returned in the response HTTP headers.

We list here recent changes made to the API or its documentation.

Anything related to equipments and spare parts (including stock management, etc.).

Anything related to maintenance operations (e.g. task, activities, maintenance plans, etc.).

Anything related to network management.

Webhooks allow you to be notified in real-time of any events occurring in the application.

A webhook must have been configured with that event to receive it. Administrators can configure webhooks here. If you want to test webhooks, you can use a service like RequestBin.com to receive webhooks and inspect it.

If the webhook fails (http code bigger than 399), the call to the webhook is retried twice. If the call is still in error, an e-mail is sent.