The data is in CSV format (commas between fields, double quotes around any field which contains a comma, a double quote inside a field is doubled.) Empty values (a.k.a. blank or null) are represented as two adjacent field separators, or as a field separator followed by end of line (or at the beginning of a line, but that can't happen with this format).
Most customers won't have data for all of the fields in the format. You should leave the fields you're not using empty.
The character encoding has to be either ASCII or ISO 8859-1 (Latin-1).
The first field of every record specifies what type of record it is (mawb,
hawb, package, etc.). The second field is an integer which specifies
the record type's version. This is used to retain backward compatibility when
a change is made to the record format.
Record type email is used for reporting back to you the results
of processing your data. You can specify different addresses for errors and
for success reports. Currently this is only supported for Air-AMS customers.
email records are global in nature and must appear at the start
of the file, before any other type of records.
For Air-AMS customers at least one email recipient for errors is required.
If you want to have messages sent to more than one email address, simply put
more than one email record of the appropriate type in the file.
| Field Name | Type | Required? | Additional Information |
|---|---|---|---|
| record_type | char(255) | always | always email
|
| record_version | integer | always | always 1 |
| address_type | char(255) | always | error, success, or all
|
| email_address | char(255) | always | a single email address
Rudimentary checking is performed on the email address
supplied. Of course it should be a valid address, but it at
least has to match |
A record of type mawb holds manifest information. This data
applies to all following shipment records until either the end of the file or
another mawb record. There will normally be a mawb
record near the top of the file, directly after any records which apply to the
whole file.
For Air-AMS the mawb record is required, and all the fields
must be supplied.
For non-Air-AMS you aren't required to have a mawb record. If
you don't use one we won't be able to print out manifests of this data, but it
will still be used for the shipment in our database.
| Field Name | Type | Required? | Additional Information |
|---|---|---|---|
| record_type | char(255) | always | always mawb
|
| record_version | integer | always | always 1 |
| manifest_code | char(15) | never |
If desired you can use this field to uniquely identify this manifest (e.g. if you sent several parts for the same MAWB). |
| manifest_date | char(8) | required for Air-AMS | format YYYYMMDD
The date that the flight LEAVES the origin country. For Air-AMS it can't be older than 7 days ago or newer than 4 days from now. |
| manifest_origin | char(3) | required for Air-AMS |
The three letter IATA airport code (all upper case) for the origin of the final leg of the flight. |
| manifest_destination | char(3) | required for Air-AMS |
The three letter IATA airport code (all upper case) for the final destination of the flight. If you ship to IBC within the United States this would be JFK, LAX, MIA, or ORD. |
| flight | char(20) | required for Air-AMS |
The airline and flight number (such as AA1234 or BA179). |
| mawb | char(11) | required for Air-AMS |
This field contains the consolidation's Master Air Waybill number (11 digits). For Air-AMS customers it is required and it must match the MAWB filed by the airline; if this is not the case US Customs will NOT release your material. Furthermore airline MAWBs have a mod-7 check digit, and we will reject files where the check-digit is invalid. |
Record type hawb is the shipment record. For each shipment on
the manifest you include a single hawb record. A multi-piece
shipment which is going to be cleared as such with US Customs must have a
single hawb record, and that record must record the number of
physical packages in the num_pieces field.
| Field Name | Type | Required? | Additional Information | Programmer's Notes | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| record_type | char(255) | always | always hawb
| 13 | |||||||||
| record_version | integer | always | always 13
| 2 | |||||||||
| profile_key | integer | never | usually empty | 2 | |||||||||
| hawb | char(40) | always | your full HAWB (including letters)
Important: We will reference the shipment internally using the last 11 digits in your HAWB, ignoring any letters or other characters. Data sent back to you will use your full HAWB. US CBP requires that the HAWB be unique among all the shipments on the same MAWB. Because of the conversion we do on your full HAWB this means that the last 11 digits of your HAWB have to be unique among shipments on the current MAWB. For example:
This would be an error. Even though the 2 full HAWBs are different they are the same when converted to the values which are sent to US CBP. | 2 | |||||||||
| ship_ref_num | char(11) | never | your customer's reference number | 2 | |||||||||
| internal_reference | char(40) | never | usually empty | 3 | |||||||||
| vend_ref_num | char(22) | never | if you are applying the delivery agent's labels you must include the tracking number here | 2 | |||||||||
| origin | char(3) | required for Air-AMS | the three letter IATA code of the origin | 2 | |||||||||
| final_destination | char(3) | required for Air-AMS | the three letter IATA code of the destination or a major
airport in its country
Though it isn't an IATA code this field is allowed to be
| 2 | |||||||||
| outlying | char(1) | never | X for outlying, empty otherwise | 2 | |||||||||
| service_provider | char(3) | never | leave empty unless told otherwise by IBC | 10 | |||||||||
| dls_station | char(3) | never | leave empty | 2 | |||||||||
| dls_final_destination | char(3) | never | leave empty | 2 | |||||||||
| num_pieces | decimal(3,0) | required for Air-AMS | the number of physical pieces (boxes, tubes, envelopes, etc.) associated with this HAWB (for multi-piece shipping) | 2 | |||||||||
| weight | decimal(7,2) | required for Air-AMS | raw weight, not rounded; must be positive if present
In pounds unless a type 4 or greater record, in which case the units are specified in the next field. | 2 | |||||||||
| weight_units | char(2) | required if weight is not empty | lb = pounds, kg = kilos, g = grams | 4 | |||||||||
| contents | char(3) | required for Air-AMS | DOC (documents) or APX (dutiable) | 2 | |||||||||
| currency_code | char(3) | never | type of currency used by monetary fields such as declared_value
It's preferred that you send monetary values to us already converted into US dollars in which case this field can be left empty. If you use a 3-letter ISO currency code here we will attempt to do the conversion for you. | 11 | |||||||||
| declared_value | decimal(7,0) | required for Air-AMS APX shipments | in US dollars or the given currency_code; must be empty or 0 for DOC shipments | 2 | |||||||||
| insurance_amount | decimal(9,2) | never | in US dollars or the given currency_code; must be empty unless you buy insurance from IBC (retail only) | 3 | |||||||||
| description | char(200) | required for Air-AAMS APX shipments | description of the goods (if APX) in English; required for AAMS APX | 2 | |||||||||
| hts_code | char(10) | required for CFS entry type 86 filing | the HTS (Harmonized Tariff System) code, a.k.a. harmonized code,
which pertains to the contents of the shipment
Must be a full 10 digit code if provided. Consult with our brokerage department to determine if this is required for your shipments. | 9 | |||||||||
| fda_prior_notice | char(12) | never | the FDA Prior Notice number; must be exactly 12 digits if present
Consult with our brokerage department to find out if this is required for your shipments. | 8 | |||||||||
| terms | char(1) | never | leave empty unless told otherwise by IBC, when it is supplied the valid values are Prepaid, Specials, and Free Domicile (DDP)
| 2 | |||||||||
| packaging | char(1) | required for Air-AMS | Use the following codes: L=Letter, P=IBC Pak, B=Box, T=Tube, C=Crate, M=Metal Film Can, O=Other | 3 | |||||||||
| service_type | char(2) | never | use ST for standard courier shipments (which is the default if the field is left empty), GD for ground service | 3 | |||||||||
| collect_amount | decimal(7,2) | required for Air-AMS shipments with terms = C
| in US dollars or the given currency_code; use only when terms is C; cannot be negative
| 2 | |||||||||
| cust_key | integer | never | leave empty unless told otherwise by IBC | 2 | |||||||||
| acct_num | char(4) | never | your account number with IBC, or empty | 2 | |||||||||
| dls_acct_num | char(12) | never | leave empty unless told otherwise by IBC | 2 | |||||||||
| ext_cust_acct | char(11) | never | leave empty unless told otherwise by IBC | 3 | |||||||||
| shipper_name | char(30) | required for Air-AMS |
Use the "true" shipper's information for these fields. If you are a wholesale account this would be your customer's information. | 2 | |||||||||
| shipper_address1 | char(25) | required for Air-AMS | 2 | ||||||||||
| shipper_address2 | char(25) | never | 2 | ||||||||||
| shipper_city | char(25) | required for Air-AMS | 2 | ||||||||||
| shipper_state | char(2) | never | 2 | ||||||||||
| shipper_zip | char(10) | never | 2 | ||||||||||
| shipper_country | char(15) | required for Air-AMS | country code or country name
For Air-AMS this must be the two letter ISO country code. | 2 | |||||||||
| shipper_phone | char(15) | never | 2 | ||||||||||
| consignee_person | char(35) |
Air-AMS shipments require at least one of the consignee_person and consignee_company be supplied | recipient's name / department | 2 | |||||||||
| consignee_company | char(35) | company name | 2 | ||||||||||
| consignee_street_1 | char(35) | required for Air-AMS | street address, line 1 | 2 | |||||||||
| consignee_street_2 | char(35) | never | street address, line 2 | 2 | |||||||||
| consignee_city | char(35) | required for Air-AMS | non-abbreviated city name | 2 | |||||||||
| consignee_state | char(20) | required for Air-AMS shipments to US and CA | abbreviated state/province code
e.g. | 2 | |||||||||
| consignee_postal_code | char(20) | required for Air-AMS shipments to US and CA | postal/zip code | 5 | |||||||||
| consignee_country | char(2) | required for Air-AMS | ISO country code | 8 | |||||||||
| consignee_phone | char(20) | never | phone number, including country code | 2 | |||||||||
| consignee_email | char(255) | never | recipient's email address | 12 | |||||||||
| consignee_tax_id | char(40) | never | recipient's country-specific tax identifier | 12 | |||||||||
| comment | char(512) | never | optional free-form text | 8 | |||||||||
| goods_country_of_origin | char(2) | never |
Origin country of included goods for customs' purpose. Normally you'd only set this if there were just one type of good in the shipment. | 13 | |||||||||
| incoming_container | char(255) | never |
identifier of the container/gaylord/etc. containing this shipment | 13 | |||||||||
When you send a live file you will receive via email either an error message or a positive acknowledgment that the data was accepted. If you receive no acknowledgment something went seriously wrong; you should contact IBC. You will normally receive a response within 20 minutes of your transmission.
If you receive a positive response that manifest is "locked" — you cannot update it. If you were to resend that data you would get an error message for each shipment saying it was a duplicate. If you need to make a change to data already submitted and accepted you will need to send an email message to aams-ZZZ-alert@ibcinc.com where ZZZ is either JFK, LAX, MIA, or ORD (whichever IBC office is handling the manifest) and then a human in that office will update the data.
If you receive an error message it indicates that the entire manifest was rejected, as any error will cause the entire file to be rejected. If that occurs you must correct the errors and resend the file in its entirety. Until a positive response is received no data is available to US Customs.
You may receive warning messages about non-critical errors along with the "good data" acknowledgments. Those warnings are designed to give you time to identify sources of invalid data; we anticipate needing to enforce stricter data validation in the future. The warnings will start with the word "NOTICE" to differentiate them from errors. You will still see the line
Successfully loaded Air AMS data
in the success email if there were no real errors, just warnings.
As requirements change we add fields and/or change data validation. The semantics for a record version don't change, instead there is a new record version assigned to the updated format. The Programmer's Notes column indicates in which version of the record a field appeared for the first time.
The record_type field was added with hawb version
13. For backwards compatibility it isn't required on versions 13 and earlier.
The same applies to version 1 mawb (previously record type 1)
and email (previously types 6 and 7) records.
Fullman spec $Revision$