---
# System prepended metadata

title: Leta Dispatch System Developer Integration
tags: [Integration Leta, Leta Integration, Leta, Leta API]

---

---
title: 'Leta Integration API'
disqus: hackmd
---

Leta Integration API
===

## Table of Contents

[TOC]

Sandbox Domain is `https://sandbox.integrations.leta.ai`
Production Domain is `https://integrations.leta.ai`

## Overview

This is a guide for developers from different organizations to plug into Leta management system and inject orders directly from their platforms.
The orders can then be managed from Leta cloud and dispatched to connected drivers for delivery.

## Developer Flow
A user with the `admin` permission has access to create a `Developer App`.
Log in to your Leta Dashboard, on the sidebar, click on `Integrations`. From here, you can create the app, add your `callback/webhook url` and a few other required details. The url specified is where you will receive your webhooks after an order changes state/status.
After creating the app, you will get the option to generate a token/key. Press this button and a token will be generated and sent to the email which was used to register the company on Leta. Use this key to authenticate your requests to this API.


## 1. Adding Orders

#### Endpoint
Make a `POST` request to the following endpoint:
`<domain>/orders/add`

#### Authentication
Add an `Authorization` header whose value will be your token as illustrated below:

```Authorization: Bearer <your_token_here>```

#### Request Body
Pass in a valid JSON payload as your body. See the table below for more details:


| Name                      | Data Type | Description                                                                                                                                | Default   | Required |
|---------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------|-----------|----------|
| `reference`               | `string`  | unique identifier for your order                                                                                                           | N/A       | True     |
| `cargo_description`       | `string`  | a description of your order                                                                                                                | N/A       | True     |
| `special_instruction`     | `string`  | extra details or very specific information about your order                                                                                | N/A       | False    |
| `customer`.`phone_number` | `string`  | customer's phone number. You must pass either `customer`.`phone_number` or `customer`.`email`. You can also pass both values if available. | N/A       | False    |
| `customer`.`email`        | `string`  | customer's email. You must pass either `customer`.`email` or `customer`.`phone_number`. You can also pass both values if available.        | N/A       | False    |
| `customer`.`name`         | `string`  | customer's name                                                                                                                            | N/A       | False    |
| `payment_method`          | `string`  | the preferred way to pay for the order. The options are `prepaid`, `postpaid_cash`, `postpaid_mobile_money`, `credit`                      | `prepaid` | False    |
| `depot_code`              | `string`  | the order's origin's depot code or api key. The depot will take precedence over pickup coordinates                                         | N/A       | False    |
| `dropoff_address`         | `string`  | drop off point's physical address, mutually exclusive to `dropoff`                                                                         | N/A       | False    |
| `dropoff`.`name`          | `string`  | name of the destination/drop off location/address                                                                                          | N/A       | True     |
| `dropoff`.`latitude`      | `string`  | latitude coordinate of the destination/drop off location/address                                                                           | N/A       | True     |
| `dropoff`.`longitude`     | `string`  | longitude coordinate of the destination/drop off location/address                                                                          | N/A       | True     |
| `pickup`.`name`           | `string`  | name of the origin/pickup location/address                                                                                                 | N/A       | False    |
| `pickup`.`latitude`       | `string`  | latitude coordinate of the origin/pickup location/address                                                                                  | N/A       | False    |
| `pickup`.`longitude`      | `string`  | longitude coordinate of the origin/pickup location/address                                                                                 | N/A       | False    |
| `total_weight`            | `float`   | the weight in kilograms of the order                                                                                                       | N/A       | False    |
| `total_price`             | `float`   | the total price of the order                                                                                                               | N/A       | False    |
| `delivery_fee`            | `float`   | the delivery/shipping fee for this order                                                                                                   | `0`       | False    |
| `products`                | `list`    | a list of products. Refer [here](https://hackmd.io/ZQRf_lalTsGRSCUxmk1Hvw?view#Products-Format) for product format                         | N/A       | False    |
| `is_return_order`         | `boolean` | if true, the pickup location becomes the drop off location and vice versa. <br/>Use this to distinguish orders which are items/goods/collectibles from your customer and not from your store. | `false`   | False    |
| `earliest_delivery_time`  | `string`  | the earliest time the order can be delivered. This is a string in ISO 8601 format, e.g; `2022-06-01T21:00:00.971Z`                                                                                                                                                            | N/A       | False    |
| `latest_delivery_time`    | `string`  | the latest time the order can be delivered. This is a string in ISO 8601 format, e.g; `2022-06-01T21:00:00.971Z`                                                                                                                                                              | N/A       | False    |
| `lead_time`               | `integer` | the time in seconds it will take to prepare the order. This is used to calculate the delivery time. Use this value to define the maximum time in seconds that an order should sit in the status `scheduled` before being automatically transitioned into the status `pending` | `0`       | False    |

**NB: You do not have to pass in `pickup`.`name`, `pickup`.`latitude` and `pickup`.`longitude` if you have passed in `depot_code`**


#### Products Format

| Name       | Data Type | Description                        | Default  | Required |
|------------|-----------|------------------------------------|----------|----------|
| `code`     | `string`  | unique identifier for your product | N/A      | True     |
| `quantity` | `integer` | the quantity of the product/item   | N/A      | True     |

#### Example Request Body

```json=
{
    "customer": {
        "phone_number": "+2547000000000",
        "email": "customer@example.com",
        "name": "john doe"
    },
    "reference": "TESTREF",
    "special_instruction": "handle with extreme care my guy",
    "cargo_description": "A lot of stuff here",
    "dropoff": {
        "name": "malindi beach resort",
        "latitude": "-1.9450453",
        "longitude": "39.045854"
    },
    "pickup": {
        "name": "diani beach resort",
        "latitude": "-1.893404",
        "longitude": "39.445854"
    },
    "payment_method": "postpaid",
    "depot_code": "some-good-code",
    "products": [
       {
           "code": "5464",
           "quantity": 26,
           "price": 567.99
       }
    ]
}
```

#### Sample Responses

**A. Unauthorized requests**

```json=
{
    "status_code": 401,
    "detail": "Authentication credentials were not provided."
}
```
Missing authentication credentials

**OR**

```json=
{
    "status_code": 401,
    "detail": "Invalid credentials."
}
```
Incorrect authentication credentials

**B. Bad Request**

```json=
{
    "status_code": 400,
    "detail": "Key: 'OrderInput.CargoDescription' Error:Field validation for 'CargoDescription' failed on the 'required' tag"
}
```
Missing field `cargo_description`

**C. Success (Order added successfully)**
```json=
{
    "status_code": 200,
    "detail": {
        "id": 1003,
        "slug": "YKacdQc",
        "reference": "TESTREF",
        "special_instruction": "handle with extreme care my guy",
        "cargo_description": "A lot of stuff here",
        "status": "pending",
        "origin": {
            "name": "diani beach resort",
            "latitude": "-1.893404",
            "longitude": "39.445854"
        },
        "destination": {
            "name": "malindi beach resort",
            "latitude": "-1.9450453",
            "longitude": "39.045854"
        },
        "direct_distance": 3737,
        "payment_method": "postpaid_mobile_money",
        "total_price": 3270,
        "depot": {
            "name": "ABC Place",
            "code": "some-good-code"
        },
        "is_paid": false,
        "recipient": {
            "phone_number": "+2547000000000",
            "email": "customer@example.com",
            "name": "john doe"
        },
        "delivery_fee": 0,
        "leta_delivery_charge": 330
    }
}
```

Order added successfully

## 2. Update Orders
This endpoint is used to update an existing order's destination and customer details.
Orders with the status `cancelled`, `delivered` or `failed` **cannot** be updated.
The request body and response format is similar to the one for adding orders.

#### Endpoint
Make a `PUT` request to the following endpoint:
`<domain>/orders/update`

#### Authentication
Add an `Authorization` header whose value will be your token as illustrated below:

```Authorization: Bearer <your_token_here>```

#### Request Body
Pass in a valid JSON payload as your body. See the table below for more details:

| Name                      | Data Type | Description                                                                                                                                | Default | Required |
|---------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------|---------|----------|
| `reference`               | `string`  | unique identifier for your order (reference number on Leta)                                                                                                          | N/A     | True     |
| `dropoff`.`name`          | `string`  | name of the destination/drop off location/address                                                                                          | N/A     | True     |
| `dropoff`.`latitude`      | `string`  | latitude coordinate of the destination/drop off location/address                                                                           | N/A     | True     |
| `dropoff`.`longitude`     | `string`  | longitude coordinate of the destination/drop off location/address                                                                          | N/A     | True     |
| `customer`.`phone_number` | `string`  | customer's phone number. You must pass either `customer`.`phone_number` or `customer`.`email`. You can also pass both values if available. | N/A     | False    |
| `customer`.`email`        | `string`  | customer's email. You must pass either `customer`.`email` or `customer`.`phone_number`. You can also pass both values if available.        | N/A     | False    |
| `customer`.`name`         | `string`  | customer's name                                                                                                                            | N/A     | False    |

#### Example Request Body

```json=
{
  "reference": "LT-00-001",
  "dropoff": {
    "name": "malindi beach resort",
    "latitude": "-1.9450453",
    "longitude": "39.045854"
  },
  "customer": {
    "phone_number": "+2547000000000",
    "email": "cust@mail.com"
  }
}
```

#### Sample Responses
**A. Success (Order Updated successfully)**

```json=
{
  "status_code": 200,
  "detail": {
    "id": 7963,
    "slug": "36-9",
    "reference": "LT-00-001",
    "special_instruction": "This is way up",
    "cargo_description": "One hundred and seventy nine items to be delivered.",
    "status": "pending",
    "origin_id": 5076,
    "origin": {
      "Id": 5076,
      "Created": "2023-04-28T12:27:41.158153Z",
      "Updated": "2023-04-28T12:27:41.158191Z",
      "Latitude": "-1.2860273",
      "Longitude": "36.8079678",
      "Name": "Regus - Nairobi, Vienna Court, State House Avenue, Nairobi, Kenya"
    },
    "destination_id": 5171,
    "destination": {
      "Id": 5171,
      "Created": "2023-10-17T09:23:52.632072Z",
      "Updated": "2023-10-17T09:23:52.632095Z",
      "Latitude": "-1.2314375",
      "Longitude": "36.7406875",
      "Name": "The Arc - Kitisuru"
    },
    "payment_method": "prepaid",
    "total_price": 0,
    "depot_id": 223,
    "depot": {
      "Id": 223,
      "name": "Vienna",
      "code": "b03YJ5"
    }
  }
}
```

**B. Failed (Order does NOT exist)**
```json=
{
  "status_code": 404,
  "detail": "Order does not exist"
}
```

**C. Failed (Order is in a complete state)**
```json
{
  "status_code": 400,
  "detail": "Order with status cancelled can not be updated"
}
```

## 3. Order Cancellation
This endpoint is used to cancel orders.
**NB: Only orders with the statuses `pending` and `broadcasted`  can be cancelled.**

#### Endpoint
Make a `POST` request to the following endpoint:
`<domain>/orders/cancel`

#### Authentication
Add an `Authorization` header whose value will be your token as illustrated below:

```Authorization: Bearer <your_token_here>```

#### Request Body
Pass in a valid JSON payload as your body. See the table below for more details:

| Name        | Data Type | Description                      | Default | Required |
|-------------|-----------|----------------------------------|---------|----------|
| `reference` | `string`  | unique identifier for your order | N/A     | True     |

#### Example Request Body

```json=
{
  "reference": "LT-00-001"
}
```
#### Sample Responses
**A. Success (Order Cancelled successfully)**

```json=
{
  "status_code": 200,
  "detail": "Order with reference LT-00-001 has been cancelled"
}
```

**B. Failed (Order NOT Cancelled successfully)**

```json=
{
  "status_code": 400,
  "detail": "Order with reference LT-00-001 has already been cancelled"
}
```
```json=
{
  "status_code": 400,
  "detail": "Order with reference LT-00-001 cannot be cancelled because it is in assigned status"
}
```

```json=
{
  "status_code": 400,
  "detail": "Order with reference LT-00-001 has already been delivered"
}
```

**C. Failed (Order does NOT exist)**
```json
{
  "status_code": 404,
  "detail": "Order with reference LT-00-001 does not exist"
}
```


## 4. Adding Depots (Store/Outlet)
This endpoint is used to create depots (stores/outlets) on Leta.

#### Endpoint
Make a `POST` request to the following endpoint:
`<domain>/depots/create/`

#### Authentication
Add an `Authorization` header whose value will be your token as illustrated below:

```Authorization: Bearer <your_token_here>```

#### Request Body
Pass in a valid JSON payload as your body. See the table below for more details:

| Name                      | Data Type | Description                                                                                                | Default | Required |
|---------------------------|-----------|------------------------------------------------------------------------------------------------------------|---------|----------|
| `name`                    | `string`  | unique identifier for your depot                                                                           | N/A     | True     |
| `code`                    | `string`  | unique code for your depot; Generated if not provided                                                      | N/A     | False    |
| `location.latitude`       | `float`   | the latitude coordinate for your depot location                                                            | N/A     | True     |
| `location.longitude`      | `float`   | the longitude coordinate for your depot location                                                           | N/A     | True     |
| `location.name`           | `string`  | the physical address for your depot                                                                        | N/A     | True     |
| `pickup_geofence_type`    | `string`  | the pickup geofence type                                                                                   | `soft`  | False    |
| `pickup_geofence_radius`  | `number`  | the pickup geofence radius in metres                                                                       | `500`   | False    |
| `dropoff_geofence_type`   | `string`  | the drop off geofence type                                                                                 | `soft`  | False    |
| `dropoff_geofence_radius` | `number`  | the drop off geofence radius in metres                                                                     | `500`   | False    |
| `order_pickup_ready`      | `boolean` | whether the orders from this depot should await orders to be marked as ready before drivers confirm pickup | `false` | False    |
| `restricted_radius`       | `number`  | the maximum broadcast radius                                                                               | `1000`  | False    |
| `order_wait_time`         | `number`  | the number of seconds that an order sits for in the queue before it broadcasts                             | `15`    | False    |
| `max_orders`              | `number`  | the maximum batch size for broadcasted orders                                                              | `1`     | False    |

#### Example Request Body

```json=
{
  "name": "ABC Place",
  "code": "some-good-code",
  "location": {
    "latitude": -1.2860273,
    "longitude": 36.8079678,
    "name": "Regus - Nairobi, Vienna Court, State House Avenue, Nairobi, Kenya"
  },
  "pickup_geofence_type": "soft",
  "pickup_geofence_radius": 500,
  "dropoff_geofence_type": "soft",
  "dropoff_geofence_radius": 500,
  "order_pickup_ready": false,
  "restricted_radius": 1000,
  "order_wait_time": 15,
  "max_orders": 1
}
```
#### Sample Responses
**A. Success (Depot Created successfully)**

```json=
{
  "status_code": 200,
  "detail": {
    "id": 223,
    "name": "ABC Place",
    "code": "some-good-code",
    "location": {
      "latitude": "-1.2860273",
      "longitude": "36.8079678",
      "name": "Regus - Nairobi, Vienna Court, State House Avenue, Nairobi, Kenya"
    },
    "pickup_geofence_type": "soft",
    "pickup_geofence_radius": 500,
    "dropoff_geofence_type": "soft",
    "dropoff_geofence_radius": 500,
    "order_pickup_ready": false,
    "restricted_radius": 1000,
    "order_wait_time": 15,
    "max_orders": 1
  }
}
```

**B. Failed (Depot Already Exists)**

```json=
{
  "status_code": 400,
  "detail": "Depot with name ABC Place already exists"
}
```
## 5. Update Depots (Store/Outlet)
#### Endpoint
Make a `PUT` request to the following endpoint:
`<domain>/depots/{depot_code}/update/`

#### Authentication
Add an `Authorization` header whose value will be your token as illustrated below:

```Authorization: Bearer <your_token_here>```

#### Path Parameters
| Name         | Data Type | Description              | Default | Required |
|--------------|-----------|--------------------------|---------|----------|
| `depot_code` | `string`  | The depot's code on Leta | N/A     | True     |


#### Request Body
Pass in a valid JSON payload as your body. See the table below for more details:


| Name                      | Data Type | Description                                                                                                | Default | Required |
|---------------------------|-----------|------------------------------------------------------------------------------------------------------------|---------|----------|
| `name`                    | `string`  | unique identifier for your depot                                                                           | N/A     | True     |
| `code`                    | `string`  | unique code for your depot; Generated if not provided                                                      | N/A     | False    |
| `location.latitude`       | `float`   | the latitude coordinate for your depot location                                                            | N/A     | True     |
| `location.longitude`      | `float`   | the longitude coordinate for your depot location                                                           | N/A     | True     |
| `location.name`           | `string`  | the physical address for your depot                                                                        | N/A     | True     |
| `pickup_geofence_type`    | `string`  | the pickup geofence type                                                                                   | `soft`  | False    |
| `pickup_geofence_radius`  | `number`  | the pickup geofence radius in metres                                                                       | `500`   | False    |
| `dropoff_geofence_type`   | `string`  | the drop off geofence type                                                                                 | `soft`  | False    |
| `dropoff_geofence_radius` | `number`  | the drop off geofence radius in metres                                                                     | `500`   | False    |
| `order_pickup_ready`      | `boolean` | whether the orders from this depot should await orders to be marked as ready before drivers confirm pickup | `false` | False    |
| `restricted_radius`       | `number`  | the maximum broadcast radius                                                                               | `1000`  | False    |
| `order_wait_time`         | `number`  | the number of seconds that an order sits for in the queue before it broadcasts                             | `15`    | False    |
| `max_orders`              | `number`  | the maximum batch size for broadcasted orders                                                              | `1`     | False    |

#### Example Request Body

```json=
{
  "name": "ABC Place",
  "code": "some-good-code",
  "location": {
    "latitude": -1.2860273,
    "longitude": 36.8079678,
    "name": "Regus - Nairobi, Vienna Court, State House Avenue, Nairobi, Kenya"
  },
  "pickup_geofence_type": "soft",
  "pickup_geofence_radius": 500,
  "dropoff_geofence_type": "soft",
  "dropoff_geofence_radius": 500,
  "order_pickup_ready": false,
  "restricted_radius": 1000,
  "order_wait_time": 15,
  "max_orders": 1
}
```
#### Sample Responses
**A. Success (Depot Updated successfully)**

```json=
{
  "status_code": 200,
  "detail": {
    "id": 223,
    "name": "ABC Place",
    "code": "some-good-code",
    "location": {
      "latitude": "-1.2860273",
      "longitude": "36.8079678",
      "name": "Regus - Nairobi, Vienna Court, State House Avenue, Nairobi, Kenya"
    },
    "pickup_geofence_type": "soft",
    "pickup_geofence_radius": 500,
    "dropoff_geofence_type": "soft",
    "dropoff_geofence_radius": 500,
    "order_pickup_ready": false,
    "restricted_radius": 1000,
    "order_wait_time": 15,
    "max_orders": 1
  }
}
```

**B. Failed (Depot does NOT Exists)**

```json=
{
  "status_code": 404,
  "detail": "Depot with code some-good-code does not exist"
}
```
## 6. Adding Products
#### Endpoint
Make a `POST` request to the following endpoint:
`/products/create/`

##### Authentication
Add an `Authorization` header whose value will be your token as illustrated below:

```Authorization: <your_token_here>```

OR

```Authorization: Bearer <your_token_here>```

##### Request Body
Pass in a valid JSON payload as your body. See the table below for more details:

| Name    | Data Type | Description                                           | Default | Required |
|---------|-----------|-------------------------------------------------------|---------|----------|
| `name`  | `string`  | unique identifier for your depot                      | N/A     | True     |
| `code`  | `string`  | unique code for your depot; Generated if not provided | N/A     | False    |
| `price` | `float`   | the price of your product                             | N/A     | True     |


##### Example Request Body

```json=
{
  "name": "Text Book",
  "code": "tBz-09op-ir"
}
```

##### Sample Responses
**A. Success (Product Created successfully)**

```json=
{
  "status_code": 201,
  "detail": {
    "id": 4351,
    "name": "Text Book",
    "code": "tBz-09op-ir",
    "company_id": 9,
    "weight": 0,
    "dimension_units": "cm",
    "price": 0,
    "length": 0,
    "width": 0,
    "height": 0,
    "weight_units": "kg",
    "created": "2025-11-21T10:58:36.305411+03:00",
    "updated": "2025-11-21T10:58:36.305411+03:00"
  }
}
```

**B. Failed (Product Already Exists)**

```json=
{
  "status_code": 400,
  "detail": "A product with this name already exists under your company"
}
```
## 7. Updating Products
#### Endpoint
Make a `PUT` request to the following endpoint:
`/products/{product_code}/update/`

The `product_code` should match the code of the product on Leta you want to update.

##### Authentication
Add an `Authorization` header whose value will be your token as illustrated below:  
```Authorization: <your_token_here>```

##### Path Parameters
| Name           | Data Type | Description                | Default | Required |
|----------------|-----------|----------------------------|---------|----------|
| `product_code` | `string`  | The product's code on Leta | N/A     | True     |

##### Request Body
Pass in a valid JSON payload as your body. See the table below for more details:

| Name    | Data Type | Description                                           | Default | Required |
|---------|-----------|-------------------------------------------------------|---------|----------|
| `name`  | `string`  | unique identifier for your depot                      | N/A     | True     |
| `code`  | `string`  | unique code for your depot; Generated if not provided | N/A     | False    |
| `price` | `float`   | the price of your product                             | N/A     | True     |


##### Example Request Body

```json=
{
  "name": "Text Book",
  "code": "tBz-09op-ir",
  "price": 210.50
}
```

##### 5. Sample Responses
**A. Success (Product Updated successfully)**

```json=
{
  "status_code": 200,
  "detail": {
    "id": 4351,
    "name": "Text Book",
    "code": "tBz-09op-ir",
    "company_id": 9,
    "weight": 0,
    "dimension_units": "cm",
    "price": 210.5,
    "length": 0,
    "width": 0,
    "height": 0,
    "weight_units": "kg",
    "created": "2025-11-21T07:58:36.305411Z",
    "updated": "2025-11-21T11:09:40.634404+03:00"
  }
}
```
**B. Failed (Product does NOT exist)**

```json=
{
  "status_code": 404,
  "detail": "No product found with the provided code"
}
```
## 8. Shipping Rates Calculation
This endpoint is used to calculate the shipping/delivery fee for a set of coordinates.

#### Endpoint
Make a `POST` request to the following endpoint:
`<domain>/shipping/rates/calculate/`

#### Authentication
Add an `Authorization` header whose value will be your token as illustrated below:

```Authorization: Bearer <your_token_here>```

#### Request Body
Pass in a valid JSON payload as your body. See the table below for more details:

| Name                      | Data Type | Description                      | Default | Required |
|---------------------------|-----------|----------------------------------|---------|----------|
| `origin`.`latitude`       | `float`   | The pickup location's latitude   | N/A     | True     |
| `origin`.`longitude`      | `float`   | The pickup location's longitude  | N/A     | True     |
| `destination`.`latitude`  | `float`   | The dropoff location's latitude  | N/A     | True     |
| `destination`.`longitude` | `float`   | The dropoff location's longitude | N/A     | True     |


#### Example Request Body
```json=
{
    "origin": {
        "latitude": -1.9450453,
        "longitude": 39.045854
    },
    "destination": {
        "latitude": -1.893404,
        "longitude": 39.445854
    }
}
```


#### Sample Responses
**A. Success (Rates Calculated successfully)**
The destination is within the agreed delivery distance radius/range.

```json=
{
    "status_code": 200,
    "detail": {
        "distance": 3855, // in metres
        "price": 147,
        "duration": 356 // in seconds
    }
}
```

**B. Bad Request (Destination Out of Range)**
The destination is beyond the agreed delivery distance radius/range.

```json=
{
    "status_code": 400,
    "detail": {
        "distance": 37558, // in metres
        "price": 0,
        "detail": "No rates found for the given distance"
    }
}
```

**C. Bad Request (Invalid Company Type)**
If your `company_type` is not `marketplace` or `hybrid`, you will get the following response:

```json=
{
  "status_code": 400,
  "detail": "Only marketplace and hybrid clients can calculate shipping rates"
}
```

**D. Bad Request (Invalid Coordinates)**
If either of your sets of coordinates is invalid, you will get the following response:

```json=
{
  "status_code": 400,
  "detail": "Error calculating distance"
}
```





## 9. Driver Availability
This endpoint checks the availability of drivers within a certain radius of the given location.

#### Endpoint
Make a `POST` request to the following endpoint:
`<domain>/drivers/availability/`

#### Authentication
Add an `Authorization` header whose value will be your token as illustrated below:

```Authorization: Bearer <your_token_here>```

#### Request Body
Pass in a valid JSON payload as your body. See the table below for more details:

| Name                     | Data Type | Description                                             | Default | Required |
|--------------------------|-----------|---------------------------------------------------------|---------|----------|
| `origin.latitude`        | `float`   | the latitude coordinate for your pickup location        | N/A     | True     |
| `origin.longitude`       | `float`   | the longitude coordinate for your pickup location       | N/A     | True     |
| `search_radius`          | `float`   | the radius in metres within which to search for drivers | N/A     | True     |
| `destination.latitude`   | `float`   | the latitude coordinate for your drop off location      | N/A     | True     |
| `destination.longitude`  | `float`   | the longitude coordinate for your drop off location     | N/A     | True     |
| `order_preparation_time` | `integer` | the time in seconds it will take to prepare the order   | `0`     | False    |

#### Example Request Body

```json=
{
  "origin": {
    "latitude": -1.2885321068613504,
    "longitude": 36.82322101368111
  },
  "destination": {
    "latitude": -1.2692453436458566,
    "longitude":  36.80877186765047
  },
  "search_radius": 500,
  "order_preparation_time": 600
}
```

#### Sample Responses
**A. Success (Drivers Found)**

```json=
{
  "status_code": 200,
  "detail": {
    "pickup_distance": 107, // in meters
    "pickup_duration": 19, // in seconds
    "prep_time": 600, // in seconds
    "delivery_distance": 27991, // in meters
    "delivery_duration": 1842, // in seconds
    "total_duration": 2461 // in seconds
  }
}
```

**B. Failed Request**

```json=
{
  "status_code": 400,
  "detail": "No available drivers within search radius"
}
```




## 10. Order Location Tracking
This endpoint is used to get real-time location updates on an order's driver. The `order_slug` should match the slug of 
the order on Leta.

#### Endpoint
This is a websocket endpoint `wss://<domain>/ws/orders/{order_slug}`


#### Authentication
None

#### Request Body
None

#### Example Request Body
None

#### Sample Responses
**A. Success (Real-time Location Updates)**

```json=
{
            "latitude": -1.9450453,
            "longitude": 39.045854
}
```

**B. Failed (Order does NOT exist)**
You will be disconnected from the websocket if the order does not exist.
```json=
{
  "status_code": 404,
  "detail": "Order does not exist"
}
```

**C. Failed (Order is in a final state)**
You will be disconnected from the websocket if the order is in a final state.
```json=
{
  "status_code": 400,
  "detail": "Order is in a final state"
}
```


**D. Failed (Order is not assigned to a driver)
You will be disconnected from the websocket if the order is not assigned to a driver.
```json=
{
  "status_code": 400,
  "detail": "Order is not assigned to a driver"
}
```

## 11. Webhooks

### Overview
Leta facilitates real-time order updates by notifying your application/system through webhooks. This guide will help you understand the various types of webhooks that we send, when they are sent, and the structure of data sent.

### Order Status Webhook
This kind of webhook is sent when an order changes state on Leta.



#### Order Statuses
All the possible order statuses for this webhook are summarized in the table below:

| Status                   | Description                                                                                                 |
|--------------------------|-------------------------------------------------------------------------------------------------------------|
| `pending`                | The order has been created but not yet assigned to a driver.                                                |
| `assigned`               | The order has been assigned to a driver.                                                                    |
| `accepted`               | The driver has acknowledged receipt of the order. <br/> **This only applies for manually assigned orders.** |
| `arrived_at_store`       | The driver has arrived at the order's pickup location.                                                      |
| `pickup`            | The driver has picked up the order.                                                                         |
| `arrived_at_destination` | The driver has arrived at the order's drop off location.                                                    |
| `delivered`              | The order has been delivered.                                                                               |
| `cancelled`              | The order has been cancelled.                                                                               |
| `failed`              | The order has been rescheduled for another delivery attempt.                                                                               |

#### Webhook Body
See the table below for the webhook body structure.

| Field             | Data Type | Description                                                                                                                                                                                                    |
|-------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `order_id`        | `string`  | The order reference number on Leta                                                                                                                                                                             |
| `order_status`    | `string`  | The status of the order                                                                                                                                                                                        |
| `tracking_url`    | `string`  | The link to the tracking page for the order                                                                                                                                                                    |
| `timestamp`       | `string`  | The UTC date and time when the order transtioned to the specified `order_status`. <br/>It follows the format  `YYYY-MM-DD HH:MM:SS`                                                                            |
| `rider.id`        | `integer` | The driver's system ID on Leta                                                                                                                                                                                 |
| `rider.name`      | `string`  | The driver's first and second name on Leta                                                                                                                                                                     |
| `rider.phone`     | `string`  | The driver's phone number on Leta                                                                                                                                                                              |
| `rider.latitude`  | `float`   | The latitude where the driver performed the action on the order. <br/>This field is only included when the action is performed by the driver on the app and not when an order is completed from the dashboard  |
| `rider.longitude` | `float`   | The longitude where the driver performed the action on the order. <br/>This field is only included when the action is performed by the driver on the app and not when an order is completed from the dashboard |
| `delivery_otp`    | `string`  | The delivery confirmation code for the specified order.<br/>This field is only available for accounts configured to confirm deliveries using a code/OTP                                                        |
| `reason`          | `string`  | An optional reason for either a cancel or a failed status webhook. <br/> The possible values are: `client not available`, `client cancelled order`, `already delivered`, `wrong order`, `late for delivery`, `stock damaged`, `wrong location`, `wrong item`, `spoilt order`, `already delivered`, `order not in car`, `order with another car`, `receiver refused delivery`, `could not access_location`, `deliver later` |
| `event` | `string` | The event that triggered this webhook. It will always be `event.order_status` |




#### Webhook sample data
The JSON below represents the body of a callback/webhook.

```json=
{
   "order_id":"LETA-123456",
   "order_status":"delivered",
   "tracking_url":"https://tracking.leta.ai/LETA-123456",
   "timestamp":"2021-09-01 12:00:00",
   "rider":{
      "id":123,
      "name":"John Doe",
      "phone":"+254712345678",
      "latitude":-1.234567,
      "longitude":36.123456
   },
   "delivery_otp":"1234",
   "event": "event.order_status"
}
```

### Rider Location Update Webhook
This kind of webhook is sent every 20 seconds with an order's rider current location.

#### Webhook Body

See the table below for the webhook body structure

| Field             | Data Type | Description                                                                                                                                                                                                    |
|-------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `order_id`        | `string`  | The order reference number on Leta                                                                                                                                                                             |
| `order_status`    | `string`  | The status of the order                                                                                                                                                                                        |
| `created`       | `string`  | The UTC date and time when this event was generated. <br/>It follows the format  `YYYY-MM-DD HH:MM:SS`                                                                            |
| `rider.id`        | `integer` | The driver's system ID on Leta                                                                                                                                                                                 |
| `rider.name`      | `string`  | The driver's first and second name on Leta                                                                                                                                                                     |
| `rider.phone`     | `string`  | The driver's phone number on Leta                                                                                                                                                                              |
| `rider.latitude`  | `float`   | The driver's current location's latitude. |
| `rider.longitude` | `float`   | The driver's current location's longitude. |
| `event` | `string` | The event that triggered this webhook. It will always be `event.rider_update` |


#### Sample Webhook Data

```json=
{
    "order_id": "LETA-123456",
    "order_status": "arrived_at_store",
    "created": "2023-01-05 07:02:02",
    "rider": {
        "id": 123,
        "name": "John Doe",
        "phone": "+254712345678",
        "latitude": -1.234567,
        "longitude": 36.123456
    },
    "event": "event.rider_update"
}
```


**Currently, the configuration of at what order state change to send a callback/webhook is done for you on request. However, this functionality will be soon be available.**