# Territory

Last updated:

<!-- -->

October 18, 2026

<!-- -->

\| 13 minutes read

<br />

<br />

The **Territory Rest API** allows you to manage territories within the Fleet Management system. You can create, retrieve, update, and delete territories. This Rest API supports basic operations to define geographical regions used for route planning and optimization.

### Territory Object Fields[​](#territory-object-fields "Direct link to Territory Object Fields")

| Field    | Type    | Description                                                                                                                                                                                                                        |
| -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`     | Integer | Unique identifier for the territory.                                                                                                                                                                                               |
| `name`   | String  | Name of the territory.                                                                                                                                                                                                             |
| `type`   | Integer | Territory type:`0` - Polygon`1` - Circle`2` - Rectangle                                                                                                                                                                            |
| `data`   | Array   | Defines the shape of the territory based on its type:**Circle** - Contains the center and a point on the circle.**Rectangle** - Contains two diagonally opposite points.**Polygon** - Contains a list of points defining the area. |
| `color`  | String  | Color associated with the territory.                                                                                                                                                                                               |
| `orders` | Array   | List of orders associated with the territory.                                                                                                                                                                                      |

***

## Endpoints[​](#endpoints "Direct link to Endpoints")

### 1. Create Territory[​](#1-create-territory "Direct link to 1. Create Territory")

**Description:** Adds a new territory to the database.

* **Base URL:** `https://api.magiclane.net/api/v1`

* **Endpoint:** `POST /fleetmanagement/territories`

* **Headers:**

  * `Authorization: YOUR_API_KEY`
  * `Content-Type: application/json`

* **Returned error codes:**

| Error Code                  | Description                                                                                                                                                                                                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 Successful`            | Successful operation.                                                                                                                                                                                                                                                                             |
| `400 Bad Request`           | - Not all the points of the territory's data have 2 values (latitude, longitude).<br />- For polygon, the data should have 3 points; for circle and rectangle the territory’s data should have 2 points: the center of the circle and a point on the circle edge or 2 points diagonally opposite. |
| `401 Unauthorized`          | API key is missing or invalid.                                                                                                                                                                                                                                                                    |
| `405 Method Not Allowed`    | Incorrect method type.                                                                                                                                                                                                                                                                            |
| `500 Internal Server Error` | Database error occurred.                                                                                                                                                                                                                                                                          |

#### Example:[​](#example "Direct link to Example:")

* **Request Body:**

- Schema View
- JSON Example
- JSON View

* `name`(

  <!-- -->

  string

  <!-- -->

  )

  Name of the territory.

* `type`(

  <!-- -->

  integer

  <!-- -->

  )

  Territory type - Specifies the shape of the territory.

  * `0` - Polygon
  * `1` - Circle
  * `2` - Rectangle

* `data`(

  <!-- -->

  array\[double]

  <!-- -->

  )

  Defines the shape of the territory based on its type:

  * **Circle**: Contains the center and a point on the circle.
  * **Rectangle**: Contains two diagonally opposite points.
  * **Polygon**: Contains a list of points defining the area.

* `color`(

  <!-- -->

  string

  <!-- -->

  )

  Color associated with the territory.

```json
[
  {
    "name": "North Region",
    "type": 1,
    "data": [
      [
        48.827865,
        2.379216
      ],
      [
        48.43446,
        5.234103
      ]
    ],
    "color": "#FF5733"
  },
  {
    "name": "South Region",
    "type": 2,
    "data": [
      [
        48.88025,
        2.299601
      ],
      [
        48.897163,
        2.292865
      ],
      [
        46.199373,
        0.069986
      ],
      [
        47.602138,
        2.330583
      ]
    ],
    "color": "#FF5723"
  }
]

```

```json
[
  {
    "name": "string",
    "type": 0,
    "data": [
      [
        0,
        0
      ],
      [
        0,
        0
      ]
    ],
    "color": "string"
  }
]

```

* **Response Body:** (error code `200`)

- Schema View
- JSON Example
- JSON View

* ▶`territories`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of territory objects.

```json
{
  "territories": [
    {
      "name": "North Region",
      "type": 1,
      "data": [
        [
          48.827865,
          2.379216
        ],
        [
          48.43446,
          5.234103
        ]
      ],
      "color": "#FF5733",
      "orders": [
        {
          "id": 879887,
          "creationTimestamp": 1752745377776,
          "customerInfo": {
            "id": 1838721,
            "alias": "Magic Customer",
            "firstName": "Magic",
            "lastName": "Customer",
            "address": {
              "country": "",
              "state": "",
              "county": "",
              "city": "",
              "postalCode": "",
              "streetName": "",
              "streetNumber": ""
            },
            "email": "magiccustomer@example.com",
            "phoneNumber": "+1202555018",
            "location": [
              48.870852,
              2.356148
            ],
            "customData": ""
          },
          "location": [
            48.870852,
            2.356148
          ],
          "alias": "Magic Order",
          "firstName": "Magic",
          "lastName": "Order",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "phoneNumber": "+1202555018",
          "customData": "",
          "type": 0,
          "status": 0,
          "state": 1,
          "priority": 0,
          "numberOfPackages": 3,
          "weight": 5.1,
          "cube": 2.5,
          "revenue": 12,
          "timeWindow": [
            420,
            1086
          ],
          "serviceTime": 0,
          "depotId": 0
        },
        {
          "id": 879888,
          "creationTimestamp": 1752745377776,
          "customerInfo": {
            "id": 1838722,
            "alias": "Magic Customer2",
            "firstName": "Magic",
            "lastName": "Customer2",
            "address": {
              "country": "",
              "state": "",
              "county": "",
              "city": "",
              "postalCode": "",
              "streetName": "",
              "streetNumber": ""
            },
            "email": "magiccustomer2@example.com",
            "phoneNumber": "+1202555018",
            "location": [
              48.870852,
              2.356148
            ],
            "customData": ""
          },
          "location": [
            48.827865,
            2.379216
          ],
          "alias": "Magic Order2",
          "firstName": "Magic2",
          "lastName": "Order2",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "phoneNumber": "+1202555019",
          "customData": "",
          "type": 0,
          "status": 0,
          "state": 1,
          "priority": 0,
          "numberOfPackages": 2,
          "weight": 4.5,
          "cube": 1.1,
          "revenue": 16,
          "timeWindow": [
            420,
            1086
          ],
          "serviceTime": 0,
          "depotId": 0
        }
      ]
    },
    {
      "name": "South Region",
      "type": 2,
      "data": [
        [
          48.88025,
          2.299601
        ],
        [
          48.897163,
          2.292865
        ],
        [
          46.199373,
          0.069986
        ],
        [
          47.602138,
          2.330583
        ]
      ],
      "color": "#FF5723",
      "orders": []
    }
  ]
}

```

```json
{
  "territories": [
    {
      "id": 0,
      "name": "string",
      "type": 0,
      "data": [
        [
          0,
          0
        ],
        [
          0,
          0
        ]
      ],
      "color": "string",
      "orders": {
        "orders": [
          {
            "id": 0,
            "creationTimestamp": 0,
            "customerInfo": {
              "id": 0,
              "alias": "string",
              "firstName": "string",
              "lastName": "string",
              "address": {
                "country": "string",
                "state": "string",
                "county": "string",
                "city": "string",
                "postalCode": "string",
                "streetName": "string",
                "streetNumber": "string",
                "extra": "string"
              },
              "email": "string",
              "phoneNumber": "string",
              "location": [
                0,
                0
              ],
              "customData": "string"
            },
            "location": [
              0,
              0
            ],
            "alias": "string",
            "firstName": "string",
            "lastName": "string",
            "address": {
              "country": "string",
              "state": "string",
              "county": "string",
              "city": "string",
              "postalCode": "string",
              "streetName": "string",
              "streetNumber": "string",
              "extra": "string"
            },
            "phoneNumber": "string",
            "customData": "string",
            "type": 0,
            "status": 0,
            "state": 1,
            "priority": 0,
            "numberOfPackages": 0,
            "weight": 0,
            "cube": 0,
            "revenue": 0,
            "timeWindow": [
              0,
              0
            ],
            "serviceTime": 0,
            "depotId": 0
          }
        ]
      }
    }
  ]
}

```

***

### 2. Get All Territories[​](#2-get-all-territories "Direct link to 2. Get All Territories")

**Description:** Fetches a list of all territories.

* **Base URL:** `https://api.magiclane.net/api/v1`

* **Endpoint:** `GET /fleetmanagement/territories`

* **Headers:**
  * `Authorization: YOUR_API_KEY`

* **Query Parameters:**

  * `search` (string, *optional*) – General search term across territories.
  * `id` (string, *optional*) – Filter by territory ID (`id=value:exact` for exact match).
  * `name` (string, *optional*) – Filter by territory name (`name=value:exact` for exact match).
  * `type` (string, *optional*) – Filter by territory type (`type=value`).
  * `data` (string, *optional*) – Filter by data (`data=value:exact` for exact match).
  * `color` (string, *optional*) – Filter by color (`color=value:exact` for exact match).
  * `sort` (string, *optional*) – Sorting format: `column1:asc/desc,column2:asc/desc`
    * Available columns: `id, name, type, data, color`
  * `includeColumns` (string, *optional*) – Specify which columns to include.
    <!-- -->
    * Available columns: `id, name, type, data, color`
  * `page` (integer, *optional*) – Page number for pagination.
  * `per_page` (integer, *optional*) – Number of items per page.

* **Returned error codes:**

| Error Code                  | Description                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| `200 Successful`            | Successful operation.                                                                      |
| `400 Bad Request`           | The values sent for page and per\_page parameters are incorrect; should be greater than 0. |
| `401 Unauthorized`          | API key is missing or invalid.                                                             |
| `405 Method Not Allowed`    | Incorrect method type.                                                                     |
| `500 Internal Server Error` | Database error occurred.                                                                   |

#### Example:[​](#example-1 "Direct link to Example:")

* **Response Body:** (error code `200`)

- Schema View
- JSON Example
- JSON View

* ▶`territories`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of territory objects.

```json
{
  "territories": [
    {
      "name": "North Region",
      "type": 1,
      "data": [
        [
          48.827865,
          2.379216
        ],
        [
          48.43446,
          5.234103
        ]
      ],
      "color": "#FF5733",
      "orders": [
        {
          "id": 879887,
          "creationTimestamp": 1752745377776,
          "customerInfo": {
            "id": 1838721,
            "alias": "Magic Customer",
            "firstName": "Magic",
            "lastName": "Customer",
            "address": {
              "country": "",
              "state": "",
              "county": "",
              "city": "",
              "postalCode": "",
              "streetName": "",
              "streetNumber": ""
            },
            "email": "magiccustomer@example.com",
            "phoneNumber": "+1202555018",
            "location": [
              48.870852,
              2.356148
            ],
            "customData": ""
          },
          "location": [
            48.870852,
            2.356148
          ],
          "alias": "Magic Order",
          "firstName": "Magic",
          "lastName": "Order",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "phoneNumber": "+1202555018",
          "customData": "",
          "type": 0,
          "status": 0,
          "state": 1,
          "priority": 0,
          "numberOfPackages": 3,
          "weight": 5.1,
          "cube": 2.5,
          "revenue": 12,
          "timeWindow": [
            420,
            1086
          ],
          "serviceTime": 0,
          "depotId": 0
        },
        {
          "id": 879888,
          "creationTimestamp": 1752745377776,
          "customerInfo": {
            "id": 1838722,
            "alias": "Magic Customer2",
            "firstName": "Magic",
            "lastName": "Customer2",
            "address": {
              "country": "",
              "state": "",
              "county": "",
              "city": "",
              "postalCode": "",
              "streetName": "",
              "streetNumber": ""
            },
            "email": "magiccustomer2@example.com",
            "phoneNumber": "+1202555018",
            "location": [
              48.870852,
              2.356148
            ],
            "customData": ""
          },
          "location": [
            48.827865,
            2.379216
          ],
          "alias": "Magic Order2",
          "firstName": "Magic2",
          "lastName": "Order2",
          "address": {
            "country": "",
            "state": "",
            "county": "",
            "city": "",
            "postalCode": "",
            "streetName": "",
            "streetNumber": ""
          },
          "phoneNumber": "+1202555019",
          "customData": "",
          "type": 0,
          "status": 0,
          "state": 1,
          "priority": 0,
          "numberOfPackages": 2,
          "weight": 4.5,
          "cube": 1.1,
          "revenue": 16,
          "timeWindow": [
            420,
            1086
          ],
          "serviceTime": 0,
          "depotId": 0
        }
      ]
    },
    {
      "name": "South Region",
      "type": 2,
      "data": [
        [
          48.88025,
          2.299601
        ],
        [
          48.897163,
          2.292865
        ],
        [
          46.199373,
          0.069986
        ],
        [
          47.602138,
          2.330583
        ]
      ],
      "color": "#FF5723",
      "orders": []
    }
  ]
}

```

```json
{
  "territories": [
    {
      "id": 0,
      "name": "string",
      "type": 0,
      "data": [
        [
          0,
          0
        ],
        [
          0,
          0
        ]
      ],
      "color": "string",
      "orders": {
        "orders": [
          {
            "id": 0,
            "creationTimestamp": 0,
            "customerInfo": {
              "id": 0,
              "alias": "string",
              "firstName": "string",
              "lastName": "string",
              "address": {
                "country": "string",
                "state": "string",
                "county": "string",
                "city": "string",
                "postalCode": "string",
                "streetName": "string",
                "streetNumber": "string",
                "extra": "string"
              },
              "email": "string",
              "phoneNumber": "string",
              "location": [
                0,
                0
              ],
              "customData": "string"
            },
            "location": [
              0,
              0
            ],
            "alias": "string",
            "firstName": "string",
            "lastName": "string",
            "address": {
              "country": "string",
              "state": "string",
              "county": "string",
              "city": "string",
              "postalCode": "string",
              "streetName": "string",
              "streetNumber": "string",
              "extra": "string"
            },
            "phoneNumber": "string",
            "customData": "string",
            "type": 0,
            "status": 0,
            "state": 1,
            "priority": 0,
            "numberOfPackages": 0,
            "weight": 0,
            "cube": 0,
            "revenue": 0,
            "timeWindow": [
              0,
              0
            ],
            "serviceTime": 0,
            "depotId": 0
          }
        ]
      }
    }
  ]
}

```

***

### 3. Get a Territory by ID[​](#3-get-a-territory-by-id "Direct link to 3. Get a Territory by ID")

**Description:** Retrieves a specific territory by ID.

* **Base URL:** `https://api.magiclane.net/api/v1`
* **Endpoint:** `GET /fleetmanagement/territories/{id}`
* **Headers:**
  * `Authorization: Bearer YOUR_API_KEY`
* **Path Parameter:**
  * `id` (integer, \**required*) - The unique territory ID.
* **Returned error codes:**

| Error Code                  | Description                               |
| --------------------------- | ----------------------------------------- |
| `200 Successful`            | Successful operation.                     |
| `400 Bad Request`           | Invalid input or missing required fields. |
| `401 Unauthorized`          | API key is missing or invalid.            |
| `404 Not Found`             | Territory not found in database.          |
| `405 Method Not Allowed`    | Incorrect method type.                    |
| `500 Internal Server Error` | Database error occurred.                  |

#### Example:[​](#example-2 "Direct link to Example:")

* **Response Body:** (error code `200`)

- Schema View
- JSON Example
- JSON View

* `id`(

  <!-- -->

  integer

  <!-- -->

  )

  Unique identifier for the territory.

* `name`(

  <!-- -->

  string

  <!-- -->

  )

  Name of the territory.

* `type`(

  <!-- -->

  integer

  <!-- -->

  )

  Territory type - Specifies the shape of the territory.

  * `0` - Polygon
  * `1` - Circle
  * `2` - Rectangle

* `data`(

  <!-- -->

  array\[double]

  <!-- -->

  )

  Defines the shape of the territory based on its type:

  * **Circle**: Contains the center and a point on the circle.
  * **Rectangle**: Contains two diagonally opposite points.
  * **Polygon**: Contains a list of points defining the area.

* `color`(

  <!-- -->

  string

  <!-- -->

  )

  Color associated with the territory.

* ▶`orders`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of orders associated with the territory.

```json
{
  "name": "North Region",
  "type": 1,
  "data": [
    [
      48.827865,
      2.379216
    ],
    [
      48.43446,
      5.234103
    ]
  ],
  "color": "#FF5733",
  "orders": [
    {
      "id": 879887,
      "creationTimestamp": 1752745377776,
      "customerInfo": {
        "id": 1838721,
        "alias": "Magic Customer",
        "firstName": "Magic",
        "lastName": "Customer",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "email": "magiccustomer@example.com",
        "phoneNumber": "+1202555018",
        "location": [
          48.870852,
          2.356148
        ],
        "customData": ""
      },
      "location": [
        48.870852,
        2.356148
      ],
      "alias": "Magic Order",
      "firstName": "Magic",
      "lastName": "Order",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "phoneNumber": "+1202555018",
      "customData": "",
      "type": 0,
      "status": 0,
      "state": 1,
      "priority": 0,
      "numberOfPackages": 3,
      "weight": 5.1,
      "cube": 2.5,
      "revenue": 12,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "depotId": 0
    },
    {
      "id": 879888,
      "creationTimestamp": 1752745377776,
      "customerInfo": {
        "id": 1838722,
        "alias": "Magic Customer2",
        "firstName": "Magic",
        "lastName": "Customer2",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "email": "magiccustomer2@example.com",
        "phoneNumber": "+1202555018",
        "location": [
          48.870852,
          2.356148
        ],
        "customData": ""
      },
      "location": [
        48.827865,
        2.379216
      ],
      "alias": "Magic Order2",
      "firstName": "Magic2",
      "lastName": "Order2",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "phoneNumber": "+1202555019",
      "customData": "",
      "type": 0,
      "status": 0,
      "state": 1,
      "priority": 0,
      "numberOfPackages": 2,
      "weight": 4.5,
      "cube": 1.1,
      "revenue": 16,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "depotId": 0
    }
  ]
}

```

```json
{
  "id": 0,
  "name": "string",
  "type": 0,
  "data": [
    [
      0,
      0
    ],
    [
      0,
      0
    ]
  ],
  "color": "string",
  "orders": {
    "orders": [
      {
        "id": 0,
        "creationTimestamp": 0,
        "customerInfo": {
          "id": 0,
          "alias": "string",
          "firstName": "string",
          "lastName": "string",
          "address": {
            "country": "string",
            "state": "string",
            "county": "string",
            "city": "string",
            "postalCode": "string",
            "streetName": "string",
            "streetNumber": "string",
            "extra": "string"
          },
          "email": "string",
          "phoneNumber": "string",
          "location": [
            0,
            0
          ],
          "customData": "string"
        },
        "location": [
          0,
          0
        ],
        "alias": "string",
        "firstName": "string",
        "lastName": "string",
        "address": {
          "country": "string",
          "state": "string",
          "county": "string",
          "city": "string",
          "postalCode": "string",
          "streetName": "string",
          "streetNumber": "string",
          "extra": "string"
        },
        "phoneNumber": "string",
        "customData": "string",
        "type": 0,
        "status": 0,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          0,
          0
        ],
        "serviceTime": 0,
        "depotId": 0
      }
    ]
  }
}

```

***

### 4. Update a Territory[​](#4-update-a-territory "Direct link to 4. Update a Territory")

**Description:** Updates an existing territory record.

* **Base URL:** `https://api.magiclane.net/api/v1`

* **Endpoint:** `PUT /fleetmanagement/territories/{id}`

* **Headers:**

  * `Authorization: YOUR_API_KEY`
  * `Content-Type: application/json`

* **Path Parameter:**
  * `id` (integer, \**required*) - Territory ID.

* **Returned error codes:**

| Error Code                  | Description                                                                                                                                                                                                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 Successful`            | Successful operation.                                                                                                                                                                                                                                                                             |
| `400 Bad Request`           | - Not all the points of the territory's data have 2 values (latitude, longitude).<br />- For polygon, the data should have 3 points; for circle and rectangle the territory’s data should have 2 points: the center of the circle and a point on the circle edge or 2 points diagonally opposite. |
| `401 Unauthorized`          | API key is missing or invalid.                                                                                                                                                                                                                                                                    |
| `404 Not Found`             | Territory not found in database.                                                                                                                                                                                                                                                                  |
| `405 Method Not Allowed`    | Incorrect method type.                                                                                                                                                                                                                                                                            |
| `500 Internal Server Error` | Database error occurred.                                                                                                                                                                                                                                                                          |

#### Example:[​](#example-3 "Direct link to Example:")

* **Request Body:**

- Schema View
- JSON Example
- JSON View

* `id`(

  <!-- -->

  integer

  <!-- -->

  )

  Unique identifier for the territory.

* `name`(

  <!-- -->

  string

  <!-- -->

  )

  Name of the territory.

* `type`(

  <!-- -->

  integer

  <!-- -->

  )

  Territory type - Specifies the shape of the territory.

  * `0` - Polygon
  * `1` - Circle
  * `2` - Rectangle

* `data`(

  <!-- -->

  array\[double]

  <!-- -->

  )

  Defines the shape of the territory based on its type:

  * **Circle**: Contains the center and a point on the circle.
  * **Rectangle**: Contains two diagonally opposite points.
  * **Polygon**: Contains a list of points defining the area.

* `color`(

  <!-- -->

  string

  <!-- -->

  )

  Color associated with the territory.

* ▶`orders`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of orders associated with the territory.

```json
{
  "name": "North Region",
  "type": 1,
  "data": [
    [
      48.827865,
      2.379216
    ],
    [
      48.43446,
      5.234103
    ]
  ],
  "color": "#FF5733",
  "orders": [
    {
      "id": 879887,
      "creationTimestamp": 1752745377776,
      "customerInfo": {
        "id": 1838721,
        "alias": "Magic Customer",
        "firstName": "Magic",
        "lastName": "Customer",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "email": "magiccustomer@example.com",
        "phoneNumber": "+1202555018",
        "location": [
          48.870852,
          2.356148
        ],
        "customData": ""
      },
      "location": [
        48.870852,
        2.356148
      ],
      "alias": "Magic Order",
      "firstName": "Magic",
      "lastName": "Order",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "phoneNumber": "+1202555018",
      "customData": "",
      "type": 0,
      "status": 0,
      "state": 1,
      "priority": 0,
      "numberOfPackages": 3,
      "weight": 5.1,
      "cube": 2.5,
      "revenue": 12,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "depotId": 0
    },
    {
      "id": 879888,
      "creationTimestamp": 1752745377776,
      "customerInfo": {
        "id": 1838722,
        "alias": "Magic Customer2",
        "firstName": "Magic",
        "lastName": "Customer2",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "email": "magiccustomer2@example.com",
        "phoneNumber": "+1202555018",
        "location": [
          48.870852,
          2.356148
        ],
        "customData": ""
      },
      "location": [
        48.827865,
        2.379216
      ],
      "alias": "Magic Order2",
      "firstName": "Magic2",
      "lastName": "Order2",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "phoneNumber": "+1202555019",
      "customData": "",
      "type": 0,
      "status": 0,
      "state": 1,
      "priority": 0,
      "numberOfPackages": 2,
      "weight": 4.5,
      "cube": 1.1,
      "revenue": 16,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "depotId": 0
    }
  ]
}

```

```json
{
  "id": 0,
  "name": "string",
  "type": 0,
  "data": [
    [
      0,
      0
    ],
    [
      0,
      0
    ]
  ],
  "color": "string",
  "orders": {
    "orders": [
      {
        "id": 0,
        "creationTimestamp": 0,
        "customerInfo": {
          "id": 0,
          "alias": "string",
          "firstName": "string",
          "lastName": "string",
          "address": {
            "country": "string",
            "state": "string",
            "county": "string",
            "city": "string",
            "postalCode": "string",
            "streetName": "string",
            "streetNumber": "string",
            "extra": "string"
          },
          "email": "string",
          "phoneNumber": "string",
          "location": [
            0,
            0
          ],
          "customData": "string"
        },
        "location": [
          0,
          0
        ],
        "alias": "string",
        "firstName": "string",
        "lastName": "string",
        "address": {
          "country": "string",
          "state": "string",
          "county": "string",
          "city": "string",
          "postalCode": "string",
          "streetName": "string",
          "streetNumber": "string",
          "extra": "string"
        },
        "phoneNumber": "string",
        "customData": "string",
        "type": 0,
        "status": 0,
        "state": 1,
        "priority": 0,
        "numberOfPackages": 0,
        "weight": 0,
        "cube": 0,
        "revenue": 0,
        "timeWindow": [
          0,
          0
        ],
        "serviceTime": 0,
        "depotId": 0
      }
    ]
  }
}

```

* **Response Body:** (error code `200`)

```json
{
  "message": "Operation done successfully",
}

```

***

### 5. Delete Territories[​](#5-delete-territories "Direct link to 5. Delete Territories")

**Description:** Deletes territories from the system.

* **Base URL:** `https://api.magiclane.net/api/v1`

* **Endpoint:** `DELETE /fleetmanagement/territories`

* **Headers:**

  * `Authorization: YOUR_API_KEY`
  * `Content-Type: application/json`

* **Returned error codes:**

| Error Code                  | Description                                                          |
| --------------------------- | -------------------------------------------------------------------- |
| `200 Successful`            | Successful operation.                                                |
| `401 Unauthorized`          | API key is missing or invalid.                                       |
| `404 Not Found`             | Can't delete territories because at least one of them does not exist |
| `405 Method Not Allowed`    | Incorrect method type.                                               |
| `500 Internal Server Error` | Database error occurred.                                             |

#### Example:[​](#example-4 "Direct link to Example:")

* **Request Body:**

```json
{
  "ids": [1234, 5678]
}

```

* **Response Body:** (error code `200`)

```json
{
  "message": "Operation done successfully",
}

```

***

### 6. Generate a Territory[​](#6-generate-a-territory "Direct link to 6. Generate a Territory")

**Description:** Automatically generates a territory based on provided parameters.The list of coordinates should contain at least 3 coordinates to create 1 territory. TerritoriesNumber, how many territories should be created (if is is 0, then the algorithm will determinate how many should be created).

* **Base URL:** `https://api.magiclane.net/api/v1`

* **Endpoint:** `POST /fleetmanagement/territories/generate`

* **Headers:**

  * `Authorization: YOUR_API_KEY`
  * `Content-Type: application/json`

* **Query Parameters:**

  * `auto` (integer, *optional*) - Controls automatic territory generation:

    <!-- -->

    * `0` (default): User must specify the number of territories to generate
    * `1`: Number of territories will be determined automatically

* **Returned error codes:**

| Error Code                  | Description                                                                                                                                                                   |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 Successful`            | Successful operation.                                                                                                                                                         |
| `400 Bad Request`           | - The number of locations is less than 3 and a territory needs at least 3 locations.<br />- The number of locations should be at least three times the number of territories. |
| `401 Unauthorized`          | API key is missing or invalid.                                                                                                                                                |
| `404 Not Found`             | Couldn't create that many territories. Try adding more coordinates or lower the number of territories.                                                                        |
| `405 Method Not Allowed`    | Incorrect method type.                                                                                                                                                        |
| `500 Internal Server Error` | Database error occurred.                                                                                                                                                      |

#### Example:[​](#example-5 "Direct link to Example:")

* **Request Body:**

- Schema View
- JSON Example
- JSON View

* `locations`(

  <!-- -->

  array\[array\[double]]

  <!-- -->

  )

  List of coordinates (\[latitude, longitude]) used to generate the territories.

* `territoriesNumber`(

  <!-- -->

  integer

  <!-- -->

  )

  How many territories should be created. If 0, the algorithm will determine the number.

```json
{
  "locations": [
    [
      48.870852,
      2.356148
    ],
    [
      48.827327,
      2.342267
    ],
    [
      48.88025,
      2.299601
    ],
    [
      48.845198,
      2.402896
    ],
    [
      48.887096,
      2.283513
    ],
    [
      48.896894,
      2.321586
    ],
    [
      48.870449,
      2.342204
    ],
    [
      48.895658,
      2.344043
    ],
    [
      48.458357,
      -0.054451
    ],
    [
      45.049782,
      2.475759
    ],
    [
      46.199373,
      0.069986
    ],
    [
      47.602138,
      2.330583
    ],
    [
      44.346051,
      4.694878
    ],
    [
      44.464582,
      2.45502
    ],
    [
      48.43446,
      5.234103
    ],
    [
      49.161539,
      0.50058
    ]
  ],
  "territoriesNumber": 3
}

```

```json
{
  "locations": [
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ],
    [
      0,
      0
    ]
  ],
  "territoriesNumber": 0
}

```

* **Response Body:** (error code `200`)

- Schema View
- JSON Example
- JSON View

* ▶`territories`(

  <!-- -->

  array\[object]

  <!-- -->

  )

  List of territory objects.

```json
{
  "territories": [
    {
      "id": 879888,
      "name": "Territory 0",
      "type": 0,
      "data": [
        [
          44.464582,
          2.45502
        ],
        [
          48.887096,
          2.283513
        ],
        [
          48.896894,
          2.321586
        ],
        [
          48.870449,
          2.342204
        ],
        [
          48.895658,
          2.344043
        ]
      ],
      "color": "#FF5733"
    },
    {
      "id": 879887,
      "name": "Territory 1",
      "type": 0,
      "data": [
        [
          49.161539,
          0.50058
        ],
        [
          44.346051,
          4.694878
        ],
        [
          48.870852,
          2.356148
        ],
        [
          48.827327,
          2.342267
        ],
        [
          48.88025,
          2.299601
        ],
        [
          48.845198,
          2.402896
        ]
      ],
      "color": "#FF5723"
    },
    {
      "id": 879886,
      "name": "Territory 2",
      "type": 0,
      "data": [
        [
          48.43446,
          5.234103
        ],
        [
          48.458357,
          -0.054451
        ],
        [
          45.049782,
          2.475759
        ],
        [
          46.199373,
          0.069986
        ],
        [
          47.602138,
          2.330583
        ]
      ],
      "color": "#FF5743"
    }
  ]
}

```

```json
{
  "territories": [
    {
      "id": 0,
      "name": "string",
      "type": 0,
      "data": [
        [
          0,
          0
        ],
        [
          0,
          0
        ],
        [
          0,
          0
        ]
      ],
      "color": "string",
      "orders": {
        "orders": [
          {
            "id": 0,
            "creationTimestamp": 0,
            "customerInfo": {
              "id": 0,
              "alias": "string",
              "firstName": "string",
              "lastName": "string",
              "address": {
                "country": "string",
                "state": "string",
                "county": "string",
                "city": "string",
                "postalCode": "string",
                "streetName": "string",
                "streetNumber": "string",
                "extra": "string"
              },
              "email": "string",
              "phoneNumber": "string",
              "location": [
                0,
                0
              ],
              "customData": "string"
            },
            "location": [
              0,
              0
            ],
            "alias": "string",
            "firstName": "string",
            "lastName": "string",
            "address": {
              "country": "string",
              "state": "string",
              "county": "string",
              "city": "string",
              "postalCode": "string",
              "streetName": "string",
              "streetNumber": "string",
              "extra": "string"
            },
            "phoneNumber": "string",
            "customData": "string",
            "type": 0,
            "status": 0,
            "state": 1,
            "priority": 0,
            "numberOfPackages": 0,
            "weight": 0,
            "cube": 0,
            "revenue": 0,
            "timeWindow": [
              0,
              0
            ],
            "serviceTime": 0,
            "depotId": 0
          }
        ]
      }
    },
    {
      "id": 0,
      "name": "string",
      "type": 0,
      "data": [
        [
          0,
          0
        ],
        [
          0,
          0
        ],
        [
          0,
          0
        ]
      ],
      "color": "string",
      "orders": {
        "orders": [
          {
            "id": 0,
            "creationTimestamp": 0,
            "customerInfo": {
              "id": 0,
              "alias": "string",
              "firstName": "string",
              "lastName": "string",
              "address": {
                "country": "string",
                "state": "string",
                "county": "string",
                "city": "string",
                "postalCode": "string",
                "streetName": "string",
                "streetNumber": "string",
                "extra": "string"
              },
              "email": "string",
              "phoneNumber": "string",
              "location": [
                0,
                0
              ],
              "customData": "string"
            },
            "location": [
              0,
              0
            ],
            "alias": "string",
            "firstName": "string",
            "lastName": "string",
            "address": {
              "country": "string",
              "state": "string",
              "county": "string",
              "city": "string",
              "postalCode": "string",
              "streetName": "string",
              "streetNumber": "string",
              "extra": "string"
            },
            "phoneNumber": "string",
            "customData": "string",
            "type": 0,
            "status": 0,
            "state": 1,
            "priority": 0,
            "numberOfPackages": 0,
            "weight": 0,
            "cube": 0,
            "revenue": 0,
            "timeWindow": [
              0,
              0
            ],
            "serviceTime": 0,
            "depotId": 0
          }
        ]
      }
    },
    {
      "id": 0,
      "name": "string",
      "type": 0,
      "data": [
        [
          0,
          0
        ],
        [
          0,
          0
        ],
        [
          0,
          0
        ]
      ],
      "color": "string",
      "orders": {
        "orders": [
          {
            "id": 0,
            "creationTimestamp": 0,
            "customerInfo": {
              "id": 0,
              "alias": "string",
              "firstName": "string",
              "lastName": "string",
              "address": {
                "country": "string",
                "state": "string",
                "county": "string",
                "city": "string",
                "postalCode": "string",
                "streetName": "string",
                "streetNumber": "string",
                "extra": "string"
              },
              "email": "string",
              "phoneNumber": "string",
              "location": [
                0,
                0
              ],
              "customData": "string"
            },
            "location": [
              0,
              0
            ],
            "alias": "string",
            "firstName": "string",
            "lastName": "string",
            "address": {
              "country": "string",
              "state": "string",
              "county": "string",
              "city": "string",
              "postalCode": "string",
              "streetName": "string",
              "streetNumber": "string",
              "extra": "string"
            },
            "phoneNumber": "string",
            "customData": "string",
            "type": 0,
            "status": 0,
            "state": 1,
            "priority": 0,
            "numberOfPackages": 0,
            "weight": 0,
            "cube": 0,
            "revenue": 0,
            "timeWindow": [
              0,
              0
            ],
            "serviceTime": 0,
            "depotId": 0
          }
        ]
      }
    }
  ]
}

```

***

### 7. Get Orders from Territory[​](#7-get-orders-from-territory "Direct link to 7. Get Orders from Territory")

**Description:** Retrieves all orders assigned to a specific territory.

* **Base URL:** `https://api.magiclane.net/api/v1`
* **Endpoint:** `GET /fleetmanagement/territories/{id}/orders`
* **Headers:**
  * `Authorization: YOUR_API_KEY`
* **Path Parameter:**
  * `id` (integer, \**required*) - The unique territory ID.
* **Returned error codes:**

| Error Code                  | Description                      |
| --------------------------- | -------------------------------- |
| `200 Successful`            | Successful operation.            |
| `401 Unauthorized`          | API key is missing or invalid.   |
| `404 Not Found`             | Territory not found in database. |
| `405 Method Not Allowed`    | Incorrect method type.           |
| `500 Internal Server Error` | Database error occurred.         |

* **Response Body:** (error code `200`)

- Schema View
- JSON Example
- JSON View

* ▶`orders`(

  <!-- -->

  array

  <!-- -->

  )

  List of order objects.

```json
{
  "orders": [
    {
      "id": 879887,
      "creationTimestamp": 1752745377776,
      "customerInfo": {
        "id": 1838721,
        "alias": "Magic Customer",
        "firstName": "Magic",
        "lastName": "Customer",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "email": "magiccustomer@example.com",
        "phoneNumber": "+1202555018",
        "location": [
          48.870852,
          2.356148
        ],
        "customData": ""
      },
      "location": [
        48.870852,
        2.356148
      ],
      "alias": "Magic Order",
      "firstName": "Magic",
      "lastName": "Order",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "phoneNumber": "+1202555018",
      "customData": "",
      "type": 0,
      "status": 0,
      "state": 1,
      "priority": 0,
      "numberOfPackages": 3,
      "weight": 5.1,
      "cube": 2.5,
      "revenue": 12,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "depotId": 0
    },
    {
      "id": 879888,
      "creationTimestamp": 1752745377776,
      "customerInfo": {
        "id": 1838722,
        "alias": "Magic Customer2",
        "firstName": "Magic",
        "lastName": "Customer2",
        "address": {
          "country": "",
          "state": "",
          "county": "",
          "city": "",
          "postalCode": "",
          "streetName": "",
          "streetNumber": ""
        },
        "email": "magiccustomer2@example.com",
        "phoneNumber": "+1202555018",
        "location": [
          48.870852,
          2.356148
        ],
        "customData": ""
      },
      "location": [
        48.827865,
        2.379216
      ],
      "alias": "Magic Order2",
      "firstName": "Magic2",
      "lastName": "Order2",
      "address": {
        "country": "",
        "state": "",
        "county": "",
        "city": "",
        "postalCode": "",
        "streetName": "",
        "streetNumber": ""
      },
      "phoneNumber": "+1202555019",
      "customData": "",
      "type": 0,
      "status": 0,
      "state": 1,
      "priority": 0,
      "numberOfPackages": 2,
      "weight": 4.5,
      "cube": 1.1,
      "revenue": 16,
      "timeWindow": [
        420,
        1086
      ],
      "serviceTime": 0,
      "depotId": 0
    }
  ]
}

```

```json
{
  "orders": [
    {
      "id": 0,
      "creationTimestamp": 0,
      "customerInfo": {
        "id": 0,
        "alias": "string",
        "firstName": "string",
        "lastName": "string",
        "address": {
          "country": "string",
          "state": "string",
          "county": "string",
          "city": "string",
          "postalCode": "string",
          "streetName": "string",
          "streetNumber": "string",
          "extra": "string"
        },
        "email": "string",
        "phoneNumber": "string",
        "location": [
          0,
          0
        ],
        "customData": "string"
      },
      "location": [
        0,
        0
      ],
      "alias": "string",
      "firstName": "string",
      "lastName": "string",
      "address": {
        "country": "string",
        "state": "string",
        "county": "string",
        "city": "string",
        "postalCode": "string",
        "streetName": "string",
        "streetNumber": "string",
        "extra": "string"
      },
      "phoneNumber": "string",
      "customData": "string",
      "type": 0,
      "status": 0,
      "state": 1,
      "priority": 0,
      "numberOfPackages": 0,
      "weight": 0,
      "cube": 0,
      "revenue": 0,
      "timeWindow": [
        0,
        0
      ],
      "serviceTime": 0,
      "depotId": 0
    }
  ]
}

```

***
