Introduction
BorderConnect's API provides an easy way to exchange eManifest related data. This allows carriers, dispatch software, or other business software to send eManifest data electronically for submission to Canada Border Services Agency (CBSA) or U.S. Customs and Border Protection (CBP). BorderConnect's API abstracts away a lot of the complex business logic and redundancy present with customs message maps.
All data is encoded as JSON (Java Script Object Notation). JSON is a simple, text base format that is programming language independent. JSON is easy to understand, read, write, and parse. It's also very well supported as the main data structure of JavaScript Objects.
Data is either uploaded manually by users via BorderConnect's web interface or sent automatically (server-to-server) using Secure WebSocket Protocol.
Terms Used In This Document
- Service Provider: A company that exchanges API data for multiple companies. For example, dispatch software or customs broker.
- Carrier: A company who is required to send eManifest data. They should have their own Canadian Carrier Code and SCAC Code (or multiple carrier codes and scac codes.)
- API Key: Unique security key used to identify connecting party. This key should not be shared and only transmitted over a secure websocket connection. It should also only be present in initial handshake message. If your API Key is compromised, please regenerate it under Company Preferences. If you're connecting via Service Provider, you do not need to generate API Key as they will be providing connectivity.
- Company Key: A unique identifier used to identify cross border carrier. This company must have valid account with BorderConnect and data will be send and received using this key. It is not used for security, it's simply an identifier of company account within BorderConnect.
Connecting with BorderConnect API
BorderConnect provides each company that wishes to connect a unique URL in the format:
wss://borderconnect.com/api/sockets/[your_suffix]
When you connect to the URL, you have 10 seconds to send a valid API Key which either identifies the service provider or the carrier. If service provider API key is provided, all inbound and outbound messages will require a companyKey value to be supplied. This allows service provider to establish one connection and send for multiple carriers. If carrier API Key is provided, inbound and outbound messages do not require the companyKey (however it may be provided).
Introduction to WebSockets
The WebSocket Protocol establishes persistent two-way connections between clients and servers. HTTP (Hypertext Transfer Protocol), though widely used, is not conducive to facilitating persistent “full duplex” connections. The WebSocket Protocol was developed to compensate for this weakness in HTTP.
WebSockets have a number of advantages over the alternatives:
- Ease of Use: WebSockets are easy to use and integrate with. Server-side and client-side implementations are characterized by consistency, simplicity, and elegance. On the server side, they eliminate the need for complicated persistence and polling mechanisms. On the client side, a simple WebSocket client can be developed in several minutes in just about any development environment, including JavaScript.
- Power and Flexibility: WebSockets join the power and flexibility of raw TCP with some of the benefits of HTTP, such as its meta data and its security model.
- Performance: WebSockets use essentially raw TCP-Sockets, avoiding the overhead that is inherent in HTTP and other protocols. Their use reduces unnecessary header traffic and network latency. Older technologies such as Push or Comet use HTTP and hence are encumbered with unnecessary overhead.
Example Client Implementations
Java Client
// WebSocket library: https://github.com/TooTallNate/Java-WebSocket
// JSON library: http://argo.sourceforge.net/
public class BorderConnectClient extends WebSocketClient {
// on connection open, send api key
public void onOpen( ServerHandshake serverHandshake ) {
send( "{ \"apiKey\": \"a-9000-3ee67a05ee8afc2d\" }" );
}
// if we receive OK on api key, import an ACE Manifest
public void onMessage( String jsonMessage ) {
JsonRootNode jsonNode = jdomParser.parse( jsonMessage );
if ( "OK".equals( jsonNode.getNullableStringValue( "status" ) ) ) {
send( "{ \"data\": \"ACE_TRIP\", \"sendId\": \"001\", \"companyKey\": \"c-9000-2bcd8ae5954e0c48\", \"operation\": \"CREATE\", \"tripNumber\": \"AAAA123457A\", \"usPortOfArrival\": \"0101\", \"estimatedArrivalDateTime\": \"2014-07-31 04:45:00\", \"truck\": { \"number\": \"2013\", \"type\": \"TR\", \"vinNumber\": \"AG12XXXXXXXXXF\", \"licensePlate\": { \"number\": \"TEMP5\", \"stateProvince\": \"ON\" } }, \"trailers\": [ { \"number\": \"0456\", \"type\": \"TL\", \"licensePlate\": { \"number\": \"JV2012\", \"stateProvince\": \"ON\" } } ], \"drivers\": [ { \"driverNumber\": \"D004\", \"firstName\": \"Michael\", \"lastName\": \"Dorn\", \"gender\": \"M\", \"dateOfBirth\": \"1970-01-01\", \"citizenshipCountry\": \"CA\", \"fastCardNumber\": \"42705555555501\" } ], \"shipments\": [ { \"data\": \"ACE_SHIPMENT\", \"sendId\": \"001\", \"companyKey\": \"c-9000-2bcd8ae5954e0c48\", \"operation\": \"CREATE\", \"type\": \"PAPS\", \"shipmentControlNumber\": \"AAAAA754321\", \"provinceOfLoading\": \"NU\", \"shipper\": { \"name\": \"Art place\", \"address\": { \"addressLine\": \"1234 Vancity\", \"city\": \"Vancouver\", \"stateProvince\": \"BC\", \"postalCode\": \"V6H 3J9\" } }, \"consignee\": { \"name\": \"Elk Corp of Texas\", \"address\": { \"addressLine\": \"401 Weavertown Rd\", \"city\": \"Myerstown\", \"stateProvince\": \"PA\", \"postalCode\": \"17067\" } }, \"commodities\": [ { \"loadedOn\": { \"type\": \"TRAILER\", \"number\": \"0456\" }, \"description\": \"Books\", \"quantity\": 35, \"packagingUnit\": \"BOX\", \"weight\": 1500, \"weightUnit\": \"L\" } ] } ], \"autoSend\": false }" );
}
}
}
public void testSendAceTripToBorderconnect() {
new BorderConnectClient( "wss://borderconnect.com/api/sockets/jones" ).run();
}
C# Client
// WebSocket library: https://github.com/sta/websocket-sharp
// JSON library: http://james.newtonking.com/json
//
// NOTE: If you encounter issues with the library truncating your
// messages you may need to modify the websocket-sharp's WebSocket.cs file
// by changing FragmentLength to 1016*50, recompile the DLL, and then
// link your project to the new DLL.
public const string API_KEY = "a-9000-3ee67a05ee8afc2d";
public static void Main() {
using ( var ws = new WebSocket( "wss://borderconnect.com/api/sockets/jones" ) ) {
// on connection open, send api key
ws.OnOpen += ( sender, e ) => {
Console.WriteLine( "Sending handshake with API key [" + API_KEY + "]" );
ws.Send( "{ \"apiKey\": \"" + API_KEY + "\" }" );
};
// if we receive OK on api key, send an ACE eManifest
ws.OnMessage += ( sender, e ) => {
Console.WriteLine("Received message [" + e.Data + "]");
dynamic responseJson = JObject.Parse( e.Data );
if ( responseJson["status"] == "OK" ) {
Console.WriteLine("Sending example ACE trip");
ws.Send( "{ \"data\": \"ACE_TRIP\", \"sendId\": \"001\", \"companyKey\": \"" + API_KEY + "\", \"operation\": \"CREATE\", \"tripNumber\": \"AAAA123457A\", \"usPortOfArrival\": \"0101\", \"estimatedArrivalDateTime\": \"2014-07-31 04:45:00\", \"truck\": { \"number\": \"2013\", \"type\": \"TR\", \"vinNumber\": \"AG12XXXXXXXXXF\", \"licensePlate\": { \"number\": \"TEMP5\", \"stateProvince\": \"ON\" } }, \"trailers\": [ { \"number\": \"0456\", \"type\": \"TL\", \"licensePlate\": { \"number\": \"JV2012\", \"stateProvince\": \"ON\" } } ], \"drivers\": [ { \"driverNumber\": \"D004\", \"firstName\": \"Michael\", \"lastName\": \"Dorn\", \"gender\": \"M\", \"dateOfBirth\": \"1970-01-01\", \"citizenshipCountry\": \"CA\", \"fastCardNumber\": \"42705555555501\" } ], \"shipments\": [ { \"data\": \"ACE_SHIPMENT\", \"sendId\": \"001\", \"companyKey\": \"c-9000-2bcd8ae5954e0c48\", \"operation\": \"CREATE\", \"type\": \"PAPS\", \"shipmentControlNumber\": \"AAAAA754321\", \"provinceOfLoading\": \"NU\", \"shipper\": { \"name\": \"Art place\", \"address\": { \"addressLine\": \"1234 Vancity\", \"city\": \"Vancouver\", \"stateProvince\": \"BC\", \"postalCode\": \"V6H 3J9\" } }, \"consignee\": { \"name\": \"Elk Corp of Texas\", \"address\": { \"addressLine\": \"401 Weavertown Rd\", \"city\": \"Myerstown\", \"stateProvince\": \"PA\", \"postalCode\": \"17067\" } }, \"commodities\": [ { \"loadedOn\": { \"type\": \"TRAILER\", \"number\": \"0456\" }, \"description\": \"Books\", \"quantity\": 35, \"packagingUnit\": \"BOX\", \"weight\": 1500, \"weightUnit\": \"L\" } ] } ], \"autoSend\": false }" );
}
};
ws.SslConfiguration.EnabledSslProtocols = System.Security.Authentication.SslProtocols.Tls12;
ws.Connect();
Console.WriteLine("Connection running...");
Console.Out.Flush();
Console.ReadLine();
}
}
JavaScript Client
<script>
function loadWebSocket() {
const API_KEY = "a-9000-3ee67a05ee8afc2d";
const socket = new WebSocket( "wss://borderconnect.com/api/sockets/jones" );
// on connection open, send api key
socket.addEventListener( "open", function ( event ) {
console.log( "Sending handshake with API key [" + API_KEY + "]" );
socket.send( `{ "apiKey": "${API_KEY}" }` );
} );
socket.addEventListener( "message", function ( event ) {
const parsedJson = JSON.parse( event.data );
console.log( "Received response with status [" + parsedJson.status + "]", parsedJson );
if ( parsedJson.status && parsedJson.status == "OK" ) {
console.log( "Sending example ACE trip" );
socket.send( `{ "data": "ACE_TRIP", "sendId": "001", "companyKey": "${API_KEY}", "operation": "CREATE", "tripNumber": "AAAA123457A", "usPortOfArrival": "0101", "estimatedArrivalDateTime": "2014-07-31 04:45:00", "truck": { "number": "2013", "type": "TR", "vinNumber": "AG12XXXXXXXXXF", "licensePlate": { "number": "TEMP5", "stateProvince": "ON" } }, "trailers": [ { "number": "0456", "type": "TL", "licensePlate": { "number": "JV2012", "stateProvince": "ON" } } ], "drivers": [ { "driverNumber": "D004", "firstName": "Michael", "lastName": "Dorn", "gender": "M", "dateOfBirth": "1970-01-01", "citizenshipCountry": "CA", "fastCardNumber": "42705555555501" } ], "shipments": [ { "data": "ACE_SHIPMENT", "sendId": "001", "companyKey": "c-9000-2bcd8ae5954e0c48", "operation": "CREATE", "type": "PAPS", "shipmentControlNumber": "AAAAA754321", "provinceOfLoading": "NU", "shipper": { "name": "Art place", "address": { "addressLine": "1234 Vancity", "city": "Vancouver", "stateProvince": "BC", "postalCode": "V6H 3J9" } }, "consignee": { "name": "Elk Corp of Texas", "address": { "addressLine": "401 Weavertown Rd", "city": "Myerstown", "stateProvince": "PA", "postalCode": "17067" } }, "commodities": [ { "loadedOn": { "type": "TRAILER", "number": "0456" }, "description": "Books", "quantity": 35, "packagingUnit": "BOX", "weight": 1500, "weightUnit": "L" } ] } ], "autoSend": false }` );
}
} );
}
window.addEventListener( "load", loadWebSocket, false );
</script>
Python Client
# WebSocket library: https://github.com/Lawouach/WebSocket-for-Python
from ws4py.client.threadedclient import WebSocketClient
import json
class BorderConnectClient( WebSocketClient ):
# on connection open, send api key
def opened( self ):
self.send( '{ "apiKey": "a-9000-3ee67a05ee8afc2d" }' )
# if we receive OK on api key, send an ACE eManifest
def received_message( self, response ):
content = json.loads( response.data.decode( "utf-8" ) )
if content.has_key( 'status' ) and content['status'] == "OK":
self.send( '{ "data": "ACE_TRIP", "sendId": "001", "companyKey": "c-9000-2bcd8ae5954e0c48", "operation": "CREATE", "tripNumber": "AAAA123457A", "usPortOfArrival": "0101", "estimatedArrivalDateTime": "2014-07-31 04:45:00", "truck": { "number": "2013", "type": "TR", "vinNumber": "AG12XXXXXXXXXF", "licensePlate": { "number": "TEMP5", "stateProvince": "ON" } }, "trailers": [ { "number": "0456", "type": "TL", "licensePlate": { "number": "JV2012", "stateProvince": "ON" } } ], "drivers": [ { "driverNumber": "D004", "firstName": "Michael", "lastName": "Dorn", "gender": "M", "dateOfBirth": "1970-01-01", "citizenshipCountry": "CA", "fastCardNumber": "42705555555501" } ], "shipments": [ { "data": "ACE_SHIPMENT", "sendId": "001", "companyKey": "c-9000-2bcd8ae5954e0c48", "operation": "CREATE", "type": "PAPS", "shipmentControlNumber": "AAAAA754321", "provinceOfLoading": "NU", "shipper": { "name": "Art place", "address": { "addressLine": "1234 Vancity", "city": "Vancouver", "stateProvince": "BC", "postalCode": "V6H 3J9" } }, "consignee": { "name": "Elk Corp of Texas", "address": { "addressLine": "401 Weavertown Rd", "city": "Myerstown", "stateProvince": "PA", "postalCode": "17067" } }, "commodities": [ { "loadedOn": { "type": "TRAILER", "number": "0456" }, "description": "Books", "quantity": 35, "packagingUnit": "BOX", "weight": 1500, "weightUnit": "L" } ] } ], "autoSend": false }' )
client = BorderConnectClient( 'wss://borderconnect.com/api/sockets/jones' )
client.connect()
client.run_forever()
Ruby Client
# WebSocket library: https://github.com/shokai/websocket-client-simple
require 'rubygems'
require 'websocket-client-simple'
require 'json'
ws = WebSocket::Client::Simple.connect 'wss://borderconnect.com/api/sockets/jones'
# on connection open, send api key
ws.on :open do
ws.send '{ "apiKey": "a-9000-3ee67a05ee8afc2d" }'
end
# if we receive OK on api key, send an ACE eManifest
ws.on :message do |msg|
parsed_json = JSON.parse(msg.data)
if parsed_json.has_key?("status") and parsed_json["status"] == "OK"
ws.send '{ "data": "ACE_TRIP", "sendId": "001", "companyKey": "c-9000-2bcd8ae5954e0c48", "operation": "CREATE", "tripNumber": "AAAA123457A", "usPortOfArrival": "0101", "estimatedArrivalDateTime": "2014-07-31 04:45:00", "truck": { "number": "2013", "type": "TR", "vinNumber": "AG12XXXXXXXXXF", "licensePlate": { "number": "TEMP5", "stateProvince": "ON" } }, "trailers": [ { "number": "0456", "type": "TL", "licensePlate": { "number": "JV2012", "stateProvince": "ON" } } ], "drivers": [ { "driverNumber": "D004", "firstName": "Michael", "lastName": "Dorn", "gender": "M", "dateOfBirth": "1970-01-01", "citizenshipCountry": "CA", "fastCardNumber": "42705555555501" } ], "shipments": [ { "data": "ACE_SHIPMENT", "sendId": "001", "companyKey": "c-9000-2bcd8ae5954e0c48", "operation": "CREATE", "type": "PAPS", "shipmentControlNumber": "AAAAA754321", "provinceOfLoading": "NU", "shipper": { "name": "Art place", "address": { "addressLine": "1234 Vancity", "city": "Vancouver", "stateProvince": "BC", "postalCode": "V6H 3J9" } }, "consignee": { "name": "Elk Corp of Texas", "address": { "addressLine": "401 Weavertown Rd", "city": "Myerstown", "stateProvince": "PA", "postalCode": "17067" } }, "commodities": [ { "loadedOn": { "type": "TRAILER", "number": "0456" }, "description": "Books", "quantity": 35, "packagingUnit": "BOX", "weight": 1500, "weightUnit": "L" } ] } ], "autoSend": false }'
end
PHP Client
// WebSocket library: https://github.com/Textalk/websocket-php
use WebSocket\Client;
$client = new Client( "wss://borderconnect.com/api/sockets/jones/" );
// send api key
$client->send( "{ \"apiKey\": \"a-9000-3ee67a05ee8afc2d\" }" );
// if we receive OK on api key, send an ACE eManifest
$response = $client->receive();
$json_array = json_decode( $response, true );
if ( array_key_exists( "status", $json_array ) && $json_array['status'] == "OK" ) {
$client->send( '{ "data": "ACE_TRIP", "sendId": "001", "companyKey": "c-9000-2bcd8ae5954e0c48", "operation": "CREATE", "tripNumber": "AAAA123457A", "usPortOfArrival": "0101", "estimatedArrivalDateTime": "2014-07-31 04:45:00", "truck": { "number": "2013", "type": "TR", "vinNumber": "AG12XXXXXXXXXF", "licensePlate": { "number": "TEMP5", "stateProvince": "ON" } }, "trailers": [ { "number": "0456", "type": "TL", "licensePlate": { "number": "JV2012", "stateProvince": "ON" } } ], "drivers": [ { "driverNumber": "D004", "firstName": "Michael", "lastName": "Dorn", "gender": "M", "dateOfBirth": "1970-01-01", "citizenshipCountry": "CA", "fastCardNumber": "42705555555501" } ], "shipments": [ { "data": "ACE_SHIPMENT", "sendId": "001", "companyKey": "c-9000-2bcd8ae5954e0c48", "operation": "CREATE", "type": "PAPS", "shipmentControlNumber": "AAAAA754321", "provinceOfLoading": "NU", "shipper": { "name": "Art place", "address": { "addressLine": "1234 Vancity", "city": "Vancouver", "stateProvince": "BC", "postalCode": "V6H 3J9" } }, "consignee": { "name": "Elk Corp of Texas", "address": { "addressLine": "401 Weavertown Rd", "city": "Myerstown", "stateProvince": "PA", "postalCode": "17067" } }, "commodities": [ { "loadedOn": { "type": "TRAILER", "number": "0456" }, "description": "Books", "quantity": 35, "packagingUnit": "BOX", "weight": 1500, "weightUnit": "L" } ] } ], "autoSend": false }' );
}
Data Layer - JSON Messages
API Response Message Map
When data is transmitted, BorderConnect's API will respond with an API Response message. The response will provide status of your request. For example, when a client connects and provides a valid API Key, they will receive a message like:
{
"data": "API_RESPONSE",
"status": "OK",
"message": "Connected",
"dateTime": "2014-12-15 03:18:23"
}
When data is processed successfully, the client will receive a message like:
{
"data": "API_RESPONSE",
"status": "IMPORTED",
"message": "1 ACI Trip [1234923ASDF] successfully imported",
"dateTime": "2014-12-15 10:09:41",
"tripCount": 1,
"shipmentCount": 2,
"tripNumber": "1234923ASDF"
}
When data fails to process, the client will receive a message like:
{
"data": "API_RESPONSE",
"status": "DATA_ERROR",
"message": "1 ACI Trip [1234923ASDF] failed",
"errors": [
{
"identifier": "1234923ASDFA",
"note": "Trip Number is already used (must be unique for a CREATE operation) [1234923ASDFA]"
}
],
"dateTime": "2014-12-15 10:15:57",
"tripNumber": "1234923ASDF"
}
The response message is generic and used to confirm data was successfully imported into BorderConnect, or if it failed and the reasons why.
Please view the PDF Message Map for full specification.
Download the JSON Schema if you'd like to validate your JSON to ensure it meets semantic rules.
ACE eManifest JSON Message Map
ACE eManifests are used to meet CBP requirements to identify a cross border carrier, the driver, truck, trailer and shipment information such as shipper and consignee.
BorderConnect's API supports receiving a complete ACE eManifest including shipments or just the list of shipments.
Example ACE eManifest JSON Data:
{
"data": "ACE_TRIP",
"sendId": "001",
"companyKey": "c-9000-2bcd8ae5954e0c48",
"operation": "CREATE",
"tripNumber": "AAAA123457A",
"usPortOfArrival": "0101",
"estimatedArrivalDateTime": "2014-07-31 04:45:00",
"truck": {
"number": "2013",
"type": "TR",
"vinNumber": "AG12XXXXXXXXXF",
"licensePlate": {
"number": "TEMP5",
"stateProvince": "ON"
}
},
"trailers": [
{
"number": "0456",
"type": "TL",
"licensePlate": {
"number": "JV2012",
"stateProvince": "ON"
}
}
],
"drivers": [
{
"driverNumber": "D004",
"firstName": "Michael",
"lastName": "Dorn",
"gender": "M",
"dateOfBirth": "1970-01-01",
"citizenshipCountry": "CA",
"fastCardNumber": "42705555555501"
}
],
"shipments": [
{
"data": "ACE_SHIPMENT",
"sendId": "001",
"companyKey": "c-9000-2bcd8ae5954e0c48",
"operation": "CREATE",
"type": "PAPS",
"shipmentControlNumber": "AAAAA754321",
"provinceOfLoading": "NU",
"shipper": {
"name": "Art place",
"address": {
"addressLine": "1234 Vancity",
"city": "Vancouver",
"stateProvince": "BC",
"postalCode": "V6H 3J9"
}
},
"consignee": {
"name": "Elk Corp of Texas",
"address": {
"addressLine": "401 Weavertown Rd",
"city": "Myerstown",
"stateProvince": "PA",
"postalCode": "17067"
}
},
"commodities": [
{
"loadedOn": {
"type": "TRAILER",
"number": "0456"
},
"description": "Books",
"quantity": 35,
"packagingUnit": "BOX",
"weight": 1500,
"weightUnit": "L"
}
]
}
],
"autoSend": false
}
Please view the PDF Message Map for full specification.
Download the JSON Schema if you'd like to validate your JSON to ensure it meets semantic rules.
ACE Send Request Message Map
An ACE Send Request allows for previously uploaded eManifest data to be transmitted to U.S. Customs and Border Protection (CBP). Although it's possible to have the data automatically transmitted on upload using the ACE eManifest Message Map's “autoSend” flag, this map allows the user the freedom to transmit eManifest data at a time of their choosing. It also allows more advanced options, such as cancelling or amending eManifest data.
Example ACE Send Request JSON Data:
{
"data": "ACE_SEND_REQUEST",
"sendId": "1302213",
"companyKey": "c-9000-2bcd8ae5954e0c48",
"type": "COMPLETE_TRIP_AND_SHIPMENTS",
"tripNumber": "AAAA123457A"
}
Please view the PDF Message Map for full specification.
Download the JSON Schema if you'd like to validate your JSON to ensure it meets semantic rules.
ACE Response Message Map
When ACE eManifest data uploaded via API is transmitted to CBP, the CBP responses to those transmissions will be returned via the API. These responses may include a direct response, such as an accept or reject of the transmission, or an update on the status of the manifest.
Example ACE Response JSON Data:
{
"data": "ACE_RESPONSE",
"dateTime": "2014-12-08 05:36:27",
"cbpDateTime": "2014-12-08 05:35:52",
"sendRequest": {
"type": "COMPLETE_TRIP_AND_SHIPMENTS",
"tripNumber": "AAAA123457A"
},
"processingResponse": {
"shipmentsRejected": 0,
"shipmentsAccepted": 1
}
}
Please view the PDF Message Map for full specification.
Download the JSON Schema if you'd like to validate your JSON to ensure it meets semantic rules.
ACI eManifest JSON Message Map
ACI eManifests are used to meet CBSA requirements to identify a cross border carrier, the driver, truck, trailer and shipment information such as shipper and consignee.
BorderConnect's API supports receiving a complete ACI eManifest including shipments or just the list of shipments.
Example ACI eManifest JSON Data:
{
"data": "ACI_TRIP",
"sendId": "001",
"companyKey": "c-9000-2bcd8ae5954e0c48",
"operation": "CREATE",
"tripNumber": "1234923ASDF",
"portOfEntry": "0440",
"estimatedArrivalDateTime": "2014-12-08 05:45:00",
"truck": {
"number": "10",
"type": "TR",
"vinNumber": "23XXXXXX54XX7",
"dotNumber": "000001",
"insurancePolicy": {
"insuranceCompanyName": "ABC Insurance",
"policyNumber": "123456789",
"issuedDate": "2010-10-20",
"policyAmount": 1000000
},
"licensePlate": {
"number": "TRK1NG",
"stateProvince": "ON"
}
},
"trailers": [
{
"number": "23411",
"type": "TL",
"licensePlate": {
"number": "OKATE1",
"stateProvince": "MI"
}
}
],
"drivers": [
{
"driverNumber": "JD",
"firstName": "John",
"lastName": "Doe",
"gender": "M",
"dateOfBirth": "1980-07-14",
"citizenshipCountry": "US",
"travelDocuments": [
{
"number": "23423562",
"type": "5K",
"stateProvince": "MI"
},
{
"number": "23423562",
"type": "6W",
"stateProvince": "MI"
}
]
}
],
"shipments": [
{
"data": "ACI_SHIPMENT",
"sendId": "001",
"companyKey": "c-9000-2bcd8ae5954e0c48",
"operation": "CREATE",
"shipmentType": "PARS",
"loadedOn": {
"type": "TRAILER",
"number": "23411"
},
"cargoControlNumber": "1234PARS34213341",
"referenceOnlyShipment": false,
"portOfEntry": "0440",
"releaseOffice": "0440",
"estimatedArrivalDate": "2014-12-08 05:45:00",
"cityOfLoading": {
"cityName": "New York",
"stateProvince": "NY"
},
"consolidatedFreight": false,
"shipper": {
"name": "Hazmat Wholesale",
"address": {
"addressLine": "1234 New York ave",
"city": "New York",
"stateProvince": "NY",
"postalCode": "12345"
}
},
"consignee": {
"name": "Canadian Lava Co.",
"address": {
"addressLine": "15 North Town Line Unit 68B",
"city": "River Canard",
"stateProvince": "ON",
"postalCode": "N9J2W2"
}
},
"commodities": [
{
"description": "Plywood",
"quantity": 900,
"packagingUnit": "PCE",
"weight": "35005",
"weightUnit": "LBR"
}
]
}
],
"autoSend": false
}
Please view the PDF Message Map for full specification.
Download the JSON Schema if you'd like to validate your JSON to ensure it meets semantic rules.
ACI Send Request Message Map
An ACI Send Request allows for previously uploaded eManifest data to be transmitted to the Canada Border Services Agency (CBSA). Although it's possible to have the data automatically transmitted on upload using the ACI eManifest Message Map's “autoSend” flag, this map allows the user the freedom to transmit eManifest data at a time of their choosing. It also allows more advanced options, such as cancelling or amending eManifest data.
Example ACI Send Request JSON Data:
{
"data": "ACE_SEND_REQUEST",
"sendId": "1302213",
"companyKey": "c-9000-2bcd8ae5954e0c48",
"tripNumber": "1234923ASDF",
"type": "ORIGINAL",
"bundleTripAndShipments": true
}
Please view the PDF Message Map for full specification.
Download the JSON Schema if you'd like to validate your JSON to ensure it meets semantic rules.
ACI Response Message Map
When ACI eManifest data uploaded via API is transmitted to CBSA, the CBSA responses to those transmissions will be returned via the API. The responses in this map will either be an accept or reject of the eManifest data transmitted. Please note that status updates will for ACI eManifest data will use the ACI Notice Message Map instead.
Example ACI Response JSON Data:
{
"data": "ACI_RESPONSE",
"sendRequest": {
"tripNumber": "1234923ASDF",
"type": "ORIGINAL",
"bundleTripAndShipments": true
},
"dateTime": "2014-12-08 03:50:36",
"cbsaDateTime": "2014-11-20 03:45:00",
"type": "ACCEPT",
"tripNumber": "1234923ASDF"
}
Please view the PDF Message Map for full specification.
Download the JSON Schema if you'd like to validate your JSON to ensure it meets semantic rules.
ACI Notice Message Map
When ACI eManifest data uploaded via API is transmitted to CBSA, the CBSA responses to those transmissions will be returned via the API. This map details potential status updates the client can receive from CBSA regarding their eManifests. Please note that accepts or rejects will use the ACI Response Message Map instead.
Example ACI Notice JSON Data:
{
"data": "ACI_NOTICE",
"dateTime": "2014-12-12 11:43:04",
"cbsaDateTime": "2014-12-11 11:39:00",
"type": "NOT_MATCHED",
"cargoControlNumber": "1234923ABCD"
}
Please view the PDF Message Map for full specification.
Download the JSON Schema if you'd like to validate your JSON to ensure it meets semantic rules.
RNS JSON Message Map
The Release Notification System (RNS) is provided by the Canada Border Services Agency (CBSA) to provide automatic updates to carriers, customs brokers, bonded warehouses, and other trade participants regarding the customs clearance status of their cargo. The most common use of an RNS message in BorderConnect is for a carrier to be able to verify that their PARS is cleared by the customs broker before crossing the border.
Unlike other updates, which are tied to eManifest submissions, RNS messages are sent to the client regardless of whether and when an eManifest has been submitted. In order to receive RNS messages via the API, the company must have an RNS profile set up in BorderConnect, and must have the option “API Subscription for All RNS Shipments” set to Yes under Company Preferences.
Example RNS JSON Data:
{
"data": "RNS_SHIPMENT",
"cargoControlNumber": "1234PARS382666",
"transactionNumber": "17889003009937",
"driverName": "Andrew Robinson",
"serviceOption": {
"number": "117",
"name": "PARS, paper"
},
"releaseOffice": {
"number": "0453",
"name": "WINDSOR AMBASSADOR BRIDGE"
},
"status": {
"dateTime": "2014-11-23 03:11:00",
"releaseCode": {
"number": "9",
"shortName": "Declaration Accepted",
"longName": "Declaration Accepted, Awaiting arrival of goods"
}
}
}
Please view the PDF Message Map for full specification.
Download the JSON Schema if you'd like to validate your JSON to ensure it meets semantic rules.
