Version: latest

• OpenAPI Spec

Mobility Work Public API

Introduction

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:

Starter	Premium	Ultimate
✔️	✔️	✔️

For instance, an endpoint limited to some plans:

Starter	Premium	Ultimate
❌	✔️	✔️

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

• by sending an email to [email protected]
• by contacting your CSM

Quickstart

HTTP endpoints

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,
    "[email protected]"
  ]
}'

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.

Webhooks

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.

API Guidelines

Identifiers

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"
}

Sending a Request

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.

API Responses & Errors

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": "[email protected]"
          }
        }
      ],
      "/assignees/1": [
        {
          "messageKey": "error.payload.assignees.unknown",
          "parameters": {
            "type": "email",
            "value": "[email protected]"
          }
        }
      ]
    }
  },
  "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 [email protected] and [email protected] 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 [email protected].

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.

Security

Authentication

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 [email protected] 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.

Webhooks Signature

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.

Best Practices

Logs

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.

Bulk update

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.

Sandbox

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.

Troubleshooting and Help

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.

Changelog

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

Date	Modification made to the API
2025-03-26	Add API to report an activity on a task and docs
2025-03-21	Add API to mark a task as completed and docs
2024-10-01	Add API maintenance plan endpoint and docs
2024-07-17	Add new API to search for tasks
2024-06-13	Add new API to recount spare parts stock and mark the old one as deprecated
2024-04-18	Add new API to create equipments
2024-04-09	Add spare part cost center and location to spare parts canceled consumption webhook
2024-03-08	Add new webhook for spare parts canceled consumption
2024-02-29	Add new api to relocate spare parts
2024-02-28	Added tags of task on sparePartWasConsumed webhook
2024-02-23	Add new api to create storage locations
2024-02-23	New sections for the API documentation
2024-02-08	Added tags and requiredSpareParts fields for Tasks webhooks
2023-12-21	More context has been added to error messages

Authentication

API Key: ApiKey

Every requests to the API must be authenticated. You must provide the API Key to authenticate as an HTTP header Api-Key.

For instance:

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

Each API Key is associated to a single network providing an access to all features available on the network subscription plan.

To get an API Key, send an email to [email protected] or contact your CSM.

Security Scheme Type:	apiKey
Header parameter name:	Api-Key

API Key: WebhookSigningKey

If you've created a secret key when creating your webhook, every webhook call on your endpoint will provide a signature so that you can verify the origin of the request and ensure it has been made by the configured webhook and not from any other source.

In the X-MW-Signature HTTP header of the request to your endpoint you'll find the signature information. It contains a string of characters formatted as following:

t={timestamp},nonce={nonce},signature={signature}

• {timestamp}: it is the Unix timestamp of when the request was created (ex: 1660338149)
• {nonce}: it is a random string of characters (ex: 752c14ea195c460bac3c3b7896975ee9fd15eeb7)
• {signature}: the signature computed from your secret key, the nonce and the timestamp (ex: 0b218e3166231b8b44ed11b5401d4de5e7e79d3e7d51415338a3e76df29372ba)

When you receive a signed request, you can retrieve all these information to compute the same signature on your end and check if the signature provided and the one you've computed match.

How to compute the signature from a signed request?

First you need to create a string of characters concatenating the timestamp, the nonce and the payload in that order, separated by a dot (.).

Then, using the HMAC method, you'll generate the keyed hash of the previously created string of characters using your secret key.

You can now compare the signature you received and the one you've just computed.

For example in php:

$requestSignature = '<the signature received>';

$content = sprintf('%s.%s.%s', $timestamp, $nonce, $payload);
$signature = hash_hmac('sha256', $content, $secretKey);

if ($signature === $requestSignature) { /* the request is from the webhook */ }
else { /* You should not accept this request */ }

What to do with the nonce and the timestamp?

The nonce is to be considered as the identifier of the webhook request. You can use it to ignore requests with the same nonce as a previous request you've already processed (This could happen if a webhook system would allow to resend past requests for example).

The timestamp allows you you to know when the request was made. If you were to receive a request with a timestamp too old (maybe from 1 hour ago) for your system, you could filter on that value as the event included might already be stale.

You must also keep in mind that either of this two values (nonce and timestamp) can allow you to prevent your system from being corrupted by Replay Attacks (a Replay Attacks describes a type of attack where the attacker intercept and re-send the same request multiple times to the endpoint).

Using the nonce to reject a request because you recognize it from a previous one or using a (short) time-based rejection rule using the timestamp can help you identify these requests and ignore them.

General Information

As all the security management is made on the receiving end (your endpoint), you can completely ignore the signature, nonetheless we strongly advise you to use it to prevent any mis-usage of your endpoint from a third party.

Security Scheme Type:	apiKey
Header parameter name:	X-MW-Signature

License

proprietary