1. Overview

This API allows you to manage delivery orders and their associated order-groups. Features include creating and retrieving both order-groups and individual delivery orders.

2. Base URL

The base URL for the API is https://external.deliveritmy.com.

3. Staging Environment URL

Staging environment base URL for the API is https://external.deliverit-staging.com.

4. Authentication

Use your API token in the Authorization header like this:

Authorization: Bearer YOUR_API_TOKEN

5. Endpoints

5.1. Create Order-Groups

Creates a new order group for delivery.

POST /order-groups
Table 1. Request Body

Name

Type

Description

Required

pickUpLocation

Location

The pickup location for the order group.

Yes

pickUpContactNumber

String

Pickup task recipient contact number. Must start with “+6” and without any space and dash. E.g. +601000000001.

Yes

pickUpDateTime

String

Pick up datetime.

Yes

pickUpPersonName

String

Pickup task recipient name.

No

deliveryMethod

[DeliveryMethod]

Preferred delivery method.

No

halal

Boolean

Is the deliverable halal or not.

No

noteToDriver

String

Extra note to driver for pick up.

No
Request Example
{
  "pickUpLocation": {
    "unitNumber": "A-01",
    "address": "LG Level, Jalan Lagoon Selatan, Bandar Sunway, 47500, Selangor",
    "coordinate": {
      "longitude": 101.606772,
      "latitude": 3.0647133
    },
    "city": "Kuala Lumpur",
    "country": "Malaysia",
    "state": "Federal Territory of Kuala Lumpur"
  },
  "pickUpContactNumber": "+601000000000",
  "pickUpDateTime": "2022-01-29T01:15:00.000Z",
  "pickUpPersonName": "Pickup Tester",
  "deliveryMethod": "MOTOR",
  "halal": true,
  "noteToDriver": "Meet at lobby"
}
Table 2. Response Body

Name

Type

Description

id

String

Unique identifier for the newly created order group.

status

Order Group Status

Current status of the order group.

pickUpLocation

Location

The pickup location for the order group.

pickUpContactNumber

String

Pickup task recipient contact number. Must start with “+6” and without any space and dash. E.g. +601000000001.

pickUpDateTime

String

Pick up datetime.

pickUpPersonName

String

Pickup task recipient name.

deliveryMethod

[DeliveryMethod]

Preferred delivery method.

halal

Boolean

Is the deliverable halal?

noteToDriver

String

Extra note to driver for pick up.

paid

boolean

Order group had paid or not.

hadPickedUp

boolean

Pick up task had completed or not.

assigned

boolean

Pick up task had assigned to worker or not.

orders

listOrder

List of drop off details for this order group pick up.
Response Example
{
    "id": "6547544cbe3e2e566799660e",
    "orders": [],
    "status": "OPEN",
    "pickUpPersonName": "Pickup Tester",
    "pickUpContactNumber": "+60123456789",
    "pickUpLocation": {
        "coordinate": {
            "longitude": 101.6024829,
            "latitude": 3.0683743
        },
        "address": "Bandar Sunway, Bandar Sunway, 47500 Petaling Jaya, Selangor, Malaysia",
        "unitNumber": "A1",
        "city": "Petaling Jaya",
        "state": "Selangor",
        "postalCode": "47500",
        "country": "Malaysia"
    },
    "pickUpDateTime": "2023-11-09T08:00:00Z",
    "deliveryMethod": "MOTOR",
    "halal": false,
    "paid": false,
    "hadPickedUp": false,
    "assigned": false
}

5.2. Get Order-Groups

Retrieves details of a specific order-group.

GET /order-groups/:group_id
Table 3. Path Parameters

Name

Type

Description

Required

group_id

string

ID of the order-group to retrieve

Yes
Table 4. Response Body

Name

Type

Description

id

String

Unique identifier for the newly created order group.

status

Order Group Status

Current status of the order group.

pickUpLocation

Location

The pickup location for the order group.

pickUpContactNumber

String

Pickup task recipient contact number. Must start with “+6” and without any space and dash. E.g. +601000000001.

pickUpDateTime

String

Pick up datetime.

pickUpPersonName

String

Pickup task recipient name.

deliveryMethod

[DeliveryMethod]

Preferred delivery method.

halal

Boolean

Is the deliverable halal?

noteToDriver

String

Extra note to driver for pick up.

paid

boolean

Order group had paid or not.

hadPickedUp

boolean

Pick up task had completed or not.

assigned

boolean

Pick up task had assigned to worker or not.

orders

listOrder

List of drop off details for this order group pick up.
Response Example
{
  "id": "6547544cbe3e2e566799660e",
  "orders": [
    {
      "id": "6547571bbe3e2e566799660f",
      "ordinal": 0,
      "status": "OPEN",
      "recipientName": "Dropoff Tester1",
      "recipientPhone": "+60123456788",
      "deliverDateTime": "2023-11-09T09:15:00Z",
      "dropOffLocation": {
        "coordinate": {
          "longitude": 101.6168101,
          "latitude": 3.064785
        },
        "address": "Taylor's University Lakeside Campus, 1, Jln Taylors, 47500 Subang Jaya, Selangor, Malaysia",
        "unitNumber": "",
        "city": "Subang Jaya",
        "state": "Selangor",
        "postalCode": "47500",
        "country": "Malaysia"
      },
      "deliveryRange": 5581,
      "deliveryFee": 906,
      "doorToDoorFee": 0,
      "currency": "MYR",
      "doorToDoor": false,
      "hadDelivered": false,
      "assigned": false
    }
  ],
  "status": "OPEN",
  "pickUpPersonName": "Pickup Tester",
  "pickUpContactNumber": "+60123456789",
  "pickUpLocation": {
    "coordinate": {
      "longitude": 101.6024829,
      "latitude": 3.0683743
    },
    "address": "Bandar Sunway, Bandar Sunway, 47500 Petaling Jaya, Selangor, Malaysia",
    "unitNumber": "A1",
    "city": "Petaling Jaya",
    "state": "Selangor",
    "postalCode": "47500",
    "country": "Malaysia"
  },
  "pickUpDateTime": "2023-11-09T08:00:00Z",
  "deliveryMethod": "MOTOR",
  "halal": false,
  "paid": false,
  "hadPickedUp": false,
  "assigned": false
}

5.3. Confirm Order-Groups

Confirm an order-group. This will close the order-group and dispatch the delivery orders.

POST /order-groups/:group_id/confirm
Table 5. Path Parameters

Name

Type

Description

Required

group_id

string

ID of the order-group to retrieve

Yes
Table 6. Response Body

Name

Type

Description

id

String

Unique identifier for the newly created order group.

status

Order Group Status

Current status of the order group.

pickUpLocation

Location

The pickup location for the order group.

pickUpContactNumber

String

Pickup task recipient contact number. Must start with “+6” and without any space and dash. E.g. +601000000001.

pickUpDateTime

String

Pick up datetime.

pickUpPersonName

String

Pickup task recipient name.

deliveryMethod

[DeliveryMethod]

Preferred delivery method.

halal

Boolean

Is the deliverable halal?

noteToDriver

String

Extra note to driver for pick up.

paid

boolean

Order group had paid or not.

hadPickedUp

boolean

Pick up task had completed or not.

assigned

boolean

Pick up task had assigned to worker or not.

orders

listOrder

List of drop off details for this order group pick up.

trackingLink

string

Tracking URL for delivery process.
Response Example
{
  "id": "6547544cbe3e2e566799660e",
  "orders": [
    {
      "id": "6547571bbe3e2e566799660f",
      "ordinal": 0,
      "status": "PROCESSING",
      "recipientName": "Dropoff Tester1",
      "recipientPhone": "+60123456788",
      "deliverDateTime": "2023-11-09T09:15:00Z",
      "dropOffLocation": {
          "coordinate": {
              "longitude": 101.6168101,
              "latitude": 3.064785
          },
          "address": "Taylor's University Lakeside Campus, 1, Jln Taylors, 47500 Subang Jaya, Selangor, Malaysia",
          "unitNumber": "",
          "city": "Subang Jaya",
          "state": "Selangor",
          "postalCode": "47500",
          "country": "Malaysia"
      },
      "deliveryRange": 5581,
      "deliveryFee": 906,
      "doorToDoorFee": 0,
      "currency": "MYR",
      "doorToDoor": false,
      "invoiceDescription": "Delivery fee to Dropoff Tester1 at Taylor's University Lakeside Campus, 1, Jln Taylor (5.581 km)",
      "deliveryJobId": "ceDN56*nNHzJxpYHLF~lb0W3",
      "trackingLink": "https://onf.lt/4d8b9d0e0b",
      "hadDelivered": false,
      "assigned": false
    }
  ],
  "status": "CONFIRMED",
  "pickUpPersonName": "Pickup Tester",
  "pickUpContactNumber": "+60123456789",
  "pickUpLocation": {
    "coordinate": {
      "longitude": 101.6024829,
      "latitude": 3.0683743
    },
    "address": "Bandar Sunway, Bandar Sunway, 47500 Petaling Jaya, Selangor, Malaysia",
    "unitNumber": "A1",
    "city": "Petaling Jaya",
    "state": "Selangor",
    "postalCode": "47500",
    "country": "Malaysia"
  },
  "pickUpDateTime": "2023-11-09T08:00:00Z",
  "deliveryMethod": "MOTOR",
  "halal": false,
  "paid": false,
  "hadPickedUp": false,
  "trackingLink": "https://onf.lt/4130b192ed",
  "assigned": false
}

5.4. Cancel Order-Groups

Cancel an order-group. This will close the order-group and cancel all associated delivery orders.

POST /order-groups/:group_id/cancel
Table 7. Path Parameters

Name

Type

Description

Required

group_id

string

ID of the order-group to retrieve

Yes
Table 8. Response Body

Name

Type

Description

id

String

Unique identifier for the newly created order group.

status

Order Group Status

Current status of the order group.

pickUpLocation

Location

The pickup location for the order group.

pickUpContactNumber

String

Pickup task recipient contact number. Must start with “+6” and without any space and dash. E.g. +601000000001.

pickUpDateTime

String

Pick up datetime.

pickUpPersonName

String

Pickup task recipient name.

deliveryMethod

[DeliveryMethod]

Preferred delivery method.

halal

Boolean

Is the deliverable halal?

noteToDriver

String

Extra note to driver for pick up.

paid

boolean

Order group had paid or not.

hadPickedUp

boolean

Pick up task had completed or not.

assigned

boolean

Pick up task had assigned to worker or not.

orders

listOrder

List of drop off details for this order group pick up.

trackingLink

string

Tracking URL for delivery process.
Response Example
{
  "id": "6547544cbe3e2e566799660e",
  "orders": [
    {
      "id": "6547571bbe3e2e566799660f",
      "ordinal": 0,
      "status": "CANCELLED",
      "recipientName": "Dropoff Tester1",
      "recipientPhone": "+60123456788",
      "deliverDateTime": "2023-11-09T09:15:00Z",
      "dropOffLocation": {
        "coordinate": {
          "longitude": 101.6168101,
          "latitude": 3.064785
        },
        "address": "Taylor's University Lakeside Campus, 1, Jln Taylors, 47500 Subang Jaya, Selangor, Malaysia",
        "unitNumber": "",
        "city": "Subang Jaya",
        "state": "Selangor",
        "postalCode": "47500",
        "country": "Malaysia"
      },
      "deliveryRange": 5581,
      "deliveryFee": 906,
      "doorToDoorFee": 0,
      "currency": "MYR",
      "doorToDoor": false,
      "invoiceDescription": "Delivery fee to Dropoff Tester1 at Taylor's University Lakeside Campus, 1, Jln Taylor (5.581 km)",
      "deliveryJobId": "ceDN56*nNHzJxpYHLF~lb0W3",
      "trackingLink": "https://onf.lt/4d8b9d0e0b",
      "hadDelivered": false,
      "assigned": false
    }
  ],
  "status": "CANCELLED",
  "pickUpPersonName": "Pickup Tester",
  "pickUpContactNumber": "+60123456789",
  "pickUpLocation": {
    "coordinate": {
      "longitude": 101.6024829,
      "latitude": 3.0683743
    },
    "address": "Bandar Sunway, Bandar Sunway, 47500 Petaling Jaya, Selangor, Malaysia",
    "unitNumber": "A1",
    "city": "Petaling Jaya",
    "state": "Selangor",
    "postalCode": "47500",
    "country": "Malaysia"
  },
  "pickUpDateTime": "2023-11-09T08:00:00Z",
  "deliveryMethod": "MOTOR",
  "halal": false,
  "paid": false,
  "hadPickedUp": false,
  "trackingLink": "https://onf.lt/4130b192ed",
  "assigned": false
}

5.5. Create Orders

Creates a new delivery order within a specific order-group.

POST /order-groups/:group_id/orders
Table 9. Path Parameters

Name

Type

Description

Required

group_id

string

ID of the order-group in which the delivery order is attached to

Yes
Table 10. Request Parameters Table:

Name

Type

Description

ordinal

int

Sequence number of drop-off tasks. Start from zero.

recipientName

string

Drop-off task recipient name.

recipientPhone

string

Drop-off task recipient contact number. Must start with “+6” and without any space and dash. E.g. +601000000001.

product

string

Name of the products.

deliverDateTime

string

Drop-off task expected arrival date time.

dropOffLocation

Location

Drop-off task location.

noteToDriver

string

Extra note for driver for order.

doorToDoor

boolean

Whether deliver door to door. Extra charges will incur to order group placement.
Resquest Example
{
	"ordinal": 0,
	"recipientName": "Dropoff Tester1",
	"recipientPhone": "+60123456788",
	"deliverDateTime": "2023-11-09T09:15:00.000Z",
	"dropOffLocation": {
		"unitNumber": "",
		"address": "Taylor's University Lakeside Campus, 1, Jln Taylors, 47500 Subang Jaya, Selangor, Malaysia",
		"coordinate": {
			"latitude": 3.064785,
			"longitude": 101.6168101
		},
		"city": "Subang Jaya",
		"country": "Malaysia",
		"state": "Selangor",
		"postalCode": "47500"
	},
	"doorToDoor": false
}
Table 11. Response Body

Name

Type

Description

ordinal

int

Sequence number of drop-off tasks. Start from zero.

recipientName

string

Drop-off task recipient name.

recipientPhone

string

Drop-off task recipient contact number. Must start with “+6” and without any space and dash. E.g. +601000000001.

product

string

Name of the products.

deliverDateTime

string

Drop-off task expected arrival date time.

dropOffLocation

Location

Drop-off task location.

noteToDriver

string

Extra note for driver for order.

doorToDoor

boolean

Whether deliver door to door. Extra charges will incur to order group placement.

deliveryRange

string

Delivery distance from previous point in meter.

deliveryFee

string

Delivery fee in cent.

doorToDoorFee

int

Door to door charge amount.

hadDelivered

boolean

Drop off had delivered or not.

assigned

boolean

Drop off task had assigned to any driver or not.
Response Example
{
  "id": "6547571bbe3e2e566799660f",
  "ordinal": 0,
  "status": "OPEN",
  "recipientName": "Dropoff Tester1",
  "recipientPhone": "+60123456788",
  "deliverDateTime": "2023-11-09T09:15:00Z",
  "dropOffLocation": {
    "coordinate": {
      "longitude": 101.6168101,
      "latitude": 3.064785
    },
    "address": "Taylor's University Lakeside Campus, 1, Jln Taylors, 47500 Subang Jaya, Selangor, Malaysia",
    "unitNumber": "",
    "city": "Subang Jaya",
    "state": "Selangor",
    "postalCode": "47500",
    "country": "Malaysia"
  },
  "deliveryRange": 5581,
  "deliveryFee": 906,
  "doorToDoorFee": 0,
  "currency": "MYR",
  "doorToDoor": false,
  "hadDelivered": false,
  "assigned": false
}

5.6. Get Orders

Retrieves details of a specific delivery order within a given order-group.

GET /order-groups/:group_id/orders/:id
Table 12. Path Parameters

Name

Type

Description

Required

group_id

string

ID of the order-group in which the delivery order is attached to

Yes

id

string

ID of the specific delivery order within the order-group

Yes
Table 13. Response Fields Table

Field

Type

Description

ordinal

int

Sequence number of drop-off tasks. Start from zero.

recipientName

string

Drop-off task recipient name.

recipientPhone

string

Drop-off task recipient contact number. Must start with “+6” and without any space and dash. E.g. +601000000001.

product

string

Name of the products.

deliverDateTime

string

Drop-off task expected arrival date time.

dropOffLocation

Location

Drop-off task location.

noteToDriver

string

Extra note for driver for order.

doorToDoor

boolean

Whether deliver door to door. Extra charges will incur to order group placement.

deliveryRange

string

Delivery distance from previous point in meter.

deliveryFee

string

Delivery fee in cent.

doorToDoorFee

int

Door to door charge amount.

hadDelivered

boolean

Drop off had delivered or not.

assigned

boolean

Drop off task had assigned to any driver or not.
Response Example
{
  "id": "6547571bbe3e2e566799660f",
  "version": 0,
  "ordinal": 0,
  "status": "OPEN",
  "recipientName": "Dropoff Tester1",
  "recipientPhone": "+60123456788",
  "deliverDateTime": "2023-11-09T09:15:00Z",
  "dropOffLocation": {
    "coordinate": {
      "longitude": 101.6168101,
      "latitude": 3.064785
    },
    "address": "Taylor's University Lakeside Campus, 1, Jln Taylors, 47500 Subang Jaya, Selangor, Malaysia",
    "unitNumber": "",
    "city": "Subang Jaya",
    "state": "Selangor",
    "postalCode": "47500",
    "country": "Malaysia"
  },
  "deliveryRange": 5581,
  "deliveryFee": 906,
  "doorToDoorFee": 0,
  "currency": "MYR",
  "doorToDoor": false,
  "hadDelivered": false,
  "assigned": false
}

6. CallBack

6.1. Callback for Delivery Status Updates

The callback will be made to the callback_url provided in the POST request. The callback will include the following parameters:

Name Type Description

webhookTrigger

number

Trigger ID indicate event that triggered the webhook

orderGroupId

string

Order group object id

orderId

string

Order object id if the event is related to an order task

metadatas

list of metadata

List of order group metadata with name and value

List of webhook triggers supported:

Trigger id Trigger name Description

0

taskStarted

Task started by the driver

3

taskCompleted

Task marked as successful.

4

taskFailed

Task failed.

9

taskAssigned

Task assigned to a driver.

10

taskUnassigned

Task unassigned from a driver.
Callback Example
{
  "webhookTrigger": 9,
  "orderGroupId": "633c67cd81fb1c25d2d113da",
  "orderId": null,
  "metadatas": [
    {
      "name": "my_order_id",
      "value": "123456"
    }
  ]
}

note: If orderId is null, the event is related to the order group aka the pickup task. If orderId is not null, the event is related to the order aka drop-off task.

7. Model

7.1. Order Group Status

An order group undergoes a series of stages, each represented by a distinct status. Though the status is a string, it can only assume the following specific values:

Table 14. Status and Descriptions

Status

Description

OPEN

Initial stage with draft versions of pickup and drop-off tasks.

CONFIRMED

Pickup and drop-off tasks are finalized and forwarded to OnFleet for driver allocation.

ASSIGNED

A driver has been allocated for the pickup and drop-off tasks in the order group.

IN_TRANSIT

The driver has initiated the pickup and drop-off tasks; the orders are currently in transit.

SUCCESS

All tasks related to pickup and drop-off within the order group have been successfully completed.

PARTIAL_SUCCESS

Mixed results for the pickup and drop-off tasks within the order group; some succeeded while others failed.

FAILED

All tasks related to pickup and drop-off within the order group were unsuccessful.

CANCELLED

All tasks related to pickup and drop-off within the order group have been cancelled.

7.2. Delivery Method

The preferable method option to deliver the goods.

Table 15. Method

Method

Description

CAR

Deliver goods with transport car.

MOTOR

Deliver goods with transport motor.

7.3. Location

The Location Object contains geographical coordinates, string full address and etc.

Table 16. Location Properties

Name

Type

Description

Required In Request

coordinate.longitude

double

The longitude coordinate of the location.

Yes

coordinate.latitude

double

The latitude coordinate of the location.

Yes

address

string

The address of the location.

Yes

unitNumber

string

The unit number of the location if present.

No

city

string

The city of the address

Yes

state

string

The state of the address

Yes

postalCode

string

The postal code of the address

Yes

country

string

The country of the address

Yes

7.4. Order

The drop off detail for order under an order group.

Table 17. Order Properties

Name

Type

Description

ordinal

int

Sequence number of drop-off tasks. Start from zero.

recipientName

string

Drop-off task recipient name.

recipientPhone

string

Drop-off task recipient contact number. Must start with “+6” and without any space and dash. E.g. +601000000001.

product

string

Name of the products.

deliverDateTime

string

Drop-off task expected arrival date time.

dropOffLocation

Location

Drop-off task location.

noteToDriver

string

Extra note for driver for order.

doorToDoor

boolean

Whether deliver door to door. Extra charges will incur to order group placement.

deliveryRange

string

Delivery distance from previous point in meter.

deliveryFee

string

Delivery fee in cent.

doorToDoorFee

int

Door to door charge amount.

hadDelivered

boolean

Drop off had delivered or not.

assigned

boolean

Drop off task had assigned to any driver or not.