The Fullman Format

Introduction

This page is only designed for those customers which have been instructed to review this file format. It is not meant to be a complete guide to sending manifest data to Pactrak®, but rather a guide to the file format only.

Fullman files are sent to us via email, via a web form, or via a web service. The data can be sent at any time. If you are an Air-AMS customer, the timing needs to follow the US Customs regulations for Air-AMS.

Testing

The web form and web service have built-in testing facilities.

If you'll be submitting your data via email you can still use the manifest submit web form for testing during your development. Once you've successfully tested your data with the form, please send an email message containing a sample data file to it-request@ibcinc.com. We'll process the data by hand and respond with the results. The email you send should be sent just as if you were sending a live message, see Emailing Data to IBC.

Going Live

Once you've successfully tested a sample, we will provide you with a customer-specific email address to which all future live data should be sent for automated processing (or which should be used with the web form or service, where it's referred to as the report address). Please note that your submission address will be in the pactrak.com domain, not the ibcinc.com domain.

The File Format

The data is in CSV format (commas between fields, double quotes around any field which contains a comma, a double quote inside a string is doubled.) Null values 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). A null value is distinct from "", the empty string, but for practical purposes there isn't often a difference.

Even though the data is in CSV format, you can't simply type your data into Excel and save it as a CSV file and then send it to us. If you do this Excel will append extra commas so that each line of data has the same number of fields. This won't work because the lines aren't supposed to have the same number of fields.

Most customers won't have data for all of the fields in the format. You should use null values for the fields you're not using.

The character encoding has to be either ASCII or ISO 8859-1 (Latin-1).

The first field of every record is an integer which specifies what type of record it is. The rest of the fields are interpreted based on this record type.

Notification Records

Record types 6 and 7 are used for reporting back to you the results of processing your data. Currently, this is only supported for Air-AMS customers.

These records are global in nature, and must appear at the start of the file, before any other types of records.

For Air-AMS customers at least one record of type 6 is required.

If you want to have messages sent to more than one email address, simply put more than one record type 6 and/or record type 7 in the file

Field Name Type Required? Additional Information
record_type integer always

6 for the address to which we send errors, 7 for the address to which we send success messages

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 "*@*.*" and not have more than one "@" in it.

Manifest Records

A record with a type of 1 holds manifest information. This data applies to all following detail records until either the end of the file or another type 1 record. Normally a type 1 record would occur immediately after the type 6 and type 7 records, and after this would come one or more detail records. You can include more than one manifest in a file by including another type 1 record and associated detail records.

For Air-AMS, the manifest information record is required, and all the fields must be supplied. Additionally, if you send multiple manifests in a single file, they must all have the same manifest_destination.

For non-Air-AMS you aren't required to have a manifest information record. If you don't use one, we won't be able to print out manifests of this data, but it will still be available at gateway time.

Field Name Type Required? Additional Information
record_type 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. See the Validating MAWBs for more information.

Detail (Shipment) Records

Record type 12 is the detail record. For each shipment on the manifest you include a single detail record. A multi-piece shipment which is going to be cleared as such with US Customs must have a single detail record, and that record must have the physical package count in the num_pieces field.
Field Name Type Required? Additional Information Programmer's Notes
record_type integer always always "12" 2
profile_key integer never usually null 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. 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:

your full HAWB HAWB sent to US CBP result
543210987654321 10987654321 OK
54321098765432ABCD1 10987654321 HAWB rejected

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.

Historical note: Before 2018-03-01 it was required that you do the conversion on your HAWB and put the result in this field, with the full HAWB in the internal_reference field. It is no longer necessary do it this way, but it is still allowed.

2
ship_ref_num char(11) never your customer's reference number 2
internal_reference char(40) never usually null 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 "USA" for US destinations.

2
outlying char(1) never X for outlying, null otherwise 2
service_provider char(3) never use list provided by your account manager, null otherwise 10
dls_station char(3) never leave null 2
dls_final_destination char(3) never leave null 2
num_pieces decimal(3,0) required for Air-AMS the number of pieces associated with this HAWB 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_unit char(1) required if weight is not null P = pounds, K = 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 null. 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 null or 0 for DOC shipments 2
insurance_amount decimal(9,2) never in US dollars or the given currency_code, but only if 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
harmonized_code char(10) never the harmonized code, used for US Customs classification purposes

Must be 8 or 10 digits if provided. Consult with our brokerage department to find out if this is required for your shipments.

9
fda_prior_notice char(12) never the FDA Prior Notice number, if filed, 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 null unless told otherwise by IBC, when it is supplied the valid values are "P"repaid, "S"pecials, and "F"ree Domeciles (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 it the field is left null), 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, only when terms = "C", cannot be negative 2
cust_key integer never leave null unless told otherwise by IBC 2
ship_acct_num char(4) never your account number with IBC, or null 2
dls_acct_num char(12) never leave null unless told otherwise by IBC 2
ext_cust_acct char(11) never leave null 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) see notes at right

  • If you are using detail record types 2, 3, or 4:

    For shipments to the US, the consignee_state field must contain the two letter state code and the 5 (or more) digit zip, formatted like "NY 11435" or "NY, 11435".

    For non-US shipments, the consignee_state field should contain both the state/province (abbreviated to two characters where possible), and the postal code. They should be separated by a comma and optionally a space.

  • If you are using any other detail record type:

    consignee_state contains the state/province (abbreviated to 2 characters where possible). This field is required for shipments to the US and Canada.

    consignee_postal_code contains the postal/zip code. This field is required for shipments to the US and Canada.

2
consignee_postal_code char(20) see notes at right 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
comments char(512) never comments or notes about the shipment 8

Additional information for Air-AMS customers

When you send a live file, you will receive either a positive acknowledgment that the data was good, or a negative error message. If you receive no acknowledgment, then it means that something went seriously wrong, and you should contact IBC. You will normally receive a response within 20 minutes of your transmission.

If you receive a positive response, then that manifest is "locked" — you cannot update it. If you were to resend that data, you would get an error message for each shipment / manifest that we had already successfully processed. Instead, 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 have to update the data.

If you receive an error message, then 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.

Lastly, you may receive warning messages about non-critical errors along with the "good data" acknowledgments. Those warnings are designed to give you time to begin to identify sources of invalid data, as we anticipate needing to enforce stricter data validation in the future. The warnings will start with the word "NOTICE" to differentiate them from errors, and you will still see the line Successfully loaded Air-AMS data: and the manifest summary if the data was loaded successfully.

Sample Data

You can download a file of sample data in the file aams-manifest-sample.csv. As mentioned earlier, your company may fill in some different fields that you see used in this example. The file specification provides the exact details of what is required and what is optional. Also, the company names and individual names have been randomly changed in order to keep client information confidential, but it should be clear how each field is being used. To reduce how much manual editing we had to do, while there are 114 shipments in the sample file, there are only 8 different shippers. Typically, you would have many more unique shippers, since you must provide the TRUE SHIPPER to US Customs. Lastly, while all of the sample descriptions are acceptable from a technical (systems) perspective, they may not be acceptable to US Customs.

Submitting Data Via The Web Form

For most customers the web submission form is the simplest way to get the shipment data to IBC. After entering the e-mail submission (report) address and your e-mail address, each part of the header information (Type 1) is entered into the corresponding text boxes and the manifest records (Type 9) are pasted into the Manifest Data text box.

Emailing Data to IBC

If you're submitting your data via email it must be sent in an email message which is either not a MIME message or is a single-part MIME message with a Content-Type from the following list:

Live data cannot be sent in a multipart MIME message. Many customers have trouble with this requirement. If this is the case for you we suggest you use the web form to submit your data instead.

You can test your ability to send the data as a single part message by sending a test message to yourself. Look at the full headers of the message you receive. (For example, in Thunderbird select View then Message Source.) If there is a "Content-Type" header and the value starts with "multipart" then it won't work. There should either be no Content-Type header, or if there is one the value has to start with something other then multipart (for example, "text/plain" or "text/csv").

Some customers are able to send one of these types, but the email program line-wraps the data in the file (which will cause failures), or a virus-scanner adds a message to the email which makes the data invalid.

It is important that you use the same software to send the test files as you will use in live production. We have had numerous cases where the test files looked good, and only when the live files were transferred did we see that the emails were not being sent properly.

Validating MAWBs

The IATA and US Customs rules for IATA MAWB's require that all MAWB's have a three digit Airline prefix and then eight digits. Those eight digits are a seven digit serial number and a mod 7 (unweighted) check digit.

Using the MAWB 180-62148741 as the example, the airline prefix is 180, the seven digit serial number is 6214874, and the check digit is a 1.

To confirm that 1 is the correct mod 7 check digit, you can determine the check digit two different ways. Method one:

    1. Divide the seven digit serial number by 7
               6214874 / 7 = 887839.1428...
    2. multiply first number after decimal by 7
                .1 x 7 = 0.7
    3. round the result up, to determine the check digit
                0.7 rounds up to 1
                the check digit is 1 (if the result were a whole
                  number, then no rounding is required)

and method two:

    1. Divide the non-check digits by 7
               6214874 / 7 = 887839.1428...
    2. multiply the integer result by 7
                887839 x 7 = 6214873
    3. The difference between the number you started with and the result
       of step 2 is the check digit:
               6214874 - 6214873 = 1
                the check digit is 1

These calculations confirm that 62148741 is a valid MAWB suffix, and as long as the 180- prefix is the correct airline prefix, you know you have a valid MAWB.

Programmer's Notes

As requirements change we add fields and/or change data validation. The semantics for a detail record type don't change, instead there is a new record version assigned. The Programmer's Notes column indicates in which version of the detail record a field appeared for the first time.