Mobility Work Public API (latest)

Download OpenAPI specification:Download

License: proprietary

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:

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,
    "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.

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": "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.

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 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.

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

⚙️ Equipments & Spare parts

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

Create spare part(s)

Starter Premium Ultimate
✔️ ✔️ ✔️

Creation of spare part(s)

⚠️ The request is processed in background. It can takes up to several minutes to see the change if there is a lot of changes.

Unit price amount must be passed as an integer in the lowest unit of the currency. For example, EUR and USD have a cent unit, 10 EUR = 1000 cents, 10 USD = 1000 pennies.

⚠️ A maximum of 10.000 creations can be processed in a single request. You need to split in several requests if you have more.

SecurityApiKey
Request
Request Body schema: application/json
Array ([ 1 .. 10000 ] items)
externalReference
required
string
name
required
string [ 3 .. 255 ] characters
description
string [ 3 .. 3000 ] characters
required
object
required
object
minimumStock
integer >= 0
maximumStock
integer >= 0
gtin
string^[0-9]{8,18}$
costCenter
string
Responses
202

Request accepted (e.g. all changes will be processed as soon as possible)

400

Request contains invalid data or does not have all required data

401

Missing or invalid Api Key (e.g. revoked or non-existent)

403

Access denied

post/partners/v1/spare-parts
Request samples
application/json

Multi spare part creation, one with the minimum data and another with all available information

[
  • {
    },
  • {
    }
]
Response samples
application/json
null

Update stock of spare partsDeprecated

Starter Premium Ultimate
✔️ ✔️

Update all spare parts stock (e.g. inventory) at once. Stock amount will replaced by the given quantity. If multiple spare parts exists with the same article code, then the stock will be replaced on every spare parts with that article code.

⚠️ The request is processed in background. It can takes up to several minutes to see the change if there is a lot of changes.

The spare part identifier can be provided in two way:

  • as a simple string
  • or a complex typed identifier

For instance, that format:

[
  {
    "id": "MW-417304e0-2ff0-410d-a7cd-de20439140c8"
  }
]

is equivalent to:

[
  {
    "id": {
      "type": "externalReference",
      "value": "MW-417304e0-2ff0-410d-a7cd-de20439140c8"
    }
  }
]

Article code is automatically generated when a spare part is referenced on the CMMS. You can replace it by your own identifier in the UI or by using the API to update spare parts attributes.

⚠️ A maximum of 10.000 stock changes can be processed in a single request. You need to split in several requests if you have more changes.

SecurityApiKey
Request
Request Body schema: application/json
Array ([ 1 .. 10000 ] items)
required
string or object (SparePartIdentifier)
quantity
required
integer >= 0

The new stock value

Responses
202

Request accepted (e.g. all changes will be processed as soon as possible)

400

Request contains invalid data or does not have all required data

401

Missing or invalid Api Key (e.g. revoked or non-existent)

403

Subscription plan does not allow to use that API

put/partners/v1/spare-parts/stock
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
null

Update spare part(s) information

Starter Premium Ultimate
✔️ ✔️ ✔️

Update all spare part(s) by replacing information with the provided information.

⚠️ The request is processed in background. It can takes up to several minutes to see the change if there is a lot of changes.

Omit the property if you do not want to make any changes to the attribute. For instance, the following request will only update the spare part name:

[
  {
    "id": {
      "type": "externalReference",
      "value": "c6d6f829-6c36-30cc-93be-d5202ca28aa4"
    },
    "name": "Rotor"
  }
]

To unset an attribute, set it to null. For instance, the following request will remove the minimum stock:

[
  {
    "id": {
      "type": "externalReference",
      "value": "c6d6f829-6c36-30cc-93be-d5202ca28aa4"
    },
    "minimumStock": null
  }
]

Unit price amount must be passed as an integer in the lowest unit of the currency. For example, EUR and USD have a cent unit, 10 EUR = 1000 cents, 10 USD = 1000 pennies.

For instance, if one spare part has a unit price of €35.00 and another has a unit price of $499.99, the request to update unit price should be:

[
  {
    "id": {
      "type": "externalReference",
      "value": "c6d6f829-6c36-30cc-93be-d5202ca28aa4"
    },
    "unitPrice": {
      "amount": 3500,
      "currency": "EUR"
    }
  },
  {
    "id": {
      "type": "externalReference",
      "value": "d8194f1f-050d-4f74-a592-2d541e6127aa"
    },
    "unitPrice": {
      "amount": 49999,
      "currency": "USD"
    }
  }
]

⚠️ A maximum of 10.000 updates can be processed in a single request. You need to split in several requests if you have more changes.

SecurityApiKey
Request
Request Body schema: application/json
Array ([ 1 .. 10000 ] items)
required
string or object (SparePartIdentifier)
object
name
string [ 3 .. 255 ] characters
description
string [ 3 .. 3000 ] characters
externalReference
string
minimumStock
number >= 0
maximumStock
number >= 0
replenishmentLot
number >= 0

minimum quantity of replenishment

gtin
string^[0-9]{8,18}$
Array of objects
Array of objects

A list of tags changes to apply to the spare part.

costCenter
string
Responses
202

Request accepted (e.g. all changes will be processed as soon as possible)

400

Request contains invalid data or does not have all required data

401

Missing or invalid Api Key (e.g. revoked or non-existent)

403

Access denied

post/partners/v1/spare-parts/attributes
Request samples
application/json

update on several spare parts with different fields updated and different way to specify the identifier

[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]
Response samples
application/json
null

Bulk Stock Movement

Starter Premium Ultimate
✔️ ✔️ ✔️

Update all spare parts stock (e.g. inventory) at once. Stock amount will replaced by the given quantity. If multiple spare parts exists with the same article code, then the stock will be replaced on every spare parts with that article code.

⚠️ The request is processed in background. It can takes up to several minutes to see the change if there is a lot of changes.

The spare part identifier can be provided in two way:

  • as a simple string
  • or a complex typed identifier

For instance, that format:

[
  {
    "id": "MW-417304e0-2ff0-410d-a7cd-de20439140c8"
  }
]

is equivalent to:

[
  {
    "id": {
      "type": "externalReference",
      "value": "MW-417304e0-2ff0-410d-a7cd-de20439140c8"
    }
  }
]

Article code is automatically generated when a spare part is referenced on the CMMS. You can replace it by your own identifier in the UI or by using the API to update spare parts attributes.

⚠️ A maximum of 10.000 stock changes can be processed in a single request. You need to split in several requests if you have more changes.

SecurityApiKey
Request
Request Body schema: application/json
Array ([ 1 .. 10000 ] items)
required
string or object (SparePartIdentifier)
required
object
Responses
202

Request accepted (e.g. all changes will be processed as soon as possible)

400

Request contains invalid data or does not have all required data

401

Missing or invalid Api Key (e.g. revoked or non-existent)

403

Subscription plan does not allow to use that API

post/partners/v1/spare-parts/movements/bulk
Request samples
application/json
[
  • {
    },
  • {
    },
  • {
    }
]
Response samples
application/json
null

Create equipment(s)

Starter Premium Ultimate
✔️ ✔️ ✔️

Creation of equipment(s)

⚠️ The request is processed in background. It can takes up to several minutes to see the change if there is a lot of changes.

⚠️ A maximum of 10.000 creations can be processed in a single request. You need to split in several requests if you have more.

SecurityApiKey
Request
Request Body schema: application/json
Array ([ 1 .. 10000 ] items)
name
required
string [ 1 .. 255 ] characters
description
null or string
Default: null
globalTradeItemNumber
null or string
Default: null
costCenter
null or string
Default: null
itemCode
null or string
Default: null
private
boolean
Default: true
tags
Array of strings
Default: []
Array of objects
Responses
202

Request accepted (e.g. all changes will be processed as soon as possible)

400

Request contains invalid data or does not have all required data

401

Missing or invalid Api Key (e.g. revoked or non-existent)

403

Access denied

post/partners/v1/equipments
Request samples
application/json

Multi equipments creation

[
  • {
    }
]
Response samples
application/json
null

Update equipment(s) information

Starter Premium Ultimate
✔️ ✔️

Update all equipment(s) by replacing information with the provided information.

⚠️ The request is processed in background. It can takes up to several minutes to see the change if there is a lot of changes.

The equipment identifier can be provided in two way:

  • as a simple string
  • or a complex typed identifier

For instance, that format:

[
  {
    "id": 2507
  }
]

is equivalent to:

[
  {
    "id": {
      "type": "native",
      "value": 2507
    }
  }
]

Omit the property if you do not want to make any changes to the attribute. To unset an attribute, set it to null.

⚠️ A maximum of 10.000 updates can be processed in a single request. You need to split in several requests if you have more changes.

SecurityApiKey
Request
Request Body schema: application/json
Array ([ 1 .. 10000 ] items)
required
integer or string or object (equipment_identifier)
name
string [ 3 .. 255 ] characters
description
string [ 3 .. 3000 ] characters
gtin
string^[0-9]{8,18}$
costCenter
string [ 3 .. 255 ] characters
itemCode
string [ 1 .. 255 ] characters
tags
Array of strings

tags codes

Array of objects
Responses
202

Request accepted (e.g. all changes will be processed as soon as possible)

400

Request contains invalid data or does not have all required data

401

Missing or invalid Api Key (e.g. revoked or non-existent)

403

Access denied

post/partners/v1/equipment/attributes
Request samples
application/json

update all info of an equipment and clear custom fields of another equipment

[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]
Response samples
application/json
null

Create storage location(s)

Starter Premium Ultimate
✔️ ✔️

Creation of storage location(s)

⚠️ The request is processed in background. It can takes up to several minutes to see the change if there is a lot of changes.

⚠️ A maximum of 10.000 creations can be processed in a single request. You need to split in several requests if you have more.

SecurityApiKey
Request
Request Body schema: application/json
Array ([ 1 .. 10000 ] items)
name
required
string [ 1 .. 255 ] characters ^(?!$)\w
additionalProperties
any
Responses
202

Request accepted (e.g. all changes will be processed as soon as possible)

400

Request contains invalid data or does not have all required data

401

Missing or invalid Api Key (e.g. revoked or non-existent)

403

Access denied

post/partners/v1/locations/create/bulk
Request samples
application/json
[
  • {
    },
  • {
    },
  • {
    }
]
Response samples
application/json
null

Relocate spare part(s)

Starter Premium Ultimate
✔️ ✔️

Relocate spare parts from a location to another one

⚠️ The request is processed in background. It can takes up to several minutes to see the change if there is a lot of changes.

⚠️ It is not possible to define a quantity to transfer. All stock from the source location is moved to the target location ⚠️ It is only possible to relocate spare parts to existing locations in the network. If the locations do not exist, please use the dedicated API to create these locations beforehand ⚠️ A maximum of 10.000 creations can be processed in a single request. You need to split in several requests if you have more.

SecurityApiKey
Request
Request Body schema: application/json
Array ([ 1 .. 10000 ] items)
required
string or object (SparePartIdentifier)
object
required
object
additionalProperties
any
Responses
202

Request accepted (e.g. all changes will be processed as soon as possible)

400

Request contains invalid data or does not have all required data

401

Missing or invalid Api Key (e.g. revoked or non-existent)

403

Access denied

post/partners/v1/spare-parts/relocate/bulk
Request samples
application/json
[
  • {
    },
  • {
    }
]
Response samples
application/json
null

🛠️ Maintenance

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

Schedule a new task

Starter Premium Ultimate
✔️ ✔️ ✔️

Pragmatically schedule a new task to be executed by the given assignees.

For some properties, we support providing several kind of identifiers.

  • native are type auto-generated by Mobility Work
  • external are type that you provide from an import or manually through the Web interface
  • email are e-mails that are associated with your user account
  • code are type auto-generated by Mobility Work or manually through the Web interface

For each type, we support type inference, it means that we automatically detect the type from the value.

  • For assignees you can mix both native and email identifiers.
  • For tags you can mix both native and code identifiers.
  • For equipment you can mix both native and external identifiers.

If type cannot be inferred, an error will be generated. You can still force the type by providing a more typed property:

{
  "assignees": [
    3,
    "john.doe@example.com"
  ]
}

is equivalent to:

{
  "assignees": [
    {
      "type": "native",
      "value": 3
    },
    {
      "type": "email",
      "value": "john.doe@example.com"
    }
  ]
}

The property metadata can be used to send any arbitrary data to associate with the task you create. For example, on task creation, you can define the following metadata:

{
  "metadata": {
    "internalIdentifier": 1234
  }
}

It will be sent back through webhooks. You can set it to set a custom identifier to further correlate a task with any internal value.

SecurityApiKey
Request
Request Body schema: application/json
required
integer or string or object (equipment_identifier)
description
required
string [ 3 .. 3000 ] characters

Description of the task

startDateTime
required
string <date-time>

Date when the task should start

endDateTime
required
string <date-time>

Date when the task should end

allDay
required
boolean
Default: true

Define if the task is scheduled on a specific time or all day

required
Array of strings or NativeIntegerIdentifier (integer) or objects or objects

List of users which will be assigned to the task

Array of strings or NativeIntegerIdentifier (integer) or objects
Default: []

List of tags to attach to the task

checklist
null or string <uuid>
Default: null

Identifier of the checklist to associate with the task

emailToCreator
boolean
Deprecated
Default: false

Send an email to the creator when the task is completed

That option will be removed in a near future.

sendEmailToAssignees
boolean
Default: false

Send an email to every assignees to notify them they are assigned to that task.

inheritEquipmentTags
boolean
Default: false

Add tags linked to the equipment on that task

object
Default: {}

Arbitrary data to associate to the task. It can be sent back through a webhook when the task is marked as done

Responses
201

Task successfully scheduled

400

Request contains invalid data or does not have all required data

401

Missing or invalid Api Key (e.g. revoked or non-existent)

post/partners/v1/tasks
Request samples
application/json
{
  • "equipment": 9,
  • "description": "API Task creation",
  • "startDateTime": "2022-01-11T09:00:00+00:00",
  • "endDateTime": "2022-01-11T10:00:00+00:00",
  • "allDay": false,
  • "assignees": [
    ]
}
Response samples
application/json
null

Trigger API maintenance plan

Starter Premium Ultimate
✔️ ✔️ ✔️

Each API call creates a task corresponding to the selected maintenance plan ID.

SecurityApiKey
Request
path Parameters
maintenancePlanId
required
string <uuid>

The maintenance plan identifier

Request Body schema: application/json
object
Default: {}

Arbitrary data to associate to the task. It can be sent back through a webhook when the task is marked as done

Responses
204

Maintenance Plan api triggered

401

Missing or invalid Api Key (e.g. revoked or non-existent)

403

Access denied

post/partners/maintenance-plans/trigger/{maintenancePlanId}
Request samples
application/json
{
  • "metadata": { }
}
Response samples
application/json
null

🏭 Network

Anything related to network management.

Retrieve network settings

Starter Premium Ultimate
✔️ ✔️ ✔️

Get information about the network associated to the API Key.

SecurityApiKey
Responses
200

Network settings

401

Missing or invalid Api Key (e.g. revoked or non-existent)

403

Access denied

get/partners/v1/network/settings
Request samples
Response samples
application/json
{
  • "networkId": "4d4b9269-db6b-4b8f-8577-d01ef451d291",
  • "legacyNetworkId": 686,
  • "name": "Mobility Work",
  • "timezone": "Europe/Paris",
  • "currency": "EUR"
}

📡 Webhooks

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

Task was completedWebhook

Starter Premium Ultimate
✔️ ✔️

Triggered when a task was marked as completed by an user.

SecurityWebhookSigningKey
Request
header Parameters
User-Agent
required
string

User agent of the webhook service

Value: "Mobility Work - Webhook Service v1"
Request Body schema: application/json
any
Responses
200

The endpoint should return 200 status to indicate that the data was received successfully.

Request samples
application/json
{
  • "_event": "TaskWasCompleted",
  • "_idempotencyKey": "i6WeIdxywu",
  • "legacyId": "32828f62",
  • "id": "32828f62",
  • "doneAt": "2021-11-02T16:32:38+00:00",
  • "initiator": {
    },
  • "associatedTo": {
    },
  • "tags": [
    ],
  • "requiredSpareParts": [
    ],
  • "metadata": {
    },
  • "networkId": "17df9a0f-5c04-43c8-b010-b48e1237e6ff"
}

Task was scheduledWebhook

Starter Premium Ultimate
✔️ ✔️

Triggered when a task was scheduled by an user.

SecurityWebhookSigningKey
Request
header Parameters
User-Agent
required
string

User agent of the webhook service

Value: "Mobility Work - Webhook Service v1"
Request Body schema: application/json
any
Responses
200

The endpoint should return 200 status to indicate that the data was received successfully.

Request samples
application/json
{
  • "_event": "TaskWasScheduled",
  • "_idempotencyKey": "i6WeIdxywu",
  • "taskId": "32828f62",
  • "scheduled": {
    },
  • "associatedTo": {
    },
  • "tags": [
    ],
  • "requiredSpareParts": [
    ],
  • "metadata": {
    },
  • "networkId": "17df9a0f-5c04-43c8-b010-b48e1237e6ff"
}

Task was canceledWebhook

Starter Premium Ultimate
✔️ ✔️

Triggered when a task was canceled by an user.

SecurityWebhookSigningKey
Request
header Parameters
User-Agent
required
string

User agent of the webhook service

Value: "Mobility Work - Webhook Service v1"
Request Body schema: application/json
any
Responses
200

The endpoint should return 200 status to indicate that the data was received successfully.

Request samples
application/json
{
  • "_event": "TaskWasCanceled",
  • "_idempotencyKey": "i6WeIdxywu",
  • "taskId": "32828f62",
  • "canceled": {
    },
  • "associatedTo": {
    },
  • "tags": [
    ],
  • "requiredSpareParts": [
    ],
  • "metadata": {
    },
  • "networkId": "17df9a0f-5c04-43c8-b010-b48e1237e6ff"
}

Task was startedWebhook

Starter Premium Ultimate
✔️ ✔️

Triggered when a task was started by an user.

SecurityWebhookSigningKey
Request
header Parameters
User-Agent
required
string

User agent of the webhook service

Value: "Mobility Work - Webhook Service v1"
Request Body schema: application/json
any
Responses
200

The endpoint should return 200 status to indicate that the data was received successfully.

Request samples
application/json
{
  • "_event": "TaskWasStarted",
  • "_idempotencyKey": "i6WeIdxywu",
  • "taskId": "32828f62",
  • "started": {
    },
  • "associatedTo": {
    },
  • "tags": [
    ],
  • "requiredSpareParts": [
    ],
  • "metadata": {
    },
  • "networkId": "17df9a0f-5c04-43c8-b010-b48e1237e6ff"
}

Activity was added on taskWebhook

Starter Premium Ultimate
✔️ ✔️

Triggered when an activity was reported on a task by an user

SecurityWebhookSigningKey
Request
header Parameters
User-Agent
required
string

User agent of the webhook service

Value: "Mobility Work - Webhook Service v1"
Request Body schema: application/json
any
Responses
200

The endpoint should return 200 status to indicate that the data was received successfully.

Request samples
application/json
{
  • "_event": "ActivityWasAddedOnTask",
  • "_idempotencyKey": "i6WeIdxywu",
  • "_type": "ActivityWasAddedOnTaskWebhook",
  • "_sentAt": "2023-06-13T15:23:48+00:00",
  • "_metadata": [ ],
  • "emittedAt": "2023-06-13T15:23:43+00:00",
  • "task": {
    },
  • "equipment": {
    },
  • "activity": {
    },
  • "networkId": "17df9a0f-5c04-43c8-b010-b48e1237e6ff",
  • "requiredSpareParts": [
    ]
}

Spare part was out of stockWebhook

Starter Premium Ultimate
✔️ ✔️

Triggered when a spare part is out of stock after consumption or stock update

SecurityWebhookSigningKey
Request
header Parameters
User-Agent
required
string

User agent of the webhook service

Value: "Mobility Work - Webhook Service v1"
Request Body schema: application/json
any
Responses
200

The endpoint should return 200 status to indicate that the data was received successfully.

Request samples
application/json
{
  • "_event": "SparePartWasOutOfStock",
  • "_idempotencyKey": "i6WeIdxywu",
  • "_date": "2022-06-02T14:31:06+00:00",
  • "_metadata": null,
  • "stock": {
    },
  • "sparePart": {
    },
  • "movement": {
    },
  • "networkId": "17df9a0f-5c04-43c8-b010-b48e1237e6ff"
}

Spare part was under minimum stock thresholdWebhook

Starter Premium Ultimate
✔️ ✔️

Triggered when the stock amount of a spare part has gone bellow the minimum stock threshold

SecurityWebhookSigningKey
Request
header Parameters
User-Agent
required
string

User agent of the webhook service

Value: "Mobility Work - Webhook Service v1"
Request Body schema: application/json
any
Responses
200

The endpoint should return 200 status to indicate that the data was received successfully.

Request samples
application/json
{
  • "_event": "SparePartStockWasUnderMinThreshold",
  • "_idempotencyKey": "i6WeIdxywu",
  • "_date": "2022-06-02T14:31:06+00:00",
  • "_metadata": null,
  • "stock": {
    },
  • "sparePart": {
    },
  • "movement": {
    },
  • "networkId": "17df9a0f-5c04-43c8-b010-b48e1237e6ff"
}

Spare part stock was recountedWebhook

Starter Premium Ultimate
✔️ ✔️

Triggered when the stock of a spare part was manually modified

SecurityWebhookSigningKey
Request
header Parameters
User-Agent
required
string

User agent of the webhook service

Value: "Mobility Work - Webhook Service v1"
Request Body schema: application/json
any
Responses
200

The endpoint should return 200 status to indicate that the data was received successfully.

Request samples
application/json
{
  • "_type": "SparePartWasManuallyRecountedWebhook",
  • "_event": "SparePartWasManuallyRecounted",
  • "_idempotencyKey": "i6WeIdxywu",
  • "_sentAt": "2022-06-02T14:31:06+00:00",
  • "emittedAt": "2023-02-08T23:00:00+00:00",
  • "_metadata": "",
  • "sparePart": {
    },
  • "location": {
    },
  • "initiator": {
    },
  • "recounted": {
    },
  • "networkId": "17df9a0f-5c04-43c8-b010-b48e1237e6ff"
}

Spare part has been replenishedWebhook

Starter Premium Ultimate
✔️ ✔️

Triggered when a spare part has been replenished

SecurityWebhookSigningKey
Request
header Parameters
User-Agent
required
string

User agent of the webhook service

Value: "Mobility Work - Webhook Service v1"
Request Body schema: application/json
any
Responses
200

The endpoint should return 200 status to indicate that the data was received successfully.

Request samples
application/json
{
  • "_type": "SparePartWasRestockedWebhook",
  • "_event": "SparePartWasRestocked",
  • "_idempotencyKey": "i6WeIdxywu",
  • "_sentAt": "2022-06-02T14:31:06+00:00",
  • "emittedAt": "2023-02-08T23:00:00+00:00",
  • "_metadata": "",
  • "task": null,
  • "sparePart": {
    },
  • "location": {
    },
  • "initiator": {
    },
  • "restocked": {
    },
  • "networkId": "17df9a0f-5c04-43c8-b010-b48e1237e6ff"
}

Spare part was consumedWebhook

Starter Premium Ultimate
✔️ ✔️

Triggered when a spare part is consumed

SecurityWebhookSigningKey
Request
header Parameters
User-Agent
required
string

User agent of the webhook service

Value: "Mobility Work - Webhook Service v1"
Request Body schema: application/json
any
Responses
200

The endpoint should return 200 status to indicate that the data was received successfully.

Request samples
application/json
{
  • "_type": "SparePartWasConsumedWebhook",
  • "_event": "SparePartWasConsumed",
  • "_idempotencyKey": "i6WeIdxywu",
  • "_sentAt": "2022-06-02T14:31:06+00:00",
  • "emittedAt": "2023-02-08T23:00:00+00:00",
  • "_metadata": "",
  • "task": {
    },
  • "sparePart": {
    },
  • "location": {
    },
  • "initiator": {
    },
  • "consumed": {
    },
  • "networkId": "17df9a0f-5c04-43c8-b010-b48e1237e6ff"
}

Spare part consumption was canceledWebhook

Starter Premium Ultimate
✔️ ✔️

Triggered when a spare part consumption has been canceled from an activity or an activity deletion

SecurityWebhookSigningKey
Request
header Parameters
User-Agent
required
string

User agent of the webhook service

Value: "Mobility Work - Webhook Service v1"
Request Body schema: application/json
any
Responses
200

The endpoint should return 200 status to indicate that the data was received successfully.

Request samples
application/json
{
  • "_type": "SparePartConsumptionWasCanceledWebhook",
  • "_event": "SparePartConsumptionWasCanceled",
  • "_idempotencyKey": "i6WeIdxywu",
  • "_sentAt": "2022-06-02T14:31:06+00:00",
  • "emittedAt": "2023-02-08T23:00:00+00:00",
  • "_metadata": "",
  • "task": {
    },
  • "sparePart": {
    },
  • "activity": {
    },
  • "location": {
    },
  • "networkId": "17df9a0f-5c04-43c8-b010-b48e1237e6ff"
}