Data Format

This page describes the format which data needs to follow in FWB and FHL request and provides the error response structure related to data format errors

FWB/FHL request

Field Name	Required	Data Type	Data Format
awb_number	Yes	string	xxx-xxxxxxxx - length 12
userEmail	Yes	string	email format
awb_status	Yes	string	accepts "PENDING_DELIVERY" only
userCompanyName	Yes	string	Free form text (spe char accepted: '.', ' ') - max length 50
isFhlOnly	No	boolean	true/false
hawbs	Conditional (isFhlOnly - true)	[]HWBDetails	N/A
handling	No	Handling	N/A
senderReference	No	SenderReference	N/A
shipper	Yes	ShipperConsigneeInfo	N/A
consignee	Yes	ShipperConsigneeInfo	N/A
notify	No	ShipperConsigneeInfo	N/A
routingDetails	Yes	[]Routing	N/A
chargesDeclaration	No	ChargesDeclaration	N/A
rates	Conditional (required only for FWB)	[]RateDetails	N/A
execution	No	Execution	N/A
oci	No	OCI	N/A
agent	No	Agent	N/A

HWBDetails Object

Field Name	Required	Data Type	Data Format
mawbNumber	No	string	xxx-xxxxxxxx - length 12
slac	No	int	length 1 to 5 digits
hawb_number	Yes	string	AAXXXXXX - Alphanumeric - length 1 to 12 chars
number_of_pieces	Yes	int	length 1 to 4 digits
commodity	Conditional (only when charges needs to be sent with HWB)	string	Free form text (spe char accepted: '.', ' ') - max length 15
gross_weight	Yes	WeightVolumeInfo	N/A
locations	Yes	HWBLocations	N/A
currency_code	Conditional (only when charges needs to be sent with HWB)	string	3 letters currency code (ISO 4217) - Alpha - length 3
charge_code*	Conditional (only when charges needs to be sent with HWB)	string	enum["CC", "CZ", "CG", "PP", "PX", "PZ", "PG", "CP", "CX", "CM", "NC", "NT", "NZ", "NG", "NP", "NX", "CA", "CB", "CE", "CH", "PC", "PD", "PE", "PH", "PF"]
other	No	string	enum["P", "C"]
values_for_carriage	No	float	length 0.01 to 12 digits - API will replace it by NVD if \<= 0
values_for_custom	No	float	length 0.01 to 12 digits - API will replace it by NCV if <= 0
values_for_insurance	No	float	length 0.01 to 12 digits - API will replace it by XXX if <= 0

*see CargoAi FWB/FHL Charge code details here

WeightVolumeInfo Object

Field Name	Required	Data Type	Data Format
value	Yes	float	length 0.01 to 9 digits
uom	Yes	string	enum["K", "L", "MC", "CF"] - K, L for weight | MC, CF for volume

HWBLocations Object

Field Name	Required	Data Type	Data Format
port_of_origin	Yes	Code	N/A
port_of_destination	Yes	Code	N/A

Handling Object

Field Name	Required	Data Type	Data Format
specialServiceInformation	No	string	Free form text (spe char accepted: '.', ' ') - max length 65
otherServiceInformation	No	string	Free form text (spe char accepted: '.', ' ') - max length 65
specialHandling	No	[]Code	N/A

Code Object

Field Name	Required	Data Type	Data Format
code	Yes	string	IATA standards 3 letters code - Alpha - length 3

SenderReference Object

Field Name	Required	Data Type	Data Format
senderAirport	No	string	IATA standards 3 letters code - Alpha - length 3
senderOfficeDesignator	No	string	enum["FF", "FR", "FM"] FF - Freight/Cargo Handling FR - Freight/Cargo Reservations FM - Freight/Cargo Systems

ShipperConsigneeInfo Object

Field Name	Required	Data Type	Data Format
name	Yes	string	Free form text (spe char accepted: '.', ' ') - max length 35
address	Yes	Address	N/A

Address Object

Field Name	Required	Data Type	Data Format
line1	Yes	string	Free form text (spe char accepted: '.', ' ') - max length 35
line2	No	string	Free form text (spe char accepted: '.', ' ') - max length 35
place	Conditional (mandatory if city.Code not provided)	string	Free form text (spe char accepted: '.', ' ') - max length 17
city	Conditional. (city.Code mandatory if place not provided)	AddressLocation	N/A
postal_code	No	string	Free form text (spe char accepted: '.', ' ') - max length 9
state_province	No	string	Free form text (spe char accepted: '.', ' ') - max length 9
country	No	AddressLocation	N/A

AddressLocation Object

Field Name	Required	Data Type	Data Format
code	Yes	string	IATA standards 3 letters code - Alpha - length 3 (City) | 2 letters code - Alpha - length 2 - ISO 3166-1 (Country)
name	No	string	Free form text (spe char accepted: '.', ' ') - max length 17

Routing Object

Field Name	Required	Data Type	Data Format
from_airport_code	Yes	string	IATA standards 3 letters code - Alpha - length 3
to_airport_code	Yes	string	IATA standards 3 letters code - Alpha - length 3
carrier_code	Yes	string	IATA standards 2 letters code - Alpha - length 2
flight_number	No	string	Alphanumeric - length 3 to 4 chars

ChargesDeclaration Object

Field Name	Required	Data Type	Data Format
currency_code	Yes	string	3 letters currency code (ISO 4217) - Alpha - length 3
charge_code*	Yes	string	enum["CC", "CZ", "CG", "PP", "PX", "PZ", "PG", "CP", "CX", "CM", "NC", "NT", "NZ", "NG", "NP", "NX", "CA", "CB", "CE", "CH", "PC", "PD", "PE", "PH", "PF"]
weight_or_valuation	No	string	enum["P", "C"] - P prepaid, C collect
values_for_carriage	No	float	length 0.01 to 12 digits - API will replace it by NVD if \<= 0
values_for_custom	No	float	length 0.01 to 12 digits - API will replace it by NCV if <= 0
values_for_insurance	No	float	length 0.01 to 12 digits - API will replace it by XXX if <= 0

RateDetails Object

Field Name	Required	Data Type	Data Format
number_of_pieces	Yes	int	length 1 to 4 digits
gross_weight	Yes	[]WeightVolumeInfo	enum["CC", "CZ", "CG", "PP", "PX", "PZ", "PG", "CP", "CX", "CM", "NC", "NT", "NZ", "NG", "NP", "NX", "CA", "CB", "CE", "CH", "PC", "PD", "PE", "PH", "PF"]
volume	No	[]WeightVolumeInfo	enum["P", "C"] - P prepaid, C collect
slac	No	int	length 1 to 5 digits
rate_class_code*	Yes	string	enum["B", "R", "S", "P", "M", "N", "Q", "K", "C", "X", "E", "U", "Y"]
commodity_item_number	No	string	length 4 to 7 digits
chargeable_weight**	No	float	length 0.01 to 7 digits
rate_or_charge	No	float	length 0.01 to 8 digits
charge_amount	No	float	length 0.01 to 12 digits
nature_and_quantity_of_goods	No	string	Free form text (spe char accepted: '.', ' ') - max length 20
hsc	No	[]int	length 1 to 18 digits
dims	No	[]Dimensions
uld	No	[]ULD

*see CargoAi FWB/FHL Rate Class code details here

**Please, see details about chargeable weight here

Dimensions Object

Field Name	Required	Data Type	Data Format
pcs	Yes	int	length 1 to 4 digits
length	Yes	int	length 1 to 5 digits
width	Yes	int	length 1 to 5 digits
height	Yes	int	length 1 to 5 digits
uom	Yes	string	enum["CMT", "INH"]
weight	No	float	length 0.01 to 7 digits
volume	No	float	length 0.01 to 7 digits

ULD Object

Field Name	Required	Data Type	Data Format
number	Yes	int	length 1 to 10 chars - Alpha numeric

Execution Object

Field Name	Required	Data Type	Data Format
date	Yes	string	format 02-Jan-06
place	Yes	string	Free form text (spe char accepted: '.', ' ') - max length 17
shipper_signature	Yes	string	Free form text (spe char accepted: '.', ' ') - max length 20
carrier_signature	Yes	string	Free form text (spe char accepted: '.', ' ') - max length

OCI Object

Field Name	Required	Data Type	Data Format
origin_country_code	Yes	string	2 letters code - Alpha - length 2 - ISO 3166-1

Agent Object

Field Name	Required	Data Type	Data Format
accountNumber	No	string	Free form text (spe char accepted: '.', ' ') - max length 14
iata	Yes	string	length 7 digit
cass	No	string	length 4 digit
place	No	string	Free form text (spe char accepted: '.', ' ') - max length 17

Error Examples

All errors related to data format will follow structure shown in below examples:

Arrays

json

{
    "errorCode": 400,
    "errorMessage": "invalid request: routing: 0: carrier_code: must contain English letters only.; 1: carrier_code: must contain English letters only.."
}

Enum

JSON

{
    "errorCode": 400,
    "errorMessage": "invalid request: awb_status: AWB Status must be either \"PENDING_AIRLINE_INFORMATION\" (requested), or \"PENDING_DELIVERY\"(confirmed)."
}

Others

JSON

{
    "errorCode": 400,
    "errorMessage": "invalid request: userEmail: must be a valid email address."
}

JSON

{
    "errorCode": 400,
    "errorMessage": "invalid request: shipper: name: must be in a valid format."
}

JSON

{
    "errorCode": 400,
    "errorMessage": "invalid request: shipper: city.code: cannot be blank."
}

JSON

{
    "errorCode": 400,
    "errorMessage": "invalid request: rates: 0: number_of_pieces: must be no greater than 9999.."
}