API documentation Waybills

Show waybill
Create waybill
- Attributes
- Example
Update waybill
Archive waybill
Add attachments
- Attributes
- Example
Add unit load device (ULD)
- Attributes
- Example
Update unit load device (ULD)
- Attributes
- Example
Delete unit load device (ULD)

Show waybill

Endpoint

[GET] /v4/waybills/{client_ref}

Attributes

Key	Description	Datatype	Possible values
carrier_ref	Official reference (MAWB/BoL) from carrier	String
state	Current state of waybill	String	Can be `pending` waybill has just been created `expected` waybill has a flight or noa scheduled for arrival `partially_arrived` waybill contents partially arrived at ehub `arrived` all waybill contents arrived at ehub `archived`
parcel_client_refs	Optional Array of parcel `client_ref` to link to the waybill. Parcels can not be of type `flat`
units	As written on manifest	Integer
units_arrived	Count of units present at ehub	Integer
uld_count	Number of ULDs for the waybill	Integer
unit_load_devices	Unit load devices for the waybill	Array of hashes	Only for waybill type `air` Check here for a description of unit load device attributes
vol_weight	In grams As written on manifest	Integer
arrival_type	Means by which waybill arrives to ehub	String	Can be `picked_up` `delivered` `delivered_by_ground_handler`
load_type	How the waybill is loaded	String	Can be `uld` `loose` `pallets`
type	Means by which waybill arrives to destination country	String	Can be `air` `rail` `sea` `road`
first_units_set_to_arrived_at	First timestamp on which the waybill has been set to `arrived` or `partially_arrived`	Timestamp
noas	NOA information	Array of hashes	Check here for a description of NOA attributes
flights	flight information	Array of hashes	Only for waybill type `air` Check here for a description of flight attributes
consignor	Address of the waybill's consignor	JSON	Check here for a description of consignor attributes
vessel	The vessel's name	String	Optional. Only for waybill type `sea`
container_type	Type of container used for this waybill	String	Optional. Only for waybill type `sea`
terminal_handling_party	Terminal handling party	String	Optional. Only for waybill type `sea`
pickup_reference	Pickup reference is designed for containers pickup	String

NOA attributes

Key	Description	Datatype	Possible values
state	Current state of waybill	String	Can be `pending` NOA awaiting `picking up` in progress `partially_picked_up` content partially present at ehub `picked_up` all content at ehub `archived`
picking_up_first_set_at	First timestamp on which the NOA has been set to `picking up`	Timestamp
units	Count of arriving units. Is subject to change.	Integer
initial_units	Count of arriving units as initially reported.	Integer
created_at	Timestamp of when the NOA was created	Timestamp
first_units_picked_up_at	Timestamp of when the first units were received	Timestamp
last_units_picked_up_at	Timestamp of when all the units were received	Timestamp

Flight attributes

Key	Description	Datatype	Possible values
number	flight number	Integer
arrival_scheduled_at		Timestamp
arrival_estimated_at		Timestamp
arrival_actual_at		Timestamp
departure_scheduled_at		Date
data_source		String	`client` OR `cargonaut`
departure_airport		String
port_of_arrival		String

Unit load device (ULD) attributes

Key	Description	Datatype	Possible values
ref_number	ULD reference number	String	3 letters, 4-5 numbers, 2-3 letters/numbers, no spaces. Example: PMC12345AB

Consignor and Delivery Location attributes

Key	Description	Datatype	Constraints	Errors
name1	Name	String	Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.	Name1 can't be blank Name1 is too long (maximum is 35 characters) Name1 must only contain latin or printable ASCII characters Name1 must not contain multiple lines
name2	Name (continued)	String	Optional. Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.	Name2 must only contain latin or printable ASCII characters Name2 is too long (maximum is 35 characters) Name2 must not contain multiple lines
street	Street	String	Maximum 70 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks. Must not contain zip code. Must not contain city.	Street can't be blank Street is too long (maximum is 70 characters) Street must not contain city, building, or company name Street must only contain latin or printable ASCII characters Street must not contain multiple lines
city	City	String	2-35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.	City can't be blank City is too short (minimum is 2 characters) City is too long (maximum is 35 characters) City must only contain latin or printable ASCII characters City must not contain multiple lines
country	Country	String	2 character ISO 3166-Alpha 2 country code.	Country can't be blank Country is unknown or not supported Country is invalid Country must be an ISO 3166-2 code, one of AU, GB, CN, HK, IN, LK, TR, US
zip	Zip	String	Zipcode associated with the address	ZIP can't be blank ZIP has invalid format (country-specific)
email	Email of recipient	String	Optional. Maximum 50 characters	Email can't be blank Email is not a valid email address Email is too long (maximum is 50 characters)
phone	Phone number	String	Optional. Maximum 15 characters. Must only contain characters 0-9, plus and minus.	Phone can't be blank Phone must only contain characters 0-9, plus and minus Phone is too long (maximum is 25 characters)

Create waybill

Endpoint

[POST] /v4/waybills

Attributes

Key	Description	Datatype	Constraints
type		String	Required `air`, `sea`, `rail` or `road`
carrier_ref	Official reference (MAWB/BoL) from carrier	String	Required `[A-Z-_]{5,15}` IATA-format for air waybills
client_ref	Reference of your choice	String	Required Unique `[A-Z-_]{5,30}`
units	As written on manifest	Integer	Required 1-10000
uld_count	Number of ULDs for waybill	Integer	Optional greater than or equal to 0 ⚠️ Deprecated! This field is deprecated and won't have any effect on the waybill. Please use `uld_refs` field instead.
uld_refs	Reference numbers of the ULDs for waybill	Array of hashes	Optional Array of hashes with reference numbers for this waybill. The reference numbers shall be unique for this waybill. Example: `[{ ref_number: "PMC12345AA" }, { ref_number: "PMC12345AB" }]` Reference numbers must have format: 3 letters, 4-5 numbers, 2-3 letters/numbers, no spaces. Example: `PMC12345AB`.
vol_weight	In grams As written on manifest	Integer	Required 1000-30000000 1000-10000000 for air waybills
manifest_base64	See below	String	Required
consigned_to_ehub	Waybill consignee ehub. Possible values: `AMS`, `BUD`, `LGG`	String	Required
consignor	Address of the waybill's consignor	JSON	Check here for a description of consignor attributes
flight_number	Should be two letters followed by 3 or 4 alphanumeric characters.	String	Optional, if no other flight param is submitted
load_type	Can be `uld` or `loose` or `pallets`	String	Optional.
flight_ptd	Scheduled departure date in local timezone: `YYYY-MM-DD`	String	Optional
flight_departure_airport	Departure airport IATA code	String	Required, if `flight_ptd` is submitted
processing_ehub	Key of processing EHub. Possible values: `AMS`, `BUD`, `LGG`,	String	Optional. If not provided, will be equal to `AMS`.
port_of_arrival	For waybill type `air` possible values are `AMS`, `BLL`, `BRU`, `BUD`, `CDG`, `CGN`, `FRA`, `HEL`, `HHN`, `LEJ`, `LGG`, `LUX`, `MAD`, `MST`, `MUC`, `MXP`, `OSL`, `OST`, `PRG`, `VIE`, `WAW` and `XCR` . For waybill type `sea` possible values are `ANR`, `RTM` and `ZEE` . For waybill type `rail` possible values are `CGN`, `DUI`, `HEE`, `LGG`, `MLW`, `NUS` and `TLB` .	String	Required, unless type `road`. `[a-zA-Z]{3}`
vessel	The vessel's name	String	Optional. Only for waybill type `sea`
container_type	Type of container used for this waybill	String	Optional. Only for waybill type `sea` Can be: `20ft` `40ft` `40fthc` `45fthc`
terminal_handling_party	Terminal handling party	String	Optional. For waybill type `sea` possible values are: `RTM ECT 8200` `RTM RWG 8970` `RTM EUROMAX 9830` `RTM APM 8203` `RTM APM II 8410` `ANR Becomar K614` `ANR RB PSA K869` `ANR RB HNN K913` `ANR LB PSA K1700` `ANR LB PSA K1718` `ANR LB PSA K1742` `ANR LB DP WORLD K1700` For waybill type `rail` possible values are: `DUI D3T` `DUI DIT` `DUI DECETE` `GVT` `CTS Container-Terminal GmbH` `CTH Container Terminal Herne GmbH` Must be empty for all other waybill types.
delivery_location_shortcode	Final delivery location shortcode of the waybill	String	Required. Only for waybill type `rail` , `road` and `sea.`
expected_ground_handler	Ground Handler expected to handle the waybill	String	Optional. Allowed values depend on the `consigned_to_ehub` ( Click here to see how to get a full list of available ground handlers ).
estimated_arrival_at	Date and time the waybill is expected to arrive (timezone CET). Format `YYYY-MM-DD HH:MM`	Timestamp	Optional. Only for waybill type `rail` , `road` and `sea.` Leave blank for waybill type `air`
pickup_reference	Pickup reference is designed for containers pickup	String	Optional

Manifest file

In order to include your manifest file in JSON, follow these steps:

Make sure your manifest file is in PDF format; otherwise convert it to PDF first
Make sure you manifest file is not larger than 2MB; otherwise, compress first
Base64-encode (compatible with RFC 4648) your manifest file
The result of this encoding is the value of the manifest_base64 attribute

Unit load devices

Unit load devices (field uld_refs) could be assigned only for waybills with type "air".

Example (create air waybill)

{
    "type": "air",
    "carrier_ref": "555-01772256"
    "client_ref": "HKG-180415-01"
    "units": 100,
    "vol_weight": 2196000,
    "manifest_base64": "JVBERi0xLjQKJeTjz9IKMSAwIG9iag…"
}

Example (create air waybill with consignor)

{
  "type": "air",
  "carrier_ref": "020-12345675",
  "client_ref": "CLIENT123",
  "port_of_arrival": "AMS",
  "vol_weight": 10000,
  "units": 100,
  "manifest_base64": "SSBhbSBhIFBERiBkb2N1bWVudCE=\n",
  "consigned_to_ehub": "AMS",
  "consignor": {
    "name1": "Baoguo Yunshu Youxian Gongsi",
    "street": "Tianhe Road no. 208",
    "zip": "510620",
    "city": "Guangzhou",
    "country": "CN"
  }
}

Example (create air waybill and associate parcels)

{
    "type": "air",
    "carrier_ref": "555-01772256"
    "client_ref": "HKG-180415-01"
    "units": 100,
    "vol_weight": 2196000,
    "manifest_base64": "JVBERi0xLjQKJeTjz9IKMSAwIG9iag…",
    "parcel_client_refs": [
      "CLIENT-123"
    ]
}

Update Waybill

Endpoint

[PATCH] /v4/waybills/{client_ref}

All attributes can be updated, including manifest_base64, while the waybill remains in state pending.
To update unit load devices, use a separate endpoint.

Afterwards, the following conditions apply:

vol_weight cannot be updated once the waybill is no longer in state pending
vessel cannot be updated once the waybill has arrived or is archived
terminal_handling_party cannot be updated once the waybill has arrived or is archived
container_type cannot be updated once the waybill has arrived or is archived
delivery_location_shortcode cannot be updated once the waybill has arrived or is archived
expected_ground_handler cannot be updated once the waybill has arrived or is archived
load_type cannot be updated once the waybill is no longer in state pending or expected

Archive Waybill

Endpoint

[DELETE] /v4/waybills/{client_ref}

Waybills can only be archived if no parcels are currently assigned to it.

Add attachments

Endpoint

[POST] /v4/waybills/{client_ref}/attachments

Attributes

Key	Description	Datatype	Constraints	Errors
type	The type of attachment to be uploaded.	String	Required, can be `t1` `commercial_invoice` `packing_list` `atr` `bol` for bills of lading `atb` for ATLAS AT/B manifest `container_redelivery` for Container re deliveries `freight_invoice` for Freight invoices `attachment` for generic attachments	Type can't be blank Type is not valid
filename	Name under which the document will be saved.	String	Required, `/[a-z0-9\. -_]+\.(pdf\|xls\|xlsx)/i` must include file extension, lower and upper case characters are allowed	Filename can't be blank Filename is not acceptable
attachment_base64	Base64-encoded (compatible with RFC 4648) content of the attachment.	String	See below	Attachment can't be blank Attachment size must be between 1KB and 2MB

Attachment file

In order to include your attachment file in JSON, follow these steps:

Make sure your attachment file is in PDF or Excel format; otherwise convert it to PDF first
Make sure your attachment file is not larger than 2MB; otherwise, compress first
Base64-encode (compatible with RFC 4648) your attachment file
The result of this encoding is the value of the attachment_base64 attribute
You may add multiple attachments of each type to a Waybill, but you can upload only one document per request.

Example (add attachment to waybill)

{
  "type": "packing_list",
  "filename": "111-123456789_packing_list.pdf",
  "attachment_base64": "JVBERi0xLjQKJeTjz9IKMSAwIG9iag…"
}

Add Unit load device (ULD)

A waybill could have multiple unit load devices. In order to add a unit load device to a waybill, you need to have waybill's client_ref and make POST request to the endpoint. Note: Unit load device could be added only for waybills with type "air".

Endpoint

[POST] /v4/waybills/{client_ref}/unit_load_devices

Attributes

Key	Description	Datatype	Constraints	Errors
ref_number	ULD reference number.	String	Required Format: 3 letters, 4-5 numbers, 2-3 letters/numbers, no spaces. Example `PMC12345AB`	Can't be blank, Must have format: 3 letters, 4-5 numbers, 2-3 letters/numbers, no spaces. Example: PMC12345AB

Example (add a ULD to waybill)

{
  "ref_number": "ABC12345RR"
}

Update unit load device (ULD)

In case if wrong reference number was assigned to a ULD device, this parameter could be updated with PATCH request to the endpoint.
Note: reference number could be changed only if ULD is not received in a EHUB.

Endpoint

[PATCH] /v4/waybills/{client_ref}/unit_load_devices/{ref_number}

Attributes

Key	Description	Datatype	Constraints	Errors
ref_number	New ULD reference number.	String	Required Format: 3 letters, 4-5 numbers, 2-3 letters/numbers, no spaces. Example `PMC12345AB`	Can't be blank, Must have format: 3 letters, 4-5 numbers, 2-3 letters/numbers, no spaces. Example: PMC12345AB

Example (update the ULD for waybill)

{
  "ref_number": "ABC12345RR"
}

Delete unit load device (ULD)

In case if wrong ULD was assigned to a waybill, this ULD could be removed from the waybill with DELETE request to the endpoint.

Endpoint

[DELETE] /v4/waybills/{client_ref}/unit_load_devices/{ref_number}

A ULD could be deleted only if it has not been received in a EHUB.

API documentation Waybills

Contents

Show waybill

Endpoint

Attributes

NOA attributes

Flight attributes

Unit load device (ULD) attributes

Consignor and Delivery Location attributes

Create waybill

Endpoint

Attributes

Manifest file

Unit load devices

Example (create air waybill)

Example (create air waybill with consignor)

Example (create air waybill and associate parcels)

Update Waybill

Endpoint

Archive Waybill

Endpoint

Add attachments

Endpoint

Attributes

Attachment file

Example (add attachment to waybill)

Add Unit load device (ULD)

Endpoint

Attributes

Example (add a ULD to waybill)

Update unit load device (ULD)

Endpoint

Attributes

Example (update the ULD for waybill)

Delete unit load device (ULD)

Endpoint