MobilityCloud
Integration architecture connecting enterprise systems and AI agents to transport orchestration.
Vertically integrated transport stack
Mobility Cloud combines software orchestration with a nationwide physical execution layer.
NextMile Network
Nationwide physical execution layer delivering scalable and consistent vehicle movement.
Orchestration & Optimization
Job routing, execution monitoring, and performance optimization across the transport lifecycle.
Automated Engagement
Event-driven status updates and automated customer communications embedded in the workflow.
Authentication
Every API request requires both authentication headers.
| Header | Required | Description |
|---|---|---|
X-Client-Id | Yes | Your assigned API client identifier. |
X-API-Key | Yes | Your private API key. Do not expose it in public client-side applications. |
Example headers
X-Client-Id: YOUR_CLIENT_ID X-API-Key: YOUR_API_KEY Content-Type: application/json
Base URL
Replace the placeholder with the URL provided for your environment.
https://api-sandbox.mobilitycloud.aiEndpoints
Select an endpoint to view parameters, schemas, examples, and possible responses.
GET/dealershipsAndHubsList Dealerships & Hubs⌄
Returns the dealerships and hubs available to the authenticated client. Optional coordinates can be supplied for proximity filtering.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
lat | number | No | Latitude for proximity filtering. Example: 40.7128. |
lon | number | No | Longitude for proximity filtering. Example: -74.006. |
cURL
curl --request GET \ 'https://api-sandbox.mobilitycloud.ai/dealershipsAndHubs?lat=40.7128&lon=-74.006' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-API-Key: YOUR_API_KEY'
200 response
[
{
"id": 1001,
"name": "Example Dealership",
"address": "123 Main Street, New York, NY",
"lat": 40.7128,
"lon": -74.006
}
]Responses
200List of dealerships
400Query validation error
401Missing or invalid authentication headers
429Rate limit exceeded
500Unexpected server error
POST/movementsCreate movement⌄
Creates a pickup or drop-off vehicle movement.
Required top-level fields
| Field | Type | Description |
|---|---|---|
dealerShipId | integer (int64) | Dealership or hub identifier. |
from | object | Origin. Requires address, latitude, and longitude. |
to | object | Destination. Requires address, latitude, and longitude. |
customer | object | Requires first name, last name, and telephone. |
type | string | PICKUP or DROPOFF. |
car | object | Requires color, plate, and a 17-character VIN. |
schedule | integer (int64) | Scheduled date/time as epoch milliseconds. |
advisorName | string | Advisor responsible for the movement. |
Request example
{
"dealerShipId": 1001,
"from": {
"address": "123 Main Street, New York, NY 10001",
"lat": 40.7505,
"lon": -73.9934,
"city": "New York",
"zip": "10001",
"country": "US",
"state": "NY"
},
"to": {
"address": "456 Example Avenue, Brooklyn, NY 11201",
"lat": 40.6960,
"lon": -73.9933,
"city": "Brooklyn",
"zip": "11201",
"country": "US",
"state": "NY"
},
"customer": {
"firstName": "Jane",
"lastName": "Doe",
"tel": "+12125550123",
"email": "jane@example.com"
},
"advisorName": "John Advisor",
"description": "Vehicle service pickup",
"comment": "Call customer on arrival",
"completionSurvey": true,
"type": "PICKUP",
"car": {
"make": "Tesla",
"color": "Black",
"year": "2023",
"model": "Model Y",
"plate": "ABC1234",
"transmission": "AUTOMATIC",
"vin": "7SAYGDEF0PF617149"
},
"schedule": 1769112000000
}cURL
curl --request POST 'https://api-sandbox.mobilitycloud.ai/movements' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-API-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data @movement.json
200 response
{
"id": 442190
}Optional fields
description, comment, completionSurvey, repairOrder, and returnTripCar.
Responses
200Movement created
400Request body validation error
401Missing or invalid authentication headers
429Rate limit exceeded
500Internal server error
GET/movements/{id}Get Movement Status⌄
Returns the current state and details of a movement.
Path parameter
| Name | Type | Required |
|---|---|---|
id | integer (int64) | Yes |
cURL
curl --request GET 'https://api-sandbox.mobilitycloud.ai/movements/442190' \ --header 'X-Client-Id: YOUR_CLIENT_ID' \ --header 'X-API-Key: YOUR_API_KEY'
200 response
{
"id": 442190,
"state": "IN_PROGRESS"
}Responses
200Movement details
400Invalid movement ID
401Missing or invalid authentication headers
404Movement not found
429Rate limit exceeded
500Unexpected server error
DELETE/movements/{id}Cancel movement⌄
Cancels an existing movement. A cancellation reason of at least 10 characters is required.
Request body
{
"reason": "Customer requested cancellation"
}cURL
curl --request DELETE 'https://api-sandbox.mobilitycloud.ai/movements/442190' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"reason":"Customer requested cancellation"}'Responses
200Movement cancelled
400Invalid ID or cancellation reason
401Missing or invalid authentication headers
404Movement not found
429Rate limit exceeded
500Unexpected server error
Movement states
Possible values returned by the movement status endpoint.
OFFERED | The movement has been offered for assignment. |
ASSIGNED | A driver or carrier has been assigned. |
SCHEDULED | The movement is scheduled. |
IN_PROGRESS | The movement is currently being executed. |
ARRIVED | The driver has arrived at the pickup point. |
DROPOFF_ARRIVED | The vehicle has arrived at the destination. |
COMPLETED | The movement was successfully completed. |
CANCELLED_COMPLETED | The movement was cancelled and closed. |
Error format
Validation and authorization errors are returned as JSON.
{
"error": "VALIDATION_ERROR",
"message": "Request body validation failed",
"issues": [
{
"path": "dealerId",
"message": "Required"
}
]
}Rate limit response
{
"code": "RATE_LIMIT_EXCEEDED",
"detail": "Too many requests."
}