📘
Uploading multiple orders?
If the use case is to upload multiple orders at once, it's recommended to only upload one file with multiple orders in it.
JSON files are preferred.
Data is sent in the body as multipart/form-data

🚧
.Remember to use correct content-type and mimetype
Data should be sent as a JSON file with the following mimeType: application/json
Batch file required
A JSON file containing the payload (remember the correct mimetype) and Data is sent in the body as multipart/form-data

Table of Contents

1) Introduction

This API is used to batch upload one or more orders into the Dropboy platform.

Uploads a file with multiple orders. The file must be a JSON file meeting the model or an XLSX file in accordance with the template, which can be found on the page Find Transport -> Upload file in the Dropboy platform.

JSON files are preferred. The size is smaller, the handling is faster and more robust, since it does not need converting first. If the file is a JSON the mimeType MUST be application/json. Orders will be created with the uploading company(user) as creator and with the user matching the contract key in the file as the performing hauler. If the contract key is not present or does not match, the orders will be assigned to the uploading user instead.

Data is sent in the body as form-data.

Progress monitoring

You can check the progress of the orders uploading when you upload orders. When you make a request to the batch upload and it's a success (check above for the 200 OK example), you will get a batchFileId out. You can use this, to make a request to Batch upload status to check for the progress.

2. Where to find required keys

The require keys can be found in the same place where the APIkey can be found, on the page "File upload" under "Orders".

The contractKey is used in the JSON file or the Excel file, to determined which of companies you have contracts with, should received the order.

3. Property descriptions

Some properties/keys need a more thorough description, which follows here.

3.1. origin, destination, sender, receiver

Key	Description
origin (required)	Is where the goods will be picked up.
destination (required)	Is where the goods will be delivered.
sender (optional)	Is the entity that is responsible for the shipping of the goods.
receiver (optional)	Is the entity that is responsible for the receiving the goods.

3.2. timeWindow

If no timeWindow object is present, timeframe will be defined as "Whenever".
timeWindow consists of the following fields: start, end, timetype & lock.

3.3. timeType

timeType	Description
anytime	Is used to keep the timeframe as only a date - this requires `start` to be filled.
before	Is used to keep the timeframe on a date, before a given time - this requires `end` to be filled.
after	Is used to keep the timeframe on a date, after a given time - this requires `start` to be filled.
between	Is used to keep the timeframe on a date, between two given points in time - this requires both `start` and `end` to be filled.

🚧
Date time format
All the date times needs to be converted from local time, to UTC ISO-8601 format. For example:
The time in Denmark is 2022-12-24T15:30:00Z which will be 2022-12-24T14:30:00Z in UTC ISO-8601 format.

📘
Important

If the date time is not available, then remove the field from the file, as the data time content is required if the fields exist. Do NOT leave the date time fields in this section black.

3.4. lock

lock is used to highlight the timeframe within the Dropboy platform. We recommend using this for anything out of the usual or highly important, and not on all timeframes.

3.5. address, zipCode & city

Dropboy validates and fetches GeoCode data for addresses using Google Maps APIs. Therefore an address must be of a Google Maps valid format, to be properly recognised by Google Maps.

If an address is not recognised by Google Maps, Dropboy marks the address with a geoWarn flag, which informs users that there is an issue with the address. This creates extra work for the dispatchers as they need to correct the address to get reliable delivery time estimations.

In most cases this issue is due to extra address information being added in the address field, such as 'Gate 4' or '2. floor right'. To help minimise the number of geoWarns in the system we recommend that all extra address information is added to the extraInfo field whenever possible.

3.6. orderType

🚧
There are Two order types. "adhoc" and "distribution".

"adhoc" orders are direct transports from A to B. The goods are picked up at one location and delivered to another location on the same trip.

"distribution" orders are transports where the shipment either starts from a terminal and is delivered to a customer, or is picked up from a customer and delivered to a terminal.

This define what order type should be used as either adhoc or distribution

The "orderType" is often used combined with the status forpickuped as either true of false.

true= the order is in delivery status
false* = the order is in pickup status

An example:

{
  "order": {
    "orderType": "distribution",
    "pickuped": true
  }
}

The above JSON example indicate that the order is a delivery from a hub.

Field	Description
`orderType`	Order type can be "adhoc" or "distribution".
`pickuped`	can be either true or false.

3.7. coordinates

If you have your own coordinates for an address that you want to use, you can specified them in the coordinates object. This can be added to origin, destination, sender and receiver: An example:

{
  "coordinates": {
    "lat": 55.736501,
    "lng": 12.398360
  }
}

3.8. cargo

A Cargo can contain multiple field. Only a few are mandatory.

Please find a list of cargo relevant field below.

Field	Type	Description
`cargoReference`	External reference number for the goods line.	String
`cargoNr`	Cargo item number. Can be used for an item type.	String
`cargoProductId`	External product id that can be used for billing. Can be A-Z, a-z, 0-9, - (dash) or _ (underscore) and between 1 and 12 characters if it's being set	String
`cargoProductRef`	External product reference	String
`description`	Cargo content description	String
`type`	Packing types. Any `string`can be used at your convenience. One of the following types are standards that can be selected in the cargo section in the order model. `colli` `=` Colli. `pallet` `=` Pallet. `eur1_1` `=` 1/1 Euro pallet. `eur1_2` `=` 1/2 Euro pallet. `eur1_4` `=` 1/4 Euro Pallet. `box` `=` Box. `cage` `=` Cage.	String
`amount`	The quantity of the item on the item line.	Integer
`weight`	Weight of the cargo in kg	Number
`volume`	Total volume of the item in m3 (only need to be filled in if you have the volume, but not the measurements, as we calculate the volume automatically if you enter the item's dimensions in the next 3 fields).	Number
`dimentions.height`	Cargo height in cm	Number
`dimentions.width`	Cargo width in cm	Number
`dimentions.length`	Cargo length in cm	Number
`barcode`	Each item line can have one barcode. Any barcode can be added, but we only support the following in the app: UPC-A UPC-E Code 39 Code 93 Code 128 EAN-8 EAN-13 QR Data Matrix	String
`loadingMeter`	Total `loadingMeters`of the item in meters. (only need to be filled in if you have the loadingMeter, and not the measurements, as we calculate the loadingMeters automatically if you enter the item's dimensions in the above 3 fields).	Number
`service`		String

3.9. cargo.services

Array String

A piece of cargo can have from zero to multiple services. The choice of services are limited to the list below. Send each desired Service ID as a String in the services array.

Service Type	Service ID
Carry-down	588ef489ccf9b6fd26e38935
Carry-down 2-man	588ef4a2ccf9b6fd26e38936
Empty Return	66a8046c04235f1251d454c5
Return	588ef51bccf9b6fd26e38937
Return carry-down	5912e2e802bdd2626ba7ebf7
Return carry-down 2-man	5912e2f402bdd2626ba7ebf8
Curbstone Delivery	5912e2bb02bdd2626ba7ebf5
Delivery vehicleside	5912e2db02bdd2626ba7ebf6
Carry-up	588ef5b9ccf9b6fd26e38938
Carry-up 2-man	588ef5c7ccf9b6fd26e38939
Installation	588ef5e6ccf9b6fd26e3893a
Installation 2-man	588ef5f5ccf9b6fd26e3893b
Assembly	588ef605ccf9b6fd26e3893c
Disassembly	588ef612ccf9b6fd26e3893d
Adjustment	588ef6f9ccf9b6fd26e3893e
Disposal	588ef7c7ccf9b6fd26e3893f
Fragile	588ef7efccf9b6fd26e38941
Repair	588ef7fdccf9b6fd26e38942
Manual service	5954f19d259c6e114a8f1c33
Unknown service	5912f89202bdd2626ba7ebf9
+5 min service	65ca856cd8ea17b9007f2442
+10 min service	65ca8574d8ea17b9007f2443
+15 min service	65ca8579d8ea17b9007f2444

3.10. pickuped

Boolean

An order is built up as both a pickup and a delivery task. In some distribution situations the users only consider deliveries as a single task, with a collection at a hub.

This property is used to adjust where the order is in the proces. It is mainly used for orders of the type "distribution". By setting this property to true, the order is "already considered picked up", meaning that only a delivery task remains.

3.11. customFields

Object String

An order can have customFields, which is key-value. key describe the information, value is the information. An example could be:

"customFields": {
	"specialTransport": "Computers"
}

customFields can contain following:

Field	Description
String	Can contain any string.
Date	Should be in UTC ISO-8601format. Will be shown as the web clients local time on the website.
Number	Can contain a number.
Checkbox (boolean)	Is an boolean. The web client will see this as an checkbox

3.12. sendSMS & smsSettings

This will be set under origin and destination.

sendSMS is a flag needed to be set to true to be able to send SMS. smsSettings contains all the different types of SMS that can be send. The list is following:

Name	Description
driveNow	This will send a SMS when the driver is starting the trip (can be set on both `origin` and `destination`)
taskStatus	This will send a SMS when activating task status (can be set on both `origin` and `destination`)
deliverOrder	This will send a SMS when the order have been delivered successful (can be set only on `destination`)
deliverOrderFailed	This will send a SMS when the order have not been delivered successful (can be set only on `destination`)

{
  "sendSMS": true,
  "smsSettings": {
    "driveNow": true,
    "taskStatus": true,
    "deliverOrder": true,
    "deliverOrderFailed": true
  }
}

3.13. comments, commentsFiles & commentsSpecial

This will be set under origin and destination

comments is just a string value that contains text that will be visible on the order

commentsSpecial is a boolean that describes if the instructions is required to be read by the driver

commentsFiles

commentsFiles is an array that contains the list of files that the driver can/need to read while picking up or delivering an order

Key	Description
url*	The url where the file can be found. In the table below you can see the files we're supporting.
fileName	The name of the file
description	The description of the file

*Is required

Type	Extensions
Images	png, jpg, jpeg, gif
Videos	mp4, mkv
Documents	pdf, docx, txt

{
  "comments": "We're in the middle of the building",
  "commentsFiles": [
    {
      "url": "https://example.com/video.mp4",
      "fileName": "video1",
      "description": "test description"
    }
  ],
    "commentsSpecial": true
}

If there are files extension that's not in the list you want to be supported, please contact support

3.14. routingTags

Type: Array String

The routingTags array is used to store strings representing key-value pairs for routing-related information. Each entry in the array is a string. The key indicates the type of information, and the value contains the corresponding details. These tags are flexible and can be customised based on the use case.

Example:

{
  "routingTags": ["TAG1", "TAG2"]
}

routingTags can contain following:

Field	Description
String	Represents a tag as a string. This can contain any string value.

The routingTagsarray allows for multiple tags to be associated with an order. Each tag should be formatted appropriately to represent the intended routing information.

3.15. loadNumber

Type: Object String

An order can have a loadNumber, which is a value representing the numeric sequence, that the order can be sorted on a trip and a date the loadNumberValue is valid.

"loadNumber": {
    "value": "##-001",
    "date":  "2025-04-07T02:00:00.000Z"
}

loadNumberValue and loadNumberDate can contain following:

Field	Description
value	Can contain any string. Only the number part after the "-" will be used to identify the numeric increasing sequence.
date	Should be in UTC ISO-8601format. Will be shown as the web clients local time on the website. The date represent the date the loadNumberValue is valid.

4. Schema

This is a basic guide to indicate how to use the API.

JSON Schema

Version 1.0

wuxus_json_schema.json

Test your JSON with this schema

Input your JSON in the right side.\ JSON schema list

Alternate guide

wuxus_json_guide.json

5. Examples

Minimal example

wuxus_minimal_example.json

Full example

wuxus_full_example.json

Postman examples

You need to add your API key in headers sections, and select the file you want to upload.

The export is pointed to the staging environment, but it's just changing the URL to change the environment.

{
	"info": {
		"_postman_id": "9412fbec-2c4a-4e5e-9014-dc4342252f2e",
		"name": "Order batch upload",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "870486",
		"_collection_link": "https://dropboy.postman.co/workspace/b8ffb935-ab83-448c-8556-a9f445497503/collection/870486-9412fbec-2c4a-4e5e-9014-dc4342252f2e?action=share&source=collection_link&creator=870486"
	},
	"item": [
		{
			"name": "/public/orders/batch",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "APIkey",
						"value": "{{apiKey}}",
						"description": "Can be found in the platform under \"Settings-> Developer Tools\""
					},
					{
						"key": "Content-Type",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "formdata",
					"formdata": [
						{
							"key": "batch",
							"description": "This is the batch file as a .json file.",
							"type": "file",
							"src": []
						}
					]
				},
				"url": {
					"raw": "https://api-staging.wuxus.com/public/orders/batch",
					"protocol": "https",
					"host": [
						"api-staging",
						"wuxus",
						"com"
					],
					"path": [
						"public",
						"orders",
						"batch"
					]
				},
				"description": "<a href=\"https://docs.dropboy.com/reference/welcome\" >Documentation</a>"
			},
			"response": []
		}
	]
}

Postman export

200200

400400