IBC Air AMS - API Submit

Purpose

The IBC Air AMS API allows you to integrate the submission of your U.S. bound manifests to your system. This service has two purposes:

The direct submission of your manifest data to the IBC Air AMS system.
Test the quality of your Air AMS manifest.

This RESTful service accepts your manifest data using a JSON structure that can be easily generated from many popular programming languages.

The Web API adheres to the REST architecture and returns notifications in JSON format.

How to Submit

The service URL is:
https://api.pactrak.com/manifest/aams

Your client must use POST HTTP method to successfully submit your JSON structure.

To test the content of your submission please use the following service URL:
https://api.pactrak.com/manifest/aams?_test

If you are testing a CFS Manifest:
https://api.pactrak.com/manifest/aams?_test&_cfs

What to Expect

For standard submissions, you will receive either an accept or failure email notification to the address list your provided.

Attention: Your API submission is not the final step in the process. If it is denied, the email will contain messages that require your immediate attention. Upon fixing these errors, you will be able to resubmit with the ultimate goal of receiving a standard acknowledgment from the Air AMS system. The final successful message is your official notice that we have accepted your data for CBP processing and that it is integrated into our systems.

For test submissions, the system will run tests of your data and respond back with a report via email to the address list you provided.

Please see the JSON structure on how to set up your submission.

The JSON Structure

For your submissions you must create the following JSON structure:

/** Main submission parameter is called aams, it contains 2 String objects and 1 Array of manifest objects
You could also submit as JSON object, by setting the "Content-Type: application/json" header. For Curl sample see the submit sample. */
aams = {

/**
* The IBC Supplied email address for your account submissions.
* For test submissions please use it@ibcinc.com
* @type String
*/
"assigned_email" : "",

/** USE either to_email or success_email and error_email combo. */
/**
* A comma separated list or CSV of your email addresses. This list will generate both success and error notices automatically.
* @type String
*/
"to_email" : "",

/**
* OPTIONAL - use instead of to_email and must also include error_email.
* A comma separated list or CSV of your email addresses for success notices.
* Specify also error_email.
* @type String
*/
"success_email" : "",

/**
* OPTIONAL - use instead of to_email and must also include success_email.
* A comma separated list or CSV of your email addresses for error notices.
* Specify also success_email.
* @type String
*/
"error_email" : "",

/**
* OPTIONAL - For Section Type 84 Entries send this parameter as written. Please consult with your sales manager for approval.
* @type String
*/
"entry_type" : "84",

/**
* OPTIONAL - For customers sending approved Section 321 submissions, set the US CBP assigned ID here.
* @type String
*/
"sec321_originator" : "",

/**
* An array of manifest objects called manifest. It should have at least 1 object.
* @type Array
*/
"manifest" : [ {

/** This is the JSON structure for 1 manifest
* A single line that contains the specific manifest information.
* This is a comma separated (CSV) line with these 7 columns:
* record_type, man_code, man_date, man_origin, man_dest, flight_info, man_info
* Please review http://www.pactrak.com/manifest-to-pactrak.html
* under the heading "Manifest Records" for the details and format for each column.
* @type String 1 line required for each manifest being reported.
*/
"manifest_line": "",

/**
* Your shipment manifest lines. The format of these lines are documented
* in http://www.pactrak.com/manifest-to-pactrak.html
* under the heading "Detail (Shipment) Records"
* @type String 1 line per package separated with a "\n" separator.
*/
"manifest_data": ""
} ]

}

You may submit multiple manifest objects by appending a subsequent manifest structure separated with a comma (,)
in the manifest section. For example, the following entry has 3 total manifest objects:
{ "assigned_email" : "", to_email: "", "manifest" : [ { m* }, { m* }, { m* } ] }
m* = { "manifest_line" : "", "manifest_data" : "" }

After making a successful submission you should expect a return of one of the following JSON structures:

Successful JSON structure

{

/**
* The HTTP response code
* @type Integer.
*/
"code": 200,

/**
* Response message relevant to the action requested.
* @type String.
*/
"message":"",

/**
* A link to the resource.
* @type String.
*/
"href":"https://api.pactrak.com/manifest/aams",

/**
* The content type supported
* @type String.
*/
"content Type":"application/json;charset=UTF-8"
}
Failures

{

/**
* The HTTP response code
* @type Integer.
*/
"code":400,

/**
* Response message relevant to the action requested.
* @type String.
*/
"message":"The following email may not be valid: @gmail.com",

/**
* Response message intended for the development team.
* @type String.
*/
"developerMessage":"",

/**
* A link to the resource
* @type String.
*/
"href":"https://api.pactrak.com/manifest/aams",

/**
* The content type supported
* @type String.
*/
"contentType":"application/json;charset=UTF-8"

}

Simple Testing

The easiest way to test your POST request is to use cURL from the system's command line.

We recommend saving your JSON structure into a text file ( input-file.txt ) and then execute this command:
This is a submission as 'application/x-www-form-urlencoded'.

curl -siL -X POST -k --data "@input-file.txt" https://api.pactrak.com/manifest/aams?_test

You can also submit strictly as JSON object with the following command. Note the JSON structure should not have the parameter name 'aams'.

curl -siL -H "Content-Type: application/json" -X POST -d "@input-file.txt" https://api.pactrak.com/manifest/aams?_test

This is a sample JSON structure ready for testing.

{"assigned_email":"it@ibcinc.com","to_email":"myemail@email.com","manifest":[{"manifest_line":"1,1034644,20140821,MIA,BUE,AA544,12573370091","manifest_data":"8,,277079283,,,,LHR,SAO ,,,,1,0.5,P,DOC,,,,,P,P,ST,,,,,,STILL DIFFERENT CO INC,1234 NEW ROAD,,FRANKFURT,,,DE, 49691231234,RUBENS ANDRADE,COMPANY 82,AV PAULISTA 2300 4TH 5TH FLRS,,SAO PAULO ,SP,01310-300,BR,,\n8,,278975857,,,,LHR,SAO,,,,1,0.5,P,DOC,,,,,P,P,ST,,,,,,STILL DIFFERENT CO INC,1234 NEW ROAD,,FRANKFURT,,,DE, 49691231234,ADEMAR RIBEIRO, COMPANY 83,AV MARIA COELHO AGUIAR 215 BLOCO,C-2 ANDAR,SAO PAULO ,SP,05805-000,BR,,\n8,,280872431,,,,LHR,SAO,,,,1,0.5,P,DOC,,,,,P,P,ST,,,,,,STILL DIFFERENT CO INC, 1234 NEW ROAD,,FRANKFURT,,,DE, 49691231234,CARLOS GULLO,COMPANY 84,AV MARIA COELHO AGUIAR 215 BLOCO,C-2 ANDAR,SAO PAULO ,SP,05805-000,BR,,\n"}]}

Testing Recommendations

We highly recommend that you test your applications by submitting POST requests to this service's test URL first: https://api.pactrak.com/manifest/aams?_test, and that you follow up with the
IBC IT Department, until you receive your official Air AMS production email address from IBC. Please review the notes in the JSON structure above for details on how your manifest request object should be setup for tests.

As a backup, we also recommend that your operations team is capable of submitting the form data manually through the IBC Air AMS Web form, in cases where a manual submittal of your data is required.

Developer Resources

If you desire to test the format of your files offline, you can review the source code used within this project and execute your tests by downloading the project source from: IBC Manifest Analyzer Project.