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	Conditional (required only for FWB)	ChargesDeclaration	N/A
rates	Conditional (required only for FWB)	[]RateDetails	N/A
execution	Conditional (required only for FWB)	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
specialServiceRequest	No	[]string	Special service request (SSR) lines, one string per line

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
account_number	No	string	Account number in the airline system - max length 47. Not sent for notify, nor in FHL
email	No	string	Email address. See note below
phone	No	string	Accepted, not included in the FWB/FHL message
fax	No	string	Accepted, not included in the FWB/FHL message
eori	No	string	EORI number. Used for the consignee only: sent in the FWB OCI line with oci.origin_country_code

Note on email: the notify party is only included in the FWB when both name and email are set. In FHL messages, the shipper and consignee are only included when their email is set.

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	Conditional (mandatory if country.code is US or CA)	string	Free form text (spe char accepted: '.', ' ') - max length 9
country	Yes	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 characters airline code - Alphanumeric - 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	Conditional (mandatory if no ULD and no dims provided)	WeightVolumeInfo	N/A
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	string	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 20

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 and digits only.; 1: carrier_code: the length must be exactly 2.."
}

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