API Examples

Let's assume you've generated your API key. Now we want to push an order to Kosmo.

We have a few solutions that you should choose from based on your use-case.

1. On-Demand: you push an order, and you want it to get assigned automatically, by dispatch rules, or manually by dispatchers.
2. Pre-planning: you push your order to Plan, where dispatchers can manually decide if it will be a part of a route, or they can optimize and create routes for drivers automatically.
3. Automated planning: you push all your orders at once, automatically create routes, and send them to drivers now or the next morning.

Let's see how we can support you with every use case:

On Demand

To create an on-demand order you simply need to use Create Order API.

An example of a simple request:

json

{
    "rules": {
        "keepUnassigned": true
    },
    "pickup": {
        "name": "Warehouse",
        "sender": {
            "phone": "[phone]",
            "fullname": "John Travolta"
        },
        "location": {
            "address": "143 cecil street",
            "country": "SG",
            "postalCode": "069542"
        }
    },
    "dropoffs": [
        {
            "location": {
                "lat": 1.2805737,
                "lng": 103.8504243,
                "address": "18 Raffles Quay, Singapore 048582",
                "country": "SG"
            },
            "receiver": {
                "email": "[email protected]",
                "phone": "[phone]",
                "fullname": "Customer name"
            },
            "orderReferenceId": "your-order-id"
        }
    ]
}

This will create an unassigned order in the Kosmo platform, which you will be able to see on the Track page.

Note: You can extend it with extra details, such as a package, or client pricing; for this, please, explore our API docs.

Let's focus on other assigning options. We can assign an order manually to a driver (you have to create a driver in the platform first):

JSON

"rules": {
  "driverID": "driver_123456"
}

Auto-assign or using a dispatch rule (please check our auto-assign settings in Settings > Operations > Dispatch settings):

JSON

"rules": {
  "autoassign": true
}

JSON

"rules": {
  "ruleID": "rule_abcdef"
}

📘

Then, you probably want to track the order status. We recommend to use our webhooks

Pre-planning

Pre-planning is used when you want to push orders all day, and then allow dispatchers to check your items, prepare routes, and package parcels.

You can use Create draft order API this way:

JSON

{
    "pickup": {
        "name": "Warehouse",
        "senderName": "John Travolta",
        "senderEmail": "[email protected]",
        "senderPhone": "[phone]",
        "pickupAddress": "143 cecil street",
        "pickupInstructions": "Push a red button to inform us you have arrived"
    },
    "dropoff": {
        "receiverName": "Customer Name",
        "receiverEmail": "[email protected]",
        "receiverPhone": "[phone]",
        "dropoffAddress": "18 Raffles Quay, Singapore 048582",
        "dropoffPostalCode": "048582"
    },
    "orderReferenceId": "your-order-id"
}

You can explore our API and add more details if you need, such as parcel information, schedules, stop types and other.

Automated planning

You want to use automated planning, when you have 100 stops and you want to create routes for them automatically.

First, you need to start with pushing these stops to Kosmo using Batch import stops API:

JSON

{
  "stops": [
    {
      "contact": {
        "phone": "[phone]",
        "fullname": "Customer name"
      },
      "location": {
        "lat": 1.280512,
        "lng": 103.850386,
        "address": "18 Raffles Quay, Singapore 048582",
        "country": "SG",
        "instructions": "leave at the door"
      },
      "stopType": "dropoff",
      "arrivalTimeEnd": "2024-07-13T07:00:00Z",
      "arrivalTimeStart": "2024-07-12T23:00:00Z",
      "orderReferenceId": "your-order-id-1"
    },
    {
      "contact": {
        "phone": "[phone]",
        "fullname": "Customer name 2"
      },
      "location": {
        "address": "7 Maxwell Rd, Singapore 069111",
        "country": "SG"
      },
      "stopType": "dropoff",
      "orderReferenceId": "your-order-id-2"
    }
  ]
}

Once stops are created you will get a response with the plan id (e.g: plan_abcdef).

JSON

{
  "planId": "plan_abcdef"
}

You can use this plan to optimize routes. But before you do this, we suggest you check our Route Settings. Also, you may need to create your drivers and locations first.

Then, you can use Optimize Plan API:

JSON

{
  "drivers": [
    "driver_1234", "driver_4567", "driver_9621"
  ],
  "startAt": "2024-07-12T05:00:00Z",
  "startLocation": "4e1648a8-c2c1-42ac-b86d-8abdd5233ff9"
}

It will return optimized routes with extra details, we recommend you check our API docs for this.

Lastly, optionally, you can push these orders to drivers using Confirm Plan API

If you want to manage your plans, having more actions, please let us know.