2. Your first API - Schedule a new task
Problem
Create your first “business” API call from scratch.
Methodology
We have based our approach on an incremental methodology: we test a minimal hypothesis and gradually build up to achieve the final result — source code that calls a Mobility Work (MW) API.
The example is based on task creation: scheduling a new task.
Before creating your first API call, please ensure that there are no security restrictions in place.
Step 1 : get an API KEY
- Contact support to obtain an API key for your network.
- If you manage multiple networks, you will need to obtain a separate API key for each one.
Step 2 : test the API KEY
- Go to your API documentation
- Go to the Retrieve network settings part
- Add your API Key
Your security key is valid
Your security key is not valid
Step 3 : test the Create Task API
Your API Key is valid, so let’s now use a “real” API to create your first task by following the documentation.
-
Step 4 is dedicated to testing it with a real application.
-
Go to the Schedule a New Task documentation.
-
Create a valid JSON payload.
-
Launch the test.
Example of a valid JSON:
{
"equipment": 1958856,
"description": "My new API Task",
"startDateTime": "2025-07-29T15:00:00.071Z",
"endDateTime": "2025-07-29T16:00:00.071Z",
"allDay": false,
"assignees": [
"[email protected]"
],
"sendEmailToAssignees": false,
"inheritEquipmentTags": false,
"metadata": {}
}
API response / HTTP 200
You can verify that your task was created on the Task Page.
- For example, by filtering by task name.
Step 4 : ID vs External reference
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.
In order to make your integration you can use External Reference instead native Id.
Valid JSon
{
"equipment": "StabiloBlue", -> External reference
"description": "My new API Task V2",
"startDateTime": "2025-07-29T15:00:00.071Z",
"endDateTime": "2025-07-29T16:00:00.071Z",
"allDay": false,
"assignees": [
"[email protected]"
],
"sendEmailToAssignees": false,
"inheritEquipmentTags": false,
"metadata": {}
}
Step 5 : Error
The core error message is alway on value of key message
For some error you can hame more details on extended_message
Call with an incorrect date
{
"equipment": 1958856,
"description": "My new API Task",
"startDateTime": "2025-07-29T15:00:00.071Z",
"endDateTime": "0005-07-29T16:00:00.071Z", -> Wrong date
"allDay": false,
"assignees": [
"[email protected]"
],
"sendEmailToAssignees": false,
"inheritEquipmentTags": false,
"metadata": {}
}
Response
HTTP 400
{
"http_status_code": 400,
"code": "400001",
"message": "Expected a date after '2025-07-29T15:00:00+00:00'",
"extended_message": null,
"more_info_url": null
}
Call with non valid eMail
{
"equipment": 1958856,
"description": "My new API Task",
"startDateTime": "2025-07-29T15:00:00.071Z",
"endDateTime": "2025-07-29T16:00:00.071Z",
"allDay": false,
"assignees": [
"laurent.desechalliers" -> wrong eMail
],
"sendEmailToAssignees": false,
"inheritEquipmentTags": false,
"metadata": {}
}
Response
HTTP 400
{
"http_status_code": 400,
"code": "400005",
"message": "The request payload is not valid.",
"extended_message": {
"global_errors": [],
"property_errors": {
"[assignees][0]": [
{
"messageKey": "error.payload.format",
"messageTemplate": "error.payload.format",
"parameters": {
"format": "email",
"type": "string"
}
},
{
"messageKey": "error.payload.type",
"messageTemplate": "error.payload.type",
"parameters": {
"expected": "integer",
"type": "string"
}
},
{
"messageKey": "error.payload.type",
"messageTemplate": "error.payload.type",
"parameters": {
"expected": "object",
"type": "string"
}
},
{
"messageKey": "error.payload.type",
"messageTemplate": "error.payload.type",
"parameters": {
"expected": "object",
"type": "string"
}
}
]
}
},
"more_info_url": null
}
Step 6: Postman exemple
We provide ressource to use directly our APIs with Postman.
Go to this page to get more information how to use pre-build PostMan collections.
Step 0 : Download PostMan Collection
Step 1 : change the API Key
- Set your API Key on the collection
Step 2 : set relevant variables values
- Change the variables values to match your network values.
- The values that are in the test collection are used for one of our test networks : you can use it on your network.
Step 3 : test
- Select
Schedule a new taskrequest - Call API (send button)
- It's must work
Step 6 : Curl exemple
curl -X POST "https://api.mobility-work.com/partners/v1/tasks" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Api-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-d '{
"equipment": "StabiloBlue",
"description": "My new API Task",
"startDateTime": "2025-07-29T15:00:00.071Z",
"endDateTime": "2025-07-29T16:00:00.071Z",
"allDay": false,
"assignees": [
"[email protected]"
],
"sendEmailToAssignees": false,
"inheritEquipmentTags": false,
"metadata": {}
}'
Run it : it’s work
Step 6 : Python exemple
import requests
import json
# Personal API key
API_KEY = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxx'
# API URL for creating a task
url = 'https://api.mobility-work.com/partners/v1/tasks'
# Headers required for API call
headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Api-Key': API_KEY
}
# Query body (data for the task to be created)
payload = {
"equipment": "StabiloBlue",
"description": "My new API Task",
"startDateTime": "2025-07-29T15:00:00.071Z",
"endDateTime": "2025-07-29T16:00:00.071Z",
"allDay": False,
"assignees": [
"[email protected]"
],
"sendEmailToAssignees": False,
"inheritEquipmentTags": False,
"metadata": {}
}
# Sending a POST request
response = requests.post(url, headers=headers, data=json.dumps(payload))
# Response processing
if response.status_code == 201:
print("✅ Tâche created with success.")
else:
print(f"❌ Error during task creation. HTTP code : {response.status_code}")
print(response.text)
Run it : it’s work
Step 6 : PHP exemple
<?php
// Personal API key
$apiKey = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
// API URL
$url = 'https://api.mobility-work.com/partners/v1/tasks';
// Payload data
$payload = [
"equipment" => "StabiloBlue",
"description" => "UUUUUUMy new API Task V6",
"startDateTime" => "2025-07-29T15:00:00.071Z",
"endDateTime" => "2025-07-29T16:00:00.071Z",
"allDay" => false,
"assignees" => [
"[email protected]"
],
"sendEmailToAssignees" => false,
"inheritEquipmentTags" => false,
"metadata" => new stdClass()
];
// cURL initialization
$ch = curl_init($url);
// POST request configuration
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Accept: application/json',
'Content-Type: application/json',
'Api-Key: ' . $apiKey
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
// Executing the request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
// Response processing
if ($httpCode === 201) {
echo "✅ Task created successfully.\n";
echo json_encode(json_decode($response), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
} else {
echo "❌ Error during task creation. HTTP code : $httpCode\n";
echo $response;
}
Run it : it’s work