M2X APIs
- Bookings (carrier allocation webhook)
M2X APIS (1.0.0)
- Mock serverhttps://developer.m2x.app/_mock/apis/publicapi/openapi/bookings/{bookingId}/events
- https://developer.m2x.app/apis/v0/bookings/{bookingId}/events
- NZ Production server (uses live data)https://m2x.app/apis/v0/bookings/{bookingId}/events
- US Production server (uses live data)https://us.m2x.app/apis/v0/bookings/{bookingId}/events
- AUS Production server (uses live data)https://au.m2x.app/apis/v0/bookings/{bookingId}/events
- Sandbox serverhttps://staging.m2x.app/apis/v0/bookings/{bookingId}/events
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://developer.m2x.app/_mock/apis/publicapi/openapi/bookings/{bookingId}/events' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"event": "load",
"status": "partial",
"note": "string",
"reference": "string",
"actualId": "string",
"created": "2019-08-24T14:15:22Z",
"actual": {
"quantity": 0,
"properties": null,
"productSpatialRequirement": null,
"productMassKg": null,
"productNetWeightKg": null,
"productTareWeightKg": null,
"metadata": null,
"product": {
"productCode": null,
"productCodeExternalId": null,
"productDescription": null
},
"content": null
}
}'Request
Webhook type: BOOKING
This webhook provides notifications of changes to bookings that have been allocated to a carrier. It provides the subscriber with the full Booking entity, and enables downstream processes such as reporting and tracking.
This webhook is triggered when:
- The booking is allocated to a carrier through the enterprise platform, either via manual assignment or automated workflow.
- Any update is made to the booking through the enterprise environment whilst the carrier is allocated.
A booking with canceled: true is sent once. While it stays canceled, no further notifications are sent for it, even if other fields change. If the booking is allocated to the carrier again, notifications resume, and a later cancellation is again sent once. Delivery is at least once, so a cancellation can occasionally be repeated.
A cancellation is only sent to a webhook that a notification of the booking was sent to while it was allocated, whether or not that notification was delivered. A booking canceled before then, such as one canceled before the webhook was created, produces no notifications. Bookings created before this behavior was introduced are the exception: their cancellation is sent once regardless.
This applies to webhooks on both corporate and carrier accounts.
Indicates whether the booking has been unallocated from the carrier. Note: This field does not reflect whether the booking itself has been canceled within the enterprise system. It only represents that the carrier is no longer assigned to the booking
Whether upon acceptance the carrier shall get a payment or not (e.g. freight forward)
The sub components of the product if present
The sub components of the product if present
Weight in kg of a single unit for the booking. Independent of productMassKg — when only this is supplied the total weight stays derived as quantity x productMassKgPerUnit.
The relevant master booking information for this booking
- Mock serverhttps://developer.m2x.app/_mock/apis/publicapi/openapi/Booking
- https://developer.m2x.app/apis/v0/Booking
- NZ Production server (uses live data)https://m2x.app/apis/v0/Booking
- US Production server (uses live data)https://us.m2x.app/apis/v0/Booking
- AUS Production server (uses live data)https://au.m2x.app/apis/v0/Booking
- Sandbox serverhttps://staging.m2x.app/apis/v0/Booking
{ "agent": { "email": "string", "uid": "string", "phone": "string", "name": "string", "externalId": "string" }, "id": "string", "externalReference": "string", "externalNote": "string", "canceled": true, "completed": true, "acknowledged": true, "tentative": true, "status": "string", "slaQuality": 0, "slaStatus": "string", "awardCreated": "2019-08-24T14:15:22Z", "requestCreated": "2019-08-24T14:15:22Z", "updated": "2019-08-24T14:15:22Z", "latestDeliveryTimestamp": "2019-08-24T14:15:22Z", "earliestPickupTimestamp": "2019-08-24T14:15:22Z", "fulfilments": [ { … } ], "acceptanceState": { "acceptanceDeadline": "2019-08-24T14:15:22Z", "actioned": "2019-08-24T14:15:22Z", "accepted": true, "acceptable": true, "declined": true, "declinable": true, "retractable": true }, "noPayment": false, "noPrice": false, "carrierId": "string", "carrierExternalId": "string", "carrierName": "string", "corporateId": "string", "corporateName": "string", "corporateSubaccountId": "string", "corporateSubaccountName": "string", "corporateSubaccountIntegrationId": "string", "transportRequirementsId": "string", "productCode": null, "productCodeName": null, "productCodeExternalId": null, "properties": null, "metadata": null, "content": {}, "quantity": 0, "productSpatialRequirement": null, "productMassKg": null, "productMassKgPerUnit": null, "productNetWeightKg": null, "productTareWeightKg": null, "distanceKm": 0, "sourceId": "string", "groupPricingStrategyGroupId": null, "priceTransport": null, "priceFaf": null, "offerStatus": "None", "priceFafOffer": null, "priceTransportOffer": null, "fromLocation": { "addressText": "string", "latitude": 0, "longitude": 0, "locationName": "string", "locationId": "string", "locationOwnerId": "string", "locationVersion": "string", "externalId": "string", "timezone": "Pacific/Auckland", "properties": null }, "fromLocationDistrict": "string", "fromLocationDistrictId": "string", "fromLocationRegion": "string", "fromDateAndTimeConstraint": { "date": "2019-08-24", "timezone": "Pacific/Auckland", "timeConstraint": {} }, "fromTimeWindows": [ { … } ], "fromLocationGroup": { "groupId": "string", "code": "C123", "externalId": "asd-asd-asd", "name": "string" }, "fromContactDetails": { "email": "string", "phone": "string", "name": "string" }, "toLocation": { "addressText": "string", "latitude": 0, "longitude": 0, "locationName": "string", "locationId": "string", "locationOwnerId": "string", "locationVersion": "string", "externalId": "string", "timezone": "Pacific/Auckland", "properties": null }, "toLocationDistrict": "string", "toLocationDistrictId": "string", "toLocationRegion": "string", "toDateAndTimeConstraint": { "date": "2019-08-24", "timezone": "Pacific/Auckland", "timeConstraint": {} }, "toTimeWindows": [ { … } ], "toLocationGroup": { "groupId": "string", "code": "C123", "externalId": "asd-asd-asd", "name": "string" }, "toContactDetails": { "email": "string", "phone": "string", "name": "string" }, "masterBooking": { "masterBookingId": "string", "type": "string", "shipmentId": "string", "transportMode": "string", "properties": null, "metadata": null, "containerNumber": "string", "containerSealNumber": "string", "shippingBookingReference": "string", "customerOrderNumber": "string", "salesOrderNumber": "string", "purchaseOrderNumber": "string", "shippingTemperature": 0, "specialInstructions": "string", "releaseNumber": "string", "feederVessel": "string", "feederVoyageNumber": "string", "oceanVessel": "string", "oceanVoyageNumber": "string", "shippingCarrier": "string", "dangerousGoods": true, "unNumber": "string", "activeRefrigeration": true, "ambientTimeHours": 0, "powerOffDateTime": "string", "vesselArrivalDateTime": "string", "vesselDepartureDateTime": "string", "packDate": "2019-08-24", "availableDate": "2019-08-24", "portEarliestReceivalDateTime": "2019-08-24T14:15:22Z", "movementSequence": 0, "movementType": "string", "movementTotal": 0, "customerName": "string", "productType": "Bulk", "emptyReleaseNumber": "string", "shipCutOffDateTime": "2019-08-24T14:15:22Z", "commodityCode": "string", "commodityDescription": "string", "connectedMovements": { … } }, "exceptionFlagState": {} }
Request
webhook type: FACT
This webhook allows you to receive notifications when booking events are created or updated. This could be due to changes made in the carrier TMS, mobile app, or in external systems via the M2X API.
Possible event types are listed in the description of the event field of the payload.
This webhook is triggered when:
- A booking event is created or updated. See below for the list of possible events.
Who captured the event. MOBILE is the driver's mobile app, API is a carrier or agent integration, WEB is a dispatcher in the web app
- Mock serverhttps://developer.m2x.app/_mock/apis/publicapi/openapi/Booking Event
- https://developer.m2x.app/apis/v0/Booking Event
- NZ Production server (uses live data)https://m2x.app/apis/v0/Booking Event
- US Production server (uses live data)https://us.m2x.app/apis/v0/Booking Event
- AUS Production server (uses live data)https://au.m2x.app/apis/v0/Booking Event
- Sandbox serverhttps://staging.m2x.app/apis/v0/Booking Event
{ "id": "string", "canceled": true, "bookingId": "string", "event": "load", "source": "API", "version": "string", "status": {}, "vehicle": { "vehicleName": "string", "vehicleId": "string", "vehicleExternalId": "string", "registration": "string", "vehicleType": "string", "weightClass": 0, "weightClassLabel": "string", "driverId": "string", "driverExternalId": "string", "driverName": "string" }, "timeWindow": { "start": "2019-08-24T14:15:22Z", "end": "2019-08-24T14:15:22Z" }, "note": "string", "reference": "string", "actualId": "string", "deliveryReference": "string", "truckReference": "string", "flagReason": "string", "resolutionReason": "string", "created": "2019-08-24T14:15:22Z", "serverCreated": "2019-08-24T14:15:22Z", "actual": {}, "attachments": {} }