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
customsOrigin	No	string	1-2 alphanumeric characters
agent	No	Agent	N/A
otherCharges	No	[]OtherCharge	N/A

Note: customsOrigin represents the customs status of the goods under the applicable customs regime, not the country of origin.

Example values under the EU/Common Transit Convention (illustrative, not an exhaustive list - the full set of values is defined by local customs authorities): T1, T2, T2F, C, F, X.

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	N/A
volume	No	[]WeightVolumeInfo	N/A Mandatory if no ULD provided and no dimensions
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: '.', ' ')
hsc	No	[]int	length 1 to 18 digits
dims	No	[]Dimensions	N/A Mandatory if no ULD provided and no volume
uld	No	[]ULD	N/A

*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
security	No	Security	N/A

Security Object

The e-CSD security group. Emitted as the leading OCI group (<country>/ISS/RA/<agent> for a
regulated agent, <country>//<issuer>/<agent> otherwise) followed by continuation lines in
this fixed order: ED, one SM per screening method, L, SD, SN.

JSON

{
  "regulated_agent": "ESRA0123-01",
  "issuer_type": "RA",
  "expiry_date": "0626",
  "screening_methods": ["XRY"],
  "security_status": "SPX",
  "screening_datetime": "05031200",
  "screener_name": "JOHNNY WALKER",
  "exemption_code": "DIPL"
}

Field Name	Required	Data Type	Data Format
regulated_agent	Yes	string	Free form text (spe char accepted: '.', ' ', '-') - max length 35
issuer_type	No (default RA)	string	enum["RA", "KC", "AC", "RC"] - RA (regulated agent), KC (known consignor), AC (account consignor), RC (regulated carrier). Empty treated as RA
expiry_date	Conditional	string	Format MMYY. Required when issuer_type is RA/empty or KC; must be empty for AC and RC
screening_methods	Conditional	[]string	Each element is a code from the SM, or AOM-<description>. Required (≥1) when issuer_type is RA/empty and exemption_code is empty; must be empty for KC, AC, RC.
security_status	Yes	string	enum["SPX", "SCO", "NSC", "SHR"]. Emitted as an SPH code, not in the OCI line
screening_datetime	No	string	Alphanumeric - length 0 to 14 chars. Must be empty unless issuer_type is RA/empty and a screening method or exemption code is present
screener_name	No	string	Free form text - max length 35
exemption_code	No	string	enum["SMUS", "MAIL", "BIOM", "DIPL", "LFSM", "NUCL", "TRNS"]. Substitutes for screening_methods on an RA block

The block has no country field of its own - it uses oci.origin_country_code.

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
name	Yes	string	Free form text (spe char accepted: '.', ' ') - max length 35
place	Yes	string	Free form text (spe char accepted: '.', ' ') - max length 17

OtherCharge Object

Field Name	Required	Data Type	Data Format
pc_indicator	Yes	string	Exactly 1 character: "P" or "C"
charge_code	Yes	string	Exactly 2 alphabetic characters
entitlement_code	Yes	string	Exactly 1 alphabetic character
charge_amount	Yes	float	Min 0.01, max 7 digits

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 \"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.."
}