API Documentation
With Deliveree API, developers can integrate our on-demand local delivery platform into their applications. The API is designed for developers to check prices, book an immediate or scheduled delivery and follow updates until delivery completion.
Overview
To get started with DELIVEREE API:
Step 1: Create a DELIVEREE developer account
- Please email our team and receive a Sandbox API key:
Step 2: Develop
- Review the documentation below
- Start making requests against API at
https://api.deliveree.com/public_api/
Step 3: Review our main flows
- Before testing on our Sandbox, Let’s review together our main flows, then you can use our sandbox environment to test the life cycle (Step 4) of a delivery with your integration.
| Scenarios | Flow |
|---|---|
| Successful Delivery/Booking 1 pickup and 1 destination |
locating_driver -> driver_accept_booking -> delivery_in_progress -> delivery_completed |
| Booking/Delivery Cancellation | locating_driver -> driver_accept_booking -> canceled |
| No driver found | locating_driver -> locating_driver_timeout Our Customer Service jumps in -> locating driver |
Step 4: Test on Sandbox
- In order to simulate the whole flow and verify you receive all statuses correctly, our API is implemented this way.
- Note the “Successful Delivery/Booking” and “No driver found and retry” will rotate when you test the same API.
| Scenarios | Flow |
|---|---|
| Successful Delivery/Booking | Book a delivery |
| 1 pickup and 1 destination | * locating_driver |
| (Wait 5-15 seconds) | |
| * driver_accept_booking | |
| (Wait 5-15 seconds) | |
| * delivery_in_progress | |
| (Wait 5-15 seconds) | |
| * delivery_completed | |
| Booking/Delivery Cancellation | Book a delivery |
| * locating_driver | |
| * driver_accept_booking | |
| (POST /public_api/v1/deliveries/{id}/cancel) | |
| (Post this before 5-15 seconds) | |
| * canceled | |
| No driver found | Book a delivery |
| * locating_driver | |
| (Wait 5-15 seconds) | |
| * locating_driver_timeout |
Step 5: Launch
- Once you have tested successfully with our sandbox environment, you can start requesting on the production environment.
- Send an email to our team to get your Production API key:
- We recommend you start by requesting a small set of deliveries. Once working well, you can roll out to all your users.
What the API can do for you?
You can use the DELIVEREE API to use our fleet of drivers to deliver your products within our services areas (geographic zones).
Here’s a flow that developers usually follow when using our API:
- To check if a delivery is possible, request a delivery quote. This endpoint takes at least 2 addresses (pickup and up to 10 drop-off locations) and returns a fee by vehicle type, and other information about a potential delivery.
- After you have evaluated the quoted price meets your need, you can choose a vehicle type and create a delivery.
- While it is in progress, you track the delivery status in real-time by polling API, or with webhooks.
Authentication
curl -H 'Authorization: YOUR_API_KEY' \
'https://api.deliveree.com/public_api/v1/deliveries'
- When your account manager first sets up your account, you will be provided with an API key. Please make sure to keep this key secured and never embed it in client-side code.
- You must pass the API key in the request header with the value Api-Key.
- Requests made without an API key will return a 401 Unauthorized response.
- Please email to our team with your contact information, and we’ll be in touch.
Requests
The base URL for all requests to the DELIVEREE API is:
https://api.deliveree.com/public_api/{version}
The current version of the API is v1. Backwards incompatible changes will result in a version bump.
REST
Our API is REST based. This means:
- It make use of standard HTTP verbs like GET, POST, DELETE.
- The API uses standard HTTP error responses to describe errors.
- Authentication is specified with HTTP Basic Authentication.
All requests use standard query encoding. POST data should be encoded as standard application/x-www-form-urlencoded.
Versioning
The Deliveree API is constantly being worked on to add features, make improvements, and fix bugs. This means that you should expect changes to be introduced and documented. Whenever we make a significant change to an endpoint, we will increase the version number used in the path of the resource being requested.
However, there are some changes or additions that are considered backwards-compatible and your applications should be flexible enough to handle them. These include:
- Adding new endpoints to the API
- Adding new attributes to the response of an existing endpoint
- Changing the order of attributes of responses (JSON by definition is an object of unordered key/value pairs)
Responses
The DELIVEREE API uses HTTP status codes to indicate the status of your requests. This includes successful and unsuccessful responses.
Responses will also include JSON formatted details for further details.
- 200 - OK: Request completed as expected.
- 201 - Created: Used for requests that create new objects (i.e. Delivery).
- 204 - No Content: The server has completed the request but does not need to return a body (i.e. DELETE requests).
- 304 - Not Modified: Resource hasn’t been updated since the date provided. See Caching below.
- 400 - Bad Request: You did something wrong. Often a missing argument or parameter.
- 401 - Unauthorized: Authentication was incorrect.
- 403 - Forbidden: The request is understood, but it has been refused or access is not allowed.
- 404 - Not Found: The requested resource could not be found.
- 405 - Method Not Allowed: Exceed the request limit.
- 422 - Invalid Request: The request body is parse-able however with invalid content or there are issues.
- 50X - Errors: Occur when something goes wrong in the Deliveree API.
Pagination
{
"pagination": {
"total_count": 500,
"per_page": 25,
"next_page": "https://api.deliveree.com/public_api/{version}/...",
"previous_page": "https://api.deliveree.com/public_api/{version}/..."
}
}
Requests that return multiple items will be paginated to 25 items by default. The page parameter can be used to specify further pages or offsets. Also, the per_page can be used for custom page sizes up to 100. To support pagination, we include attributes such as:
Errors
HTTP/1.1 422 Invalid Request
Content-Type: application/json
{
"error": {
"code": "string",
"message": "string"
}
}
Error responses include details about what went wrong.
Webhooks
Webhooks allow you to receive real-time updates to your ongoing deliveries. By configuring a URL we can POST updates to, you’ll get the most up-to-date information to show to your customers.
Webhook endpoint
- To use webhooks, you’ll need to configure your own web application to accept HTTP POST requests from us. These requests will contain JSON objects representing the event that has occurred.
Please contact our team to configure this URL endpoint.
We will send a JSON payload to the endpoint for every job status update, you can read more about the possible statuses.
Security
- Encryption: You may use a HTTP or a HTTPS url for webhooks. In most cases HTTP is sufficient, but HTTPS can be useful if your data is sensitive or if you wish to protect against replay attacks for example.
- Authentication: With each request we will send our webhook authentication header. Since this is the only way to identify the origin of your data, you should validate this header. In case the authentication header is incorrect, you should reply with an 401 Unauthorized.
| Headers | Description |
|---|---|
| Authorization | The unique key for a webhook which we use to authorize our requests. (This key can be generated by you) |
{
"id": 100,
"customer_id": 22,
"driver_id": 403,
"vehicle_type_id": 1,
"company_id": 33,
"time_type": "now",
"status": "delivery_in_progress",
"note": "Just a note",
"total_fees": 500,
"currency": "Rp",
"tracking_url": "https://webapp.deliveree.com/...",
"created_at": "2016-01-29T01:35:08Z",
"sent_at": "2016-01-29T01:35:09Z"
}
SDK
With Deliveree SDK, developers can integrate our on-demand local delivery platform into their applications. The SDK is designed for developers to check prices, book an immediate or scheduled delivery and follow updates until delivery completion.
| Language | Requirements | Link |
|---|---|---|
| C# | .NET 4.5+ or .NET CORE 2.1.13+ | Get Started |
| Javascript | NodeJS | Get Started |
| PHP | PHP 5.5+ | Get Started |
| Ruby | Ruby 1.9+ | Get Started |
| Python | Python 3.3+ | Get Started |
| Java | Java 8 or later, Spring Boot Framework 1.5.9 or later | Get Started |
Sandbox
The DELIVEREE API Sandbox provides development endpoints for testing the functionality of an application without making calls to the production Deliveree platform. All requests made to the Sandbox environment will be ephemeral.
Requests to the Sandbox environment should be made to:
https://api.sandbox.deliveree.com/public_api/{version}
How to get a production key?
When you’re ready to start doing live deliveries:
- Send your request to our team:
- Receive your production key.
- Use your production API key to create live deliveries.
Endpoints
Get a delivery quote
The first step in using the Deliveree API is to get a quote on a delivery. This allows you to make decisions about the appropriate cost and availability for using the Deliveree platform, which can vary based on distance and vehicle.
Get a delivery quote including POD and/or COD
POD = Proof of Delivery
COD = Cash on Delivery
Each location can include a POD and/or a COD (set need_cod / need_pod as true or false). Our API returns a total_fee based on our pricing by country. Note that if you request a COD, the cod_invoice_fees (amount that needs to be collected by the driver) is required.
Request
$ curl -X POST /public_api/v1/deliveries/get_quote \
--header "Content-Type:application/json" \
--header "Authorization:YOUR_API_KEY" \
--header "Accept-Language:en" \
--data '{
"time_type": "now",
"vehicle_type_id":21,
"packs": [
{
"dimensions": [1,2,3],
"weight": 100,
"quantity": 2
},
{
"dimensions": [2,2,5],
"weight": 20,
"quantity": 1
}
],
"locations": [
{
"address": "Jl. Sultan Iskandar Muda No.21, Arteri Pondok Indah, Pd. Pinang, Kby. Lama, Kota Jakarta Selatan, Daerah Khusus Ibukota Jakarta, Indonesia",
"latitude": -6.2608232,
"longitude": 106.7884168
},
{
"address": "Gedung Inti Sentra, Jl. Taman Kemang, RT.14/RW.1, Bangka, Mampang Prpt., Kota Jakarta Selatan, Daerah Khusus Ibukota Jakarta, Indonesia",
"latitude": -6.2608232,
"longitude": 106.7884168,
"need_cod": true,
"cod_invoice_fees": 5000,
"need_pod":true
},
{
"address": "Lavenue Apartemen, Jl. Ps. Minggu Raya, RT.7/RW.2, Pancoran, South Jakarta City, Jakarta, Indonesia",
"latitude": -6.248446679393533,
"longitude": 106.84431951392108,
"recipient_name": "Duke",
"recipient_phone": "+84903856534",
"note": "Office tower, 19th floor"
}
],
"extra_services": [
{
"extra_requirement_id": 140,
"selected_amount": 1
},
{
"extra_requirement_id": 416,
"selected_amount": 1,
"extra_requirement_pricing_id": 2146
}
]
}'
POST /public_api/v1/deliveries/get_quote
Headers
| Name | Type | Description |
|---|---|---|
| Authorization * | string | API Key |
| Accept-Language | string | User language |
Parameters
| Name | Type | Description |
|---|---|---|
| time_type * | string | There are 2 time_type : “now” and “schedule”. “now” is a delivery that needs to happen now. “schedule” is a delivery in the future (at least 2 hours from current time). |
| pickup_time | datetime (ISO Time) |
For time_type=“now”, the pickup_time can be blank as the Delivery needs to happen now. For time_type=“schedule”, the pickup_time needs a value. |
| vehicle_type_id | integer |
Optional specific Vehicle Type ID. The return quotes will only for vehicle type you provide. Use this when you know exactly what vehicle type you need. |
| packs | array |
List of Pack’s informations. Include dimensions(length, width, height), weigth, quantity. |
| locations * | array |
List of Short Location (incl. pick-up and drop-off locations). Example :
Maximum locations : - Up to 23 Locations for Indonesia - Up to 15 Locations for Thailand - Up to 15 Locations for Philippines |
| extra_services | array |
List of Extra service (incl. normal and goods insurance).
|
Short Location
A location is an object representing a location.
| Name | Type | Description |
|---|---|---|
| address * | string | Address of the location |
| latitude | float | Latitude component of the location |
| longitude | float | Longitude component of the location |
| need_cod | boolean | The location need COD or not. |
| cod_invoice_fees | float | The COD amount that needs to be collected by the driver at that location. Is required if need_cod is true. |
| need_pod | boolean | The location need POD or not. |
Note:
- We highly recommend using latitude and longitude address for location accuracy.
- POD services are available in select regions only
Pack
Pack is kind of package you want to delivery.
| Name | Type | Description |
|---|---|---|
| dimensions * | array | Array [length, width, height] of pack by Centimeter |
| weigth * | float | Weight of pack by Kilogram |
| quantity * | integer | Quantity of pack |
Responses
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"vehicle_type_id": 1,
"vehicle_type_name": "Motorcycle",
"time_type":"now",
"total_fees": 500,
"currency": "Rp",
"total_distance": 0.0,
"vehicle_type": {
"id": 21,
"name": "Double Engkel Pickup",
"cargo_length": 300.0,
"cargo_height": 200.0,
"cargo_width": 200.0,
"cargo_weight": 2000.0,
"cargo_cubic_meter": 10.0,
"minimum_pickup_time": "2021-09-24T12:36:28.538+07:00",
"quick_choices": [
{
"id": 272,
"schedule_time": 5,
"time_type": "now"
}
]
}
}
]
}
We return a list of fees for all available vehicle types.
| Name | Type | Description |
|---|---|---|
| vehicle_type_id | integer | The ID of vehicle type (use it to create a delivery) |
| vehilce_type_name | string | The name of vehicle type (ex. Motorbike, City Car, etc) |
| time_type | string | Available in 2 types: “now” and “Schedule” |
| total_fees | string | Estimated Delivery Fee for the vehicle type |
| currency | string | Currency of the amound fee (ex. Rp, Usd, etc) |
| total_distance | float | Total amount of distances, calculated in kilometres |
| vehicle_type | array | List of verhicles |
| id | integer | The ID of the vehicle |
| name | string | Name of the Vehicle |
| cargo_length | float | Cargo length of a vehicle |
| cargo_height | float | Cargo height of a vehicle |
| cargo_width | float | Cargo width of a vehicle |
| cargo_weight | float | Cargo weight of a vehicle |
| cargo_cubic_meter | float | Cargo cubic meter of a vehicle |
| minimum_pickup_time | datetime | Minimum pickup time according to the “time_type” |
| quick_choices | datetime | List of available quick choices |
Quick Choice
| Name | Type | Description |
|---|---|---|
| id | integer | Id of quick choice |
| schedule_time | datetime | Schedule time in minutes |
| time_type | string | Available in 2 types: “now” and “schedule” |
Create a delivery
Once you have all locations of a delivery you can get a delivery quote. This allows you to make decisions about the appropriate cost and availability for using Deliveree, which can vary based on distance and vehicle.
Create a delivery including POD and/or COD (Only apply for BP)
POD = Proof of Delivery
COD = Cash on Delivery
Each location can include a POD and/or a COD (set need_cod / need_pod as true or false). A note to the driver can be added for each POD or COD. If a COD is selected, the COD amount is required.
COD and POD screen selection on Customer App as illustration
As example, what does the driver see?
At delivery of Destination 2 above, the driver sees as following.
Request
$ curl -X POST /public_api/v1/deliveries \
--header "Content-Type:application/json" \
--header "Authorization:YOUR_API_KEY" \
--header "Accept-Language:en" \
--data '{
"vehicle_type_id": 1,
"note": "Fragile item that needs good care.",
"time_type": "schedule",
"pickup_time": "2016-05-13T09:51:16+07:00",
"job_order_number": "66666",
"locations": [
{
"address": "Jl. Sultan Iskandar Muda No.21, Arteri Pondok Indah, Pd. Pinang, Kby. Lama, Kota Jakarta Selatan, Daerah Khusus Ibukota Jakarta, Indonesia",
"latitude": -6.2608232,
"longitude": 106.7884168,
"recipient_name": "Duke",
"recipient_phone": "+84903398399",
"note": "Second floor, room 609"
},
{
"address": "Gedung Inti Sentra, Jl. Taman Kemang, RT.14/RW.1, Bangka, Mampang Prpt., Kota Jakarta Selatan, Daerah Khusus Ibukota Jakarta, Indonesia",
"latitude": -6.2608232,
"longitude": 106.7884168,
"recipient_name": "Nam",
"recipient_phone": "+84903856534",
"note": "First floor, right room.",
"need_cod": true,
"cod_note": "You need to get money from Nam",
"cod_invoice_fees": 5000,
"need_pod":true,
"pod_note": "You need to ..."
},
{
"address": "Lavenue Apartemen, Jl. Ps. Minggu Raya, RT.7/RW.2, Pancoran, South Jakarta City, Jakarta, Indonesia",
"latitude": -6.248446679393533,
"longitude": 106.84431951392108,
"recipient_name": "Duke",
"recipient_phone": "+84903856534",
"note": "Office tower, 19th floor"
}
],
"require_signatures": true,
"extra_services": [
{
"extra_requirement_id": 140,
"selected_amount": 1
},
{
"extra_requirement_id": 416,
"selected_amount": 1,
"extra_requirement_pricing_id": 2146
}
]
}'
$ curl -X POST /public_api/v1/deliveries \
--header "Content-Type:application/json" \
--header "Authorization:YOUR_API_KEY" \
--header "Accept-Language:en" \
--data '{
"vehicle_type_id": 1,
"note": "Fragile item that needs good care.",
"time_type": "now",
"quick_choice": true,
"quick_choice_id": 186,
"job_order_number": "66666",
"locations": [
{
"address": "Jl. Sultan Iskandar Muda No.21, Arteri Pondok Indah, Pd. Pinang, Kby. Lama, Kota Jakarta Selatan, Daerah Khusus Ibukota Jakarta, Indonesia",
"latitude": -6.2608232,
"longitude": 106.7884168,
"recipient_name": "Duke",
"recipient_phone": "+84903398399",
"note": "Second floor, room 609"
},
{
"address": "Gedung Inti Sentra, Jl. Taman Kemang, RT.14/RW.1, Bangka, Mampang Prpt., Kota Jakarta Selatan, Daerah Khusus Ibukota Jakarta, Indonesia",
"latitude": -6.2608232,
"longitude": 106.7884168,
"recipient_name": "Nam",
"recipient_phone": "+84903856534",
"note": "First floor, right room.",
"need_cod": true,
"cod_note": "You need to get money from Nam",
"cod_invoice_fees": 5000,
"need_pod":true,
"pod_note": "You need to ..."
},
{
"address": "Lavenue Apartemen, Jl. Ps. Minggu Raya, RT.7/RW.2, Pancoran, South Jakarta City, Jakarta, Indonesia",
"latitude": -6.248446679393533,
"longitude": 106.84431951392108,
"recipient_name": "Duke",
"recipient_phone": "+84903856534",
"note": "Office tower, 19th floor"
}
],
"require_signatures": true,
"extra_services": [
{
"extra_requirement_id": 140,
"selected_amount": 1
},
{
"extra_requirement_id": 416,
"selected_amount": 1,
"extra_requirement_pricing_id": 2146
}
]
}'
POST /public_api/v1/deliveries
Headers
| Name | Type | Description |
|---|---|---|
| Authorization * | string | API Key |
| Accept-Language | string | User language |
Required Parameter by User Type
BP as Non-Bp Account
| Name | Type | Description |
|---|---|---|
| booking_payment_type * | string | Set value of Booking Payment Type equal to ‘cash’ |
| customer_id * | integer | Customer Id is an id of a specific account, which BP wants to create. This account must be an employee of the company. |
| location | array | Location list must contains at least 1 location with is_payer = true |
Those services of BP account below will apply to this booking:
- Signature Setting
- Favorite Drivers
- Extra Services
- Booking Attachments
- Default Note
- Default Badges
Non-BP Account
| Name | Type | Description |
|---|---|---|
| location | array | Location list must contains at least 1 location with is_payer = true |
Parameters
| Name | Type | Description |
|---|---|---|
| vehicle_type_id * | integer | Vehicle Type ID, provided when requesting a “Delivery Quote” (ex. 1 which is Motorbike) |
| customer_id | integer | Customer ID |
| booking_payment_type | string | Booking Payment type is available in 2 types: credit and cash (apply for key from BP |
| note | string | Note of for the entire delivery. This one is different from “note per location”. (ex. Fragile Item that needs good care.) |
| time_type * | string | There are 2 time_type : “now” and “schedule”. “now” is a delivery that needs to happen now. “schedule” is a delivery in the future (at least 2 hours from current time). |
| pickup_time | datetime (ISO Time) | For time_type=“now”, the pickup_time can be blank as the Delivery needs to happen now. For time_type=“schedule”, the pickup_time needs a value. |
| job_order_number | string | Optional Job/Order number that identifies the package. Example: “Order #690” |
| allow_parking_fees | boolean | Driver may have to pay for parking. |
| allow_tolls_fees | boolean | Driver can use tolls roads. |
| allow_waiting_time_fees | boolean | Driver may have to wait 60min or more. |
| optimize_route | boolean | Re-order your destinations to achieve the fastest route. |
| send_first_to_favorite | boolean | Prioritizing booking to your favorite drivers first before everyone else |
| locations * | array |
List of Location (incl. pick-up and drop-off locations). Example :
Maximum locations : - Up to 23 Locations for Indonesia - Up to 15 Locations for Thailand - Up to 15 Locations for Philippines |
| require_signatures | boolean | Require signatures and applies to all locations |
| extra_services | array | List of Extra service (incl. normal and goods insurance). |
| quick_choice | boolean | Allow to use quick choice for time type now. It will be the pickup time for a booking |
| quick_choice_id | integer | id of quick choice |
Location
A location is an object representing a location of delivery
| Name | Type | Description |
|---|---|---|
| address * | string | Address of the location |
| latitude | float | Latitude component of the location |
| longitude | float | Longitude component of the location |
| recipient_name * | string | Name of a personal recipient at the location (our driver needs to contact person at the location, ex. Thomas Eichenberger) |
| recipient_phone * | string | Phone number of a personal recipient at the location (our driver needs to call that person when arriving) |
| is_payer | boolean | The recipient is payer or not. When API key come from Non-BP and BP as Non-BP, It requires at least 1 is_payer = true |
| note | string | Additional instructions for the driver at the location. Each location has a particular note (ex. Pickup Location: Building G2, 18th floor. Drop-off location: Ground Floor, please ring.) |
| status | string | Delivery status |
| failed_delivery_reason | string | Reason for failed delivery (If Delivery status is Failed) |
| need_cod | boolean | The location need COD or not. |
| cod_note | string | COD note. |
| cod_invoice_fees | float | The COD amount that needs to be collected by the driver at that location. Is required if need_cod is true. |
| need_pod | boolean | The location need POD or not. |
| pod_note | string | POD note. |
| position_trackings | array | List of Position Tracking |
| proof_of_delivery_photos | array | List of Proof of delivery photos and documents |
| signature_url | string | The Signature Url. |
Note:
- We highly recommend using latitude and longitude address for location accuracy.
- POD services are available in select regions only
Extra service
An extra service is an object representing an extra service of delivery
| Name | Type | Description |
|---|---|---|
| extra_requirement_id * | integer | Extra service Id |
| selected_amount | integer | Selected amount of extra service |
| extra_requirement_pricing_id | integer | Extra service pricing id of goods insurance |
| name | string | Name of extra service |
| unit_price | float | Unit price of extra service |
| display_level_price | string | Display text for level price of goods insurance pricing |
| display_fees | string | Display text for fees of goods insurance pricing |
| display_fees_without_currency | string | Display text for fees without currency of goods insurance pricing |
| position | integer | Position of extra service |
| is_insurance | boolean | The extra service has goods insurance or not. |
Responses
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": 100,
"customer_id": 22,
"driver_id": 403,
"vehicle_type_id": 1,
"company_id": 33,
"time_type": "now",
"status": "delivery_in_progress",
"note": "Just a note",
"total_fees": 500,
"currency": "Rp",
"tracking_url": "https://webapp.deliveree.com/...",
"job_order_number": "66666",
"created_at": "2016-01-29T01:35:08Z",
"eta_from_driver_to_pickup": 1800,
"distance_from_driver_to_pickup": 10.5,
"pickup_time": "2021-07-01T18:38:17+07:00",
"completed_at": null,
"driver": null,
"vehicle": {
"vehicle_attributes": {
"plate_number": null
}
},
"locations": [
{
"id": 707438,
"name": "Jl. Sultan Iskandar Muda No.21, Arteri Pondok Indah, Pd. Pinang, Kby. Lama, Kota Jakarta Selatan, Daerah Khusus Ibukota Jakarta, Indonesia",
"driver_note": null,
"note": "Second floor, room 609",
"recipient_name": "Duke",
"status": "",
"failed_delivery_reason": "",
"position_trackings": [],
"proof_of_delivery_photos": [],
"signature_url": null
},
{
"id": 707439,
"name": "Gedung Inti Sentra, Jl. Taman Kemang, RT.14/RW.1, Bangka, Mampang Prpt., Kota Jakarta Selatan, Daerah Khusus Ibukota Jakarta, Indonesia",
"driver_note": null,
"note": "First floor, right room.",
"recipient_name": "Duke",
"status": "",
"failed_delivery_reason": "",
"position_trackings": [],
"proof_of_delivery_photos": [],
"signature_url": null
},
{
"id": 707440,
"name": "Lavenue Apartemen, Jl. Ps. Minggu Raya, RT.7/RW.2, Pancoran, South Jakarta City, Jakarta, Indonesia",
"driver_note": null,
"note": "Office tower, 19th floor",
"recipient_name": "Duke",
"status": "",
"failed_delivery_reason": "",
"position_trackings": [],
"proof_of_delivery_photos": [],
"signature_url": null
}
],
"require_signatures": true,
"booking_extra_requirements": [
{
"selected_amount": 1,
"extra_requirement_id": 140,
"name": "Extra Helper",
"unit_price": 50000,
"display_level_price": null,
"display_fees": "Free",
"display_fees_without_currency": "Free",
"position": 1,
"is_insurance": false
},
{
"selected_amount": 1,
"extra_requirement_id": 416,
"name": "Goods Insurance",
"unit_price": 0.0,
"display_level_price": "Rp 1.000.000.000",
"display_fees": "Free",
"display_fees_without_currency": "Free",
"position": 1,
"is_insurance": true
}
]
}
| Name | Type | Description |
|---|---|---|
| id | integer | ID of delivery |
| customer_id | integer | ID of customer |
| driver_id | integer | ID of driver |
| vehicle_type_id | integer | ID of vehicle type |
| company_id | integer | ID of company (if the delivery is from a Business) |
| time_type | string | Time type of delivery (“now” or “schedule”) |
| status | string | Status of delivery |
| note | text | Note of entire delivery (not the note per location) |
| total_fees | float | Amount Fee |
| currency | string | Currency of Delivery (ex. Rp, Usd, etc) |
| tracking_url | string | URL to view status of delivery. That URL can be opened in a browser to follow the driver real-time and see the ETA to locations). |
| job_order_number | string | Order Number |
| created_at | datetime | Time of Creation of the delivery (ISO Time) |
| eta_from_driver_to_pickup | integer | ETA in seconds from current driver location to pickup location |
| distance_from_driver_to_pickup | float | Distance between driver and pickup location (Unit: Kilometer) |
| pickup_time | string | Timestamp when user confirm via SMS. (ISOTime) |
| completed_at | string | Timestamp when driver complete booking. (ISOTime) |
| driver | object | Driver Information. In case the booking is on process, this field will be null |
| vehicle | object | Vehicle Information, include “platenumber” as String |
| locations | array | List of Location (incl. pick-up and drop-off locations). |
Exceed request limitation
- Note: We highly recommend you to use your longitude and latitude API services. In case, if you’re using the Geo Coordinates service from Deliveree, please note it is limited. You will see an error message if it reaches the query limit.
Delivery status
| Name | Description |
|---|---|
| locating_driver | The system is searching (locating) for a driver. |
| locating_driver_timeout | After a time T, the system has not found a driver yet, therefore there is a timeout (can retry). |
| driver_accept_booking | The system has found a driver who took that delivery. |
| delivery_in_progress | The delivery has started and is in progress. |
| delivery_completed | The delivery is completed. The item has been delivered to all recipients successfully. |
| undeliverable | Error, the system cannot process this request. |
| canceled | Delivery has been canceled. |
Sandbox Note: Bookings with an odd-numbered booking ID will automatically be completed; while bookings with an even-numbered ID has to manually be completed by using the “Test My Booking” tab in the Sandbox API Dashboard.
For Example:
Booking ID 12345 will automatically be completed
Booking ID 12346 needs to be completed by the client by checking the “Test My Booking” tab in the Sandbox API Dashboard.
Get Delivery Details
You can check the delivery status at any time, but we highly recommend using webhooks if you can implement them for real-time updates.
Request
$ curl -X GET /public_api/v1/deliveries/1 \
--header "Content-Type:application/json" \
--header "Authorization:YOUR_API_KEY" \
--header "Accept-Language:en"
GET /public_api/v1/deliveries/{id}
Headers
| Name | Type | Description |
|---|---|---|
| Authorization * | string | API Key |
| Accept-Language | string | User language |
Parameters
| Name | Type | Description |
|---|---|---|
| id * | integer | ID of Delivery. |
Responses
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 100,
"customer_id": 22,
"driver_id": 403,
"driver": {
"id": 403,
"name": "Duke the driver",
"phone": "+84903398399",
"driver_image_url": "https://webapp.deliveree.com/...",
"last_known_position_lat": 10.767930,
"last_known_position_lng": 106.696440
},
"vehicle_type_id": 1,
"company_id": 33,
"time_type": "now",
"status": "delivery_in_progress",
"note": "Just a note",
"total_fees": 500,
"currency": "Rp",
"tracking_url": "https://webapp.deliveree.com/...",
"job_order_number": "66666",
"eta_from_driver_to_pickup": 60,
"distance_from_driver_to_pickup": 1.2,
"created_at": "2016-01-29T01:35:08Z",
"pickup_time": "2016-02-01T01:36:08Z",
"completed_at": null,
"vehicle": {
"vehicle_attributes": {
"plate_number": "SPIL Blue 40ft - 000.01"
}
},
"locations": [
{
"address": "Jl. Sultan Iskandar Muda No.21, Arteri Pondok Indah, Pd. Pinang, Kby. Lama, Kota Jakarta Selatan, Daerah Khusus Ibukota Jakarta, Indonesia",
"latitude": -6.2608232,
"longitude": 106.7884168,
"recipient_name": "Duke",
"recipient_phone": "+84903398399",
"note": "Second floor, room 609",
"status": "",
"failed_delivery_reason": "",
"position_trackings": [
{
"id": 1,
"latitude": -6.272444,
"longitude": 106.805534,
"tracked_at": "2016-01-29T03:35:08Z",
"tracking_type": "location_have_arrived"
},
{
"id": 2,
"latitude": -6.272444,
"longitude": 106.805534,
"tracked_at": "2016-01-29T03:55:08Z",
"tracking_type": "location_accept_delivery"
}
],
"proof_of_delivery_photos": [
{
"photo_type": "proof_of_delivery",
"photo_name": "Proof of delivery",
"image_url": "https://webapp.deliveree.com/...",
"image_content_type": "image/png"
},
{
"photo_type": "proof_of_delivery",
"photo_name": "Proof of delivery",
"image_url": "https://webapp.deliveree.com/...",
"image_content_type": "image/png"
}
],
"signature_url": "https://webapp.deliveree.com/..."
},
{
"address": "Gedung Inti Sentra, Jl. Taman Kemang, RT.14/RW.1, Bangka, Mampang Prpt., Kota Jakarta Selatan, Daerah Khusus Ibukota Jakarta, Indonesia",
"latitude": -6.2608232,
"longitude": 106.7884168,
"recipient_name": "Nam",
"recipient_phone": "+84903856534",
"note": "First floor, right room.",
"status": "Failed",
"failed_delivery_reason": "Recipient rejected",
"need_cod": true,
"cod_note": "You need to get money from Nam",
"cod_invoice_fees": 5000,
"need_pod":true,
"pod_note": "You need to ...",
"position_trackings": [
{
"id": 3,
"latitude": -1.003189,
"longitude": 101.972332,
"tracked_at": "2016-01-29T05:35:08Z",
"tracking_type": "location_have_arrived"
},
{
"id": 4,
"latitude": -1.003189,
"longitude": 101.972332,
"tracked_at": "2016-01-29T05:55:08Z",
"tracking_type": "location_accept_delivery"
}
],
"proof_of_delivery_photos": [
{
"photo_type": "proof_of_delivery",
"photo_name": "Proof of delivery",
"image_url": "https://webapp.deliveree.com/...",
"image_content_type": "image/png"
},
{
"photo_type": "proof_of_delivery",
"photo_name": "Proof of delivery",
"image_url": "https://webapp.deliveree.com/...",
"image_content_type": "image/png"
}
],
"signature_url": "https://webapp.deliveree.com/..."
},
{
"address": "Lavenue Apartemen, Jl. Ps. Minggu Raya, RT.7/RW.2, Pancoran, South Jakarta City, Jakarta, Indonesia",
"latitude": -6.248446679393533,
"longitude": 106.84431951392108,
"recipient_name": "Duke",
"recipient_phone": "+84903856534",
"note": "Office tower, 19th floor",
"status": "",
"failed_delivery_reason": "",
"position_trackings": [
{
"id": 3,
"latitude": -1.003189,
"longitude": 101.972332,
"tracked_at": "2016-01-29T05:35:08Z",
"tracking_type": "location_have_arrived"
},
{
"id": 4,
"latitude": -1.003189,
"longitude": 101.972332,
"tracked_at": "2016-01-29T05:55:08Z",
"tracking_type": "location_accept_delivery"
}
],
"proof_of_delivery_photos": [
{
"photo_type": "proof_of_delivery",
"photo_name": "Proof of delivery",
"image_url": "https://webapp.deliveree.com/...",
"image_content_type": "image/png"
},
{
"photo_type": "proof_of_delivery",
"photo_name": "Proof of delivery",
"image_url": "https://webapp.deliveree.com/...",
"image_content_type": "image/png"
}
],
"signature_url": "https://webapp.deliveree.com/..."
}
],
"require_signatures": true,
"booking_extra_requirements": [
{
"selected_amount": 1,
"extra_requirement_id": 140,
"name": "Extra Helper",
"unit_price": 50000,
"display_level_price": null,
"display_fees": "Free",
"display_fees_without_currency": "Free",
"position": 1,
"is_insurance": false
},
{
"selected_amount": 1,
"extra_requirement_id": 416,
"name": "Goods Insurance",
"unit_price": 0.0,
"display_level_price": "Rp 1.000.000.000",
"display_fees": "Free",
"display_fees_without_currency": "Free",
"position": 1,
"is_insurance": true
}
]
}
See “Create a delivery” response above.
| Name | Type | Description |
|---|---|---|
| id | integer | ID of delivery |
| customer_id | integer | ID of customer |
| driver_id | integer | ID of driver |
| driver | array |
Infomations of Driver |
| vehicle_type_id | integer | ID of vehicle type |
| company_id | integer | ID of company (if the delivery is from a Business) |
| time_type | string | Time type of delivery (“now” or “schedule”) |
| status | string | Status of delivery |
| note | text | Note of entire delivery (not the note per location |
| total_fees | float | Amount Fee |
| currency | string | Currency of Delivery (ex. Rp, Usd, etc) |
| tracking_url | string | URL to view status of delivery. That URL can be opened in a browser to follow the driver real-time and see the ETA to locations) |
| job_order_number | string | Order Number |
| eta_from_driver_to_pickup | integer | ETA in seconds from current driver location to pickup location |
| distance_from_driver_to_pickup | float | Distance between driver and pickup location (Unit: Kilometer) |
| pickup_time | string | Timestamp when user confirm via SMS. (ISOTime) |
| completed_at | string | Timestamp when driver complete booking. (ISOTime) |
| created_at | datetime | Time of Creation of the delivery (ISO Time) |
| created_at | integer | ETA in seconds from current driver location to pickup location |
| plate_number | string | Plate number of vehicle |
| locations * | array |
List of Location (incl. pick-up and drop-off locations). Example :
Maximum locations : - Up to 23 Locations for Indonesia - Up to 15 Locations for Thailand - Up to 15 Locations for Philippines |
Driver
| Name | Type | Description |
|---|---|---|
| id | integer | ID of driver |
| name | string | Name of customer |
| phone | string | Number phone of driver |
| driver_image_url | string | Link avatar of driver |
| last_known_position_lat | float | Last latitude position of driver |
| last_known_position_lng | integer | Last longitude position of driver |
Position Tracking
| Name | Type | Description |
|---|---|---|
| id | integer | ID of position tracking |
| latitude | float | Position latitude driver tracked |
| longitude | float | Position longitude driver tracked |
| tracked_at | datetime | Position driver tracked |
| tracking_type | string |
List of type driver tracked Explain :
|
Proof of delivery photos and documents
| Name | Type | Description |
|---|---|---|
| photo_type | string | Type of photo |
| photo_name | string | Name of photo |
| image_url | string | URL of photo |
| image_content_type | string | Photo content type |
Cancel a delivery
A Delivery can be cancelled without fee before it has been accepted by a driver or within the 5 first minutes if the driver has not yet picked up the package.
Request
$ curl -X POST /public_api/v1/deliveries/1/cancel \
--header "Content-Type:application/json" \
--header "Authorization:YOUR_API_KEY" \
--header "Accept-Language:en"
POST /public_api/v1/deliveries/{id}/cancel
Headers
| Name | Type | Description |
|---|---|---|
| Authorization * | string | API Key |
| Accept-Language | string | User language |
Parameters
| Name | Type | Description |
|---|---|---|
| id * | integer | ID of Delivery. |
Responses
We don’t return content for this API, please check the HTTP STATUS to know the result.
Get deliveries list
List of all deliveries of a customer.
Request
$ curl -X GET /public_api/v1/deliveries \
--header "Content-Type:application/json" \
--header "Authorization:YOUR_API_KEY" \
--header "Accept-Language:en" \
GET /public_api/v1/deliveries/
Headers
| Name | Type | Description |
|---|---|---|
| Authorization * | string | API Key |
| Accept-Language | string | User language |
Parameters
$ curl -X GET /public_api/v1/deliveries?per_page=30&page=1&to_date=12%2F12%2F2021&sort_by=customer_name&order_by=desc&search=BMW+i8&status=canceled \
--header "Content-Type:application/json" \
--header "Authorization:YOUR_API_KEY" \
--header "Accept-Language:en" \
| Name | Type | Description |
|---|---|---|
| page | integer | Define the number of pages or offsets |
| per_page | integer | Set up the number of items displayed per page. (max 100 items) |
| from_date | datetime | Bookings with pickup time less than this parameter will be filtered (format: dd/mm/yyyy) |
| to_date | datetime | Bookings with pickup time greater than this parameter will be filtered (format: dd/mm/yyyy) |
| status | string | To display booking status |
| search | string | Text seach to find customer name, vehicle type and booking id |
| sort_by | string | Sort by id, time type, vehicle type, pickup time and customer name |
| order_by | string | Order by ascending and (default) descending |
Responses
HTTP/1.1 200 OK
Content-Type: application/json
{
"pagination": {
"total_count": 500,
"per_page": 25,
"next_page": "https://api.deliveree.com/public_api/{version}/...",
"previous_page": "https://api.deliveree.com/public_api/{version}/..."
},
"data": [
{
"id": 263979,
"customer_id": 5348,
"driver_id": 403,
"vehicle_type_id": 1,
"company_id": 569,
"time_type": "now",
"status": "delivery_in_progress",
"note": "Fragile item that needs good care.",
"total_fees": 400,
"currency": "฿",
"tracking_url": "http://localhost:3000/SqCkEVNiUbfLFey97",
"job_order_number": "66666",
"eta_from_driver_to_pickup": null,
"distance_from_driver_to_pickup": null,
"created_at": "2021-07-01T18:37:16+07:00",
"pickup_time": null,
"completed_at": null,
"driver": null,
"vehicle": {
"vehicle_attributes": {
"plate_number": null
}
},
"locations": [
{
"id": 707398,
"name": "buu dien thanh pho ho chi minh",
"driver_note": null,
"note": "Second floor, room 609",
"recipient_name": "Duke",
"position_trackings": [],
"proof_of_delivery_photos": [],
"signature_url": null
},
{
"id": 707399,
"name": "buu dien thanh pho ho chi minh",
"driver_note": null,
"note": "Second floor, room 609",
"recipient_name": "Duke",
"position_trackings": [],
"proof_of_delivery_photos": [],
"signature_url": null
}
],
"require_signatures": true,
"booking_extra_requirements": [
{
"selected_amount": 1,
"extra_requirement_id": 140,
"name": "Extra Helper",
"unit_price": 50000,
"display_level_price": null,
"display_fees": "Free",
"display_fees_without_currency": "Free",
"position": 1,
"is_insurance": false
},
{
"selected_amount": 1,
"extra_requirement_id": 416,
"name": "Goods Insurance",
"unit_price": 0.0,
"display_level_price": "Rp 1.000.000.000",
"display_fees": "Free",
"display_fees_without_currency": "Free",
"position": 1,
"is_insurance": true
}
]
},
...
]
}
| Name | Type | Description |
|---|---|---|
| pagination.total_count | integer | Total number of results |
| pagination.per_page | integer | Number of result in current page |
| pagination.next_page | string | URL for the next page |
| pagination.previous_page | string | URL for the previous page |
| data | array | List of Delivery object |
Delivery
A delivery is an object representing a delivery.
| Name | Type | Description |
|---|---|---|
| id | integer | ID of delivery |
| customer_id | integer | ID of customer |
| driver_id | integer | ID of driver |
| vehicle_type_id | integer | ID of vehicle type |
| company_id | integer | ID of company (if the delivery is from a Business) |
| time_type | string | Time type of delivery (“now” or “schedule”) |
| status | string | Status of delivery |
| note | text | Note of the entire delivery (not the note per location) |
| total_fees | float | Amount Fee |
| currency | string | Currency of Delivery (ex. Rp, Usd, etc) |
| tracking_url | string | URL to view status of delivery. That URL can be opened in a browser to follow the driver real-time and see the ETA to locations. |
| job_order_number | string | Order Number |
| created_at | datetime | Time of Creation of the delivery (ISO Time) |
| eta_from_driver_to_pickup | integer | ETA in seconds from current driver location to pickup location |
| distance_from_driver_to_pickup | float | Distance between driver and pickup location (Unit: Kilometer) |
| pickup_time | string | Timestamp when user confirm via SMS. (ISOTime) |
| completed_at | string | Timestamp when driver complete booking. (ISOTime) |
| driver | object | Driver Information. In case the booking is on process, this field will be null |
| vehicle | object | Vehicle Information, include “platenumber” as String |
| locations | array | List of Location (incl. pick-up and drop-off locations). |
Get vehicle types
We return a list vehicle types of a specific area.
Request
$ curl -X GET /public_api/v1/vehicle_types \
--header "Content-Type:application/json" \
--header "Authorization:YOUR_API_KEY" \
GET /public_api/v1/vehicle_types
Headers
| Name | Type | Description |
|---|---|---|
| Authorization * | string | API Key |
Parameters
No need parameters.
Responses
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 27,
"name": "Closed Van",
"cargo_length": 200,
"cargo_height": 175,
"cargo_width": 180,
"cargo_weight": 1700,
"cargo_cubic_meter": 7,
"minimum_pickup_time_now": "2021-09-24T10:44:06.664+07:00",
"minimum_pickup_time_schedule": "2021-09-24T11:44:06.664+07:00",
"minimum_pickup_time_fullday": "2021-09-24T11:44:06.664+07:00",
"minimum_pickup_time_fpr": "2021-09-25T09:44:06.664+07:00",
"quick_choices": [
{
"id": 318,
"schedule_time": 15,
"time_type": "now"
},
{
"id": 319,
"schedule_time": 30,
"time_type": "now"
},
{
"id": 320,
"schedule_time": 45,
"time_type": "schedule"
}
]
},
{
"id": 82,
"name": "L300",
"cargo_length": 210,
"cargo_height": 125,
"cargo_width": 125,
"cargo_weight": 1000,
"cargo_cubic_meter": 3.3,
"minimum_pickup_time_schedule": "2021-09-24T10:44:06.684+07:00",
"minimum_pickup_time_fullday": "2021-09-24T10:44:06.684+07:00",
"minimum_pickup_time_fpr": "2021-09-25T09:44:06.684+07:00"
}
]
}
| Name | Type | Description |
|---|---|---|
| ID | integer | ID of vehicle type |
| name | string | Name of vehicle type |
| cargo_length | float | Cargo length of vehicle type (cm) |
| cargo_height | float | Cargo height of vehicle type (cm) |
| cargo_width | float | Cargo width of vehicle type (cm) |
| cargo_weight | float | Cargo weight of vehicle type (kg) |
| cargo_cubic_meter | float | Cargo cubic meter of vehicle type (m3) |
| minimum_pickup_time_schedule | datetime | Minimum pickup time with type schedule |
| minimum_pickup_time_fullday | datetime | Minimum pickup time with type full-day |
| minimum_pickup_time_fpr | datetime | Minimum pickup time with type fpr |
| minimum_pickup_time_fpr | datetime | Minimum pickup time with type fpr |
| quick_choices | array | List of quick choices |
Get extra services
We return a list of extra services of a specific vehicle type.
Request
$ curl -X GET /public_api/v1/vehicle_types/21/extra_services \
--header "Content-Type:application/json" \
--header "Authorization:YOUR_API_KEY" \
GET /public_api/v1/vehicle_types/{vehicle_type_id}/extra_services
Headers
| Name | Type | Description |
|---|---|---|
| Authorization * | string | API Key |
Parameters
| Name | Type | Description |
|---|---|---|
| dropoff_count | integer | How many drop-off? |
| time_type | string | Time type of delivery (“now” or “schedule”). |
Responses
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": 140,
"amount": 1,
"unit_price": 50000,
"name": "Extra Helper",
"position": 1,
"pricing_method": "normal"
},
{
"id": 416,
"amount": 0,
"unit_price": 0.0,
"name": "Goods Insurance",
"position": 2,
"pricings": [
{
"id": 2146,
"fees": 0.0,
"position": 1,
"level_price": 1000000000.0,
"display_level_price": "Rp 1 billion",
"display_fees": "Free",
"display_fees_without_currency": "Free"
}
],
"pricing_method": "by_options"
}
]
}
| Name | Type | Description |
|---|---|---|
| id | integer | Id of extra service |
| amount | integer | Amount of extra service |
| content | string | Explaination of extra service |
| unit_price | float | Unit price of extra service |
| name | string | Name of extra service |
| position | integer | Position of extra service |
| pricings | array | List of Extra Service Pricing (This is used only for goods insurance). |
| pricing_method | string | Pricing method of extra service(“normal” or “by_options”). - “by_options”: pricing method for goods insurance. - “normal”: pricing method for normal extra services. |
Extra Service Pricing
| Name | Type | Description |
|---|---|---|
| id | integer | Id of goods insurance pricing |
| fees | float | Fee of goods insurance pricing |
| position | integer | Position of goods insurance pricing |
| level_price | float | Level price of goods insurance pricing |
| display_level_price | string | Display text for level price of goods insurance pricing |
| display_fees | string | Display text for fees of goods insurance pricing |
| display_fees_without_currency | string | Display text for fees without currency of goods insurance pricing |
Get user profile
Get current user profile
Request
$ curl -X POST /public_api/v1/customers/user_profile \
--header "Content-Type:application/json" \
--header "Authorization: YOUR_API_KEY" \
--header "Accept-Language:en"
POST /public_api/v1/customers/user_profile
Headers
| Name | Type | Description |
|---|---|---|
| Authorization * | string | API Key |
| Accept-Language | string | User language |
Responses
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "Company Name",
"user_type": "bp_account",
"country_code": "ID",
"time_zone": "Bangkok",
"currency": "Rp",
"fleet_price_url": "https://www.deliveree.com/id/en/whole-vehicle-fleet-prices/",
"allow_post_payment": true
}
| Name | Type | Description |
|---|---|---|
| name | string | Name of company or customer |
| user_type | string | Check bp_account and non_bp_account |
| country_code | string | User country code |
| time_zone | string | User time zone |
| currency | string | Currency (ex. Rp, Usd, etc) |
| fleet_price_url | string | Fleet price URL |
| allow_post_payment | string | Allow post payment |