For AI agents: visit https://cargoai.readme.io/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI. Append .md to any documentation page URL to get its markdown version.
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
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
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.
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
{
"errorCode": 400,
"errorMessage": "invalid request: routing: 0: carrier_code: must contain English letters only.; 1: carrier_code: must contain English letters only.."
}
Enum
{
"errorCode": 400,
"errorMessage": "invalid request: awb_status: AWB Status must be \"PENDING_DELIVERY\"(confirmed)."
}
Others
{
"errorCode": 400,
"errorMessage": "invalid request: userEmail: must be a valid email address."
}
{
"errorCode": 400,
"errorMessage": "invalid request: shipper: name: must be in a valid format."
}
