# Overview

Last updated:

<!-- -->

October 18, 2026

<!-- -->

\| 7 minutes read

<br />

<br />

[v](/docs/cloud-rest-api/guides/fleet-management/CHANGELOG/)

<!-- -->

[1.2.1 Release notes →](/docs/cloud-rest-api/guides/fleet-management/CHANGELOG/)

<br />

<br />

**The Fleet Management Rest API**, is a powerful and flexible solution for optimizing and managing your fleet operations. This API is designed to streamline route planning, order fulfillment, and vehicle assignments by leveraging **Vehicle Routing Problem (VRP)** optimization. Whether you are managing deliveries, service operations, or logistics, our API provides all the tools you need to maximize efficiency and minimize costs.

## Authentication[​](#authentication "Direct link to Authentication")

All Fleet Management API endpoints require an API key passed in the `Authorization` header:

```bash
curl -X POST  https://api.magiclane.net/api/v1/ \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

```

See the [Introduction guide](/docs/cloud-rest-api/guides/introduction.md#api-authentication) for details on obtaining your API key.

***

## Two Ways to Use the Fleet Management REST API[​](#two-ways-to-use-the-fleet-management-rest-api "Direct link to Two Ways to Use the Fleet Management REST API")

The Fleet Management REST API provides two distinct approaches for route optimization, each designed for different use cases:

### Direct Optimization (`/optimize`)[​](#direct-optimization-optimize "Direct link to direct-optimization-optimize")

**Stateless, Real-time Operations**

* **Input**: Send complete VRP data directly in a single request
* **Output**: Receive optimized routes immediately
* **Storage**: No data is saved to the database
* **Best for**: Real-time route planning, what-if scenarios, external system integration

### Full Entity Management[​](#full-entity-management "Direct link to Full Entity Management")

**Persistent, UI-Friendly Operations**

* **Workflow**: Create customers → orders → vehicles → optimizations → retrieve solutions
* **Storage**: All data is persisted and manageable via CRUD operations
* **Best for**: Fleet management applications, dashboards, long-term planning

:::tip Choosing the Right Approach

* Use **`/optimize`** for quick, stateless operations and real-time scenarios
* Use **full entity management** when building applications with user interfaces that require data persistence :::

## Feature list[​](#feature-list "Direct link to Feature list")

**The Fleet Management Rest API** is designed to handle a wide variety of logistics, routing, and optimization tasks, providing robust support for fleet operations. Below is an overview of the key features:

### 1. Customers and Orders[​](#1-customers-and-orders "Direct link to 1. Customers and Orders")

* **Customer Management**:

  <!-- -->

  * Add, retrieve, update, and delete customer profiles.
  * Manage customer contact information, such as email, phone number, and address.
  * Associate custom data with customers for additional information.

* **Order Management**:

  <!-- -->

  * Add, retrieve, update, and delete orders.

  * Support for order types: **Pickup** and **Delivery**.

  * Define order attributes:

    <!-- -->

    * Time windows (start and end times).
    * Priority levels: **Low** or **High**.
    * Parcel details: weight, volume and number of packages.
    * Customizable service times per order.

  * Sequence orders into specific routes or enforce delivery sequences.

### 2. Vehicles[​](#2-vehicles "Direct link to 2. Vehicles")

* **Vehicle Management**:

  <!-- -->

  * Add, retrieve, update, and delete vehicles.

  * Define vehicles by type: **Car**, **Truck**, **Bike**, **E-bike**, or **Pedestrian**.

  * Manage vehicle attributes:

    <!-- -->

    * Maximum load weight and volume.
    * Fuel type and consumption rates.
    * Physical dimensions: height, width, length, and axle load. (only for trucks; currently descriptive only, not used in route optimization – TBD)
    * Operating costs (fixed and hourly).

  * Track vehicle availability and statuses (e.g., Available, En Route).

  * Assign vehicles to routes based on constraints and optimization results.

* **Vehicle Constraints**:

  <!-- -->

  * Specify start and end times for vehicle operations.
  * Define maximum distance, number of orders, or packages for all vehicles or for each vehicle.

### 3. Territories[​](#3-territories "Direct link to 3. Territories")

* **Territory Management**:

  <!-- -->

  * Add, retrieve, update, and delete territories.
  * Define operational territories with different shapes: **Polygon**, **Circle**, or **Rectangle**.
  * Retrieves orders inside territories, helps territory-based routing.
  * Customize territory colors for easier visualization.

### 4. Fleet Optimization[​](#4-fleet-optimization "Direct link to 4. Fleet Optimization")

* **Optimization Goals**:
  <!-- -->
  * Optimize routes based on distance or time.

* **Route Types**:

  <!-- -->

  * Round routes (start and end at the same location).
  * End-anywhere routes (routes that end at the most efficient destination).
  * Custom endpoints for routes.

* **Configuration Options**:

  <!-- -->

  * Set optimization quality: **Unoptimized**, **Fast**, **Optimized**, or **Best**.
  * Define matrix-building types for distance and time calculations:
    <!-- -->
    * User-defined or real-world driving metrics.
  * Specify road restrictions:
    <!-- -->
    * Avoid toll roads or highways "TBD".

* **Fuel and Cost Efficiency**:

  <!-- -->

  * Incorporate fuel prices for multiple fuel types: Diesel Standard/Premium, Gasoline Standard/Premium, LPG, Electric.
  * Calculate route costs based on vehicle consumption and distance.

* **Order Sequencing**:

  <!-- -->

  * Group orders into fixed or flexible sequences.
  * Enforce pickup and delivery pairings for specific use cases.

* **Real-Time Operations**:

  <!-- -->

  * Reoptimize routes dynamically in response to changes.
  * Monitor vehicle progress, arrival times, and wait times.

* **Custom Constraints**:

  <!-- -->

  * Allow dropped orders if no feasible solution is found.
  * Enable grouping of nearby orders for clustering efficiency.
  * Balance routes by time or the number of orders.

### 5. Reporting and Insights[​](#5-reporting-and-insights "Direct link to 5. Reporting and Insights")

* **Performance Metrics**:

  <!-- -->

  * Total travel distance, duration, and service times per route.
  * Fuel consumption and cost estimations for each route.
  * Order-level details: delivery statuses, waiting times, and package counts.

* **Export Options**:
  <!-- -->
  * Export routes in multiple formats, such as GPX or database files.

### 6. API Flexibility[​](#6-api-flexibility "Direct link to 6. API Flexibility")

* **Async Operations**:
  <!-- -->
  * Perform asynchronous optimizations, order updates, and route reassignments.
* **Error Handling**:
  <!-- -->
  * Detailed error messages and codes for debugging failed requests.
* **Customization**:
  <!-- -->
  * Flexible configuration parameters to tailor optimizations to your business needs.

***

### Step-by-Step Guide: Creating an Optimization[​](#step-by-step-guide-creating-an-optimization "Direct link to Step-by-Step Guide: Creating an Optimization")

***(Using Full Entity Management Approach)***

This guide demonstrates how to create an optimization using the persistent, entity-based workflow where all data is stored in the database and can be managed through CRUD operations.

:::note Alternative Approach For stateless, real-time optimization without data persistence, use the **`/optimize`** endpoint directly. See the [Optimize Documentation](/docs/cloud-rest-api/guides/fleet-management/core-concepts/landmark.md#2-optimize-asynchronously) for details. :::

:::info 📌 **Order of Operations: Visual Flow**

<!-- -->

:::

### Step 1: Add Customers and Orders[​](#step-1-add-customers-and-orders "Direct link to Step 1: Add Customers and Orders")

Before optimizing routes, you need to define *who* is involved and *what* needs to be delivered or picked up.

#### Create Customers[​](#create-customers "Direct link to Create Customers")

Customers are the people or organizations placing orders. Each order must be linked to a customer using their `customerId`.

* **API Endpoint:** `POST /customers`
* **Request:** An array of customer objects
* **Response:** Returns customer objects with system-generated `id`s

#### Create Orders[​](#create-orders "Direct link to Create Orders")

Orders define what is being delivered or picked up, and include location, time windows, priorities, and a `customerId`.

* **API Endpoint:** `POST /orders`
* **Request:** An array of order objects
* **Response:** Returns order objects with system-generated `id`s

***

### Step 2: Add Vehicles and Constraints[​](#step-2-add-vehicles-and-constraints "Direct link to Step 2: Add Vehicles and Constraints")

Vehicles represent your delivery or pickup fleet. Each vehicle can have specific limits or rules, known as constraints.

#### Create Vehicles[​](#create-vehicles "Direct link to Create Vehicles")

Each vehicle will be used in route planning and must be created before optimization.

* **API Endpoint:** `POST /vehicles`
* **Request:** An array of vehicle objects
* **Response:** Returns vehicle objects with system-generated `id`s

#### Define Vehicle Constraints[​](#define-vehicle-constraints "Direct link to Define Vehicle Constraints")

These rules ensure routes stay within each vehicle’s capabilities, such as:

* Maximum capacity
* Maximum distance
* Revenue or delivery limitations

***

### Step 3: Set Optimization Parameters[​](#step-3-set-optimization-parameters "Direct link to Step 3: Set Optimization Parameters")

Define settings that control how the optimization engine works. These can include:

* Optimization goals (e.g., minimize distance, time)
* Maximum search time
* Flexibility options

This step fine-tunes how the system balances different priorities.

***

### Step 4: Define Departures and Destinations[​](#step-4-define-departures-and-destinations "Direct link to Step 4: Define Departures and Destinations")

Set the start and end points for each vehicle’s route.

* **Departures:** Starting locations for vehicles. Affect travel time and routing logic.
* **Destinations:** Final stops for vehicles. Help ensure the most efficient route end-points.

These can be specific locations or rules (e.g., return to depot).

***

### Step 5: Create the Optimization[​](#step-5-create-the-optimization "Direct link to Step 5: Create the Optimization")

This is where everything comes together - customers, orders, vehicles, and parameters - to define the full routing problem.

* **API Endpoint:** `POST /optimizations`
* **Request:** An object that includes orders, vehicles, constraints, and optimization settings
* **Response:** Returns an `optimizationId` and `requestId` to track the process

***

### Step 6: Retrieve the Optimized Solution[​](#step-6-retrieve-the-optimized-solution "Direct link to Step 6: Retrieve the Optimized Solution")

Once the system has finished processing, fetch the optimized routes.

* **API Endpoint:** `GET /optimizations/{id}/solution`
* **Response:** A list of optimized routes for the fleet, based on the submitted data
