API Documentation


CreateShipment

The CreateShipment API will provide you with a carrier compliant shipping label for a variety of carriers such as: FedEx, UPS, Purolator, PTC, CanadaPost, etc.

Quick Links
What can you do with CreateShipment?
POST /webship/api/createshipment

Get the carrier compliant shipping label for the selected carrier.
CreateShipment - Request Properties
ApiKey
{ "ApiKey": "APIKEY" }

The API key for your account.
 
AccountNumber
{ "AccountNumber": "ZZZZZ" }

Your Secureship account number.
 
Username
{ "Username": "user@mycompany.com" }

The username you use to log into your Secureship account.
 
ReturnSampleData
{ "ReturnSampleData": "true" }

Sample data is returned (significantly faster and best for testing).
 
TestMode
{ "TestMode": true }

This value indicates if you want a test label to be returned. Test labels are not valid for shipping and best used after having tested with ReturnSampleData.
 
ShipDateTime
{ "ShipDateTime": "2015-08-13T15:59:00"}

Date and time the package will ship.
 
FromAddress
{ "FromAddress": {
"Company": "Company ABC",
"Contact": "Contact ABC",
"Tel": "613‐555‐1234",
"Addr1": "1500 Bank St",
"Addr2": "Suite 614",
"CountryCode":"CA",
"PostalCode":"K1H-1B8",
"City":"Ottawa",
"Province":"ON",
"Residential":false
}
}

The full ship from address information of your shipment.

Addr1: This is the street name and number of the address. This field is mandatory

Addr2: If you have additional street name information, it will go here. This field is optional.

Company: If the ship from address is from a person and not a company, enter the person's name in the Company field as well as the Contact field

CountryCode: The ISO 3166-1 alpha-2 two-letter country code for the country.
 
ToAddress
{ "ToAddress": {
"Company": "Company ABC",
"Contact": "Contact ABC",
"Tel": "613‐555‐1234",
"Addr1": "1 Main St",
"Addr2": "Building 1",
"Addr3": "Unit 5",
"CountryCode":"US",
"PostalCode":"90210",
"City":"Beverly Hills",
"Province":"CA",
"Residential":false
}
}

The full destination address information of your shipment.

Addr1: This is the street name and number of the address. This field is mandatory.

Addr2, Addr3: If you have additional street name information, it will go here. These fields are optional.

Company: If the destination is to a person, enter the person's name in the Company field as well as the Contact field.

CountryCode: The ISO 3166-1 alpha-2 two-letter country code for the country.

PostalCode: For destinations that do not have a postal code, you may need to enter '0000' or '00000' depending on the requested number of digits.
 
PackageType
{ "PackageType": "MyPackage" }

The type of package being used.
  • MyPackage: Selected when you use your own box
  • Envelope: When the package type used is an envelope provided by the carrier. It will say 'UPS Envelope' or 'FedEx Envelope' on it.
  • Pak: When the package type used is a Pak provided by the carrier. It will say 'UPS Pak' or 'FedEx Pak' on it.
 
Packages
{ "Packages": [
{
  "Weight": 1.5,
  "WeightUnits": "KGS"
},
{
  "Weight": 5,
  "WeightUnits": "LBS",
  "Length": 1,
  "Width": 1,
  "Height": 1,
 "DimensionUnits": "INCHES",
 "Insurance": 100,
  "AdditionalHandling": true,
  "SignatureOption": "SignatureRequired"
} ]
}

List of packages containing the weights, sizes, and additional package options.

WeighUnits: The weight units used.
  • LBS
  • KGS
DimensionUnits: The dimensional units used.
  • INCHES
  • CM
Insurance: The requested amount of insurance for this package and is based on the currency of the ship from country unless specified otherwise on the commercial invoice.

To ensure proper coverage, insurance is specified at the package level and not the shipment level.

Note: Every carrier has different insurance limitations. Please be sure to verify the insurance limitations prior to insuring and shipping your packages.

AdditionalHandling: Specify if the package requires additional handling. Additional handling normally applies to packages not encased in a cardboard box.
  • True
  • False
SignatureOption: Specify if the package requires a signature.
  • None
  • SignatureRequired
  • AdultSignatureRequired - This option is not always available and will vary by carrier and destination.
 
LabelSize
{ "LabelSize": "Paper_85x11" }

The preferred print size of the shipping label. By default, the desktop printer size is returned.

  • Paper_85x11 - Desktop Printer size of 8.5x11"
  • Paper_4x6 - Thermal Printer size of 4x6"
 
SelectedCarrier
{ "SelectedCarrier": 0 }

Indicates which carrier will be used to ship your package.
  • 0 - UPS
  • 1 - FedEx
  • 2 - Purolator
  • 6 - Canpar
  • 8 - Personal Touch Courier
  • 9 - CanadaPost
 
SelectedServiceLevel
{ "SelectedServiceLevel": 0 }

Indicates which service level will be used to ship your package.
  • 0 - UPS Express Early A.M. / UPS Express Plus
  • 1 - UPS Express
  • 2 - UPS Express Saver
  • 3 - UPS Expedited
  • 4 - UPS 3 Day Select
  • 5 - UPS Standard / UPS Ground
  • 6 - UPS 2nd Day Air AM
  • 7 - UPS 2nd Day Air
  • 10 - FedEx First Overnight / FedEx Priority First
  • 11 - FedEx Priority Overnight / FedEx Priority
  • 14 - FedEx Standard Overnight
  • 12 - FedEx 2Day
  • 15 - FedEx Economy
  • 13 - FedEx Ground
  • 20 - Purolator Express 9AM
  • 21 - Purolator Express 10:30AM
  • 28 - Purolator Express 12PM
  • 22 - Purolator Express
  • 23 - Purolator Express Evening
  • 24 - Purolator Ground 9AM
  • 25 - Purolator Ground 10:30AM
  • 29 - Purolator Ground 12PM
  • 26 - Purolator Ground
  • 27 - Purolator Ground Evening
  • 60 - Canpar Express 10AM
  • 61 - Canpar Express 12PM
  • 62 - Canpar Express
  • 63 - Canpar Select 10AM
  • 64 - Canpar Select 12PM
  • 65 - Canpar Select
  • 66 - Canpar Ground 10AM
  • 67 - Canpar Ground 12PM
  • 68 - Canpar Ground
  • 69 - Canpar Select (USA)
  • 70 - Canpar Ground (USA)
  • 71 - Canpar International
  • 80 - PTC Personal
  • 81 - PTC Rush
  • 82 - PTC Non-Rush
  • 83 - PTC Direct Drive
  • 90 - CanadaPost Priority
  • 91 - CanadaPost XpressPost
  • 92 - CanadaPost Expedited Parcel
  • 93 - CanadaPost Parcel
  • 94 - CanadaPost International Parcel Air
  • 95 - CanadaPost International Parcel Surface
 
BillingOption
{ "BillingOption": 0 }

Indicates who will be paying for the shipping. Prepaid is the default shipping option.

  • 0 - Prepaid (Your account will pay for the shipping)
  • 1 - Freight Collect
  • 2 - Third Party
  • 3 - Free Domicile
  • 4 - Delivery Duty Paid
 
BillingAccountNumber
{ "BillingAccountNumber": "ZZZZZZ" }

The carrier account number to bill the shipping charges to. This field is required when BillingOption selected is Freight Collect or Third Party.
 
EmailNotifications
{ "EmailNotifications": [ {
{
  "EmailAddress": "user@mycompany.com",
  "DeliveryConfirmation":true
},
{
  "EmailAddress": "user2@mycompany.com",
  "DeliveryConfirmation":true
} ]
}

An email notification is sent when a certain condition is met.
 
Reference
{ "Reference": "Tradeshow booth" }

This is your internal information relating to your shipment. The information indicated in this field will appear on your invoice and is intended to help you with costing of different shipments to different activities or to different clients.
 
DeliveryComments
{ "DeliveryComments": "Behind Building 3A" }

Delivery comments that can assist the driver in completing the delivery of your shipment.
 
SaturdayDelivery
{ "SaturdayDelivery": false }

Some carriers offer Saturday delivery to select locations. Set the option to true if you would like a Saturday delivery.

Note: please check with the carrier to ensure you comply with their Saturday delivery requirements.
 
DocumentsOnly
{ "DocumentsOnly": false }

Indicates if the shipment contains documents only. This field is required for international shipments.
 
CommercialInvoice
{ "CommercialInvoice":{
"GeneralDescriptionOfGoods":"Sale of electronic equipment",
"ReasonForExport":0,
"Remarks":"This is a test shipment",
"CurrencyCode":"CAD",
"Broker":"UPS",
"Parts":[
{
"Qty":1,
"QtyUnits":"each",
"DetailedDescription":"This is a detailed description of goods",
"CountryOfOrigin":"US",
"UnitValue":6.3404
},
{
"Qty":1,
"QtyUnits":"each",
"DetailedDescription":"This is a detailed description of goods",
"CountryOfOrigin":"US",
"UnitValue":6.3404
} ]
}
}

The commercial invoice information is required for any non-document shipments destined to an international location.

GeneralDescriptionOfGoods: A mandatory field describing the general description of goods.

ReasonForExport: An optional field describing the reason for the export. If no value is provided, a default value of PermanentExport will be used
  • 0 - Permanent / Sold
  • 1 - Temporary
  • 2 - Gift
  • 3 - Repair / Warranty
  • 4 - Commercial Sample
  • 5 - Personal Effects
  • 6 - Return Shipment
Remarks: An optional field used to further describe the general description of goods.

CurrencyCode: The three letter code (ISO 4217) used to describe the currency used on the commercial invoice and other fields requiring a monetary value.

Broker: The customs broker you would like to have the shipment cleared with. A customs broker can only be selected for international ground shipments. This field is optional.

Parts: This is a list containing a detailed breakdown of the contents of your shipment.

Qty: The number of items within the shipment

QtyUnits: The units used to describe the quantity. 'Each' tends to be the general option used by shippers.
  • Each
  • Bag
  • Barrel
  • Box
  • Bunch
  • Bundle
  • Canister
  • Crate
  • Carton
  • Cylinder
  • Dozen
  • Envelope
  • Pallet
  • Piece
  • Pieces
  • Package
  • Pair
  • Pairs
  • Set
DetailedDescription: A detailed description of one of the items within your shipment. This normally includes make, model, brand, and/or composition breakdown.

CountryofOrigin: The ISO 3166-1 alpha-2 two-letter country code for the country where the item originated from.

HSCode: The harmonized system code used to describe the current item. This field is optional.

UnitValue: The Unit Value of the current item. The Unit Value is multiplied against the quantity to provide a total value for this item. The currency code specified above is used to describe the currency amount for this item.

 
CreateShipment - Response Properties
ShipmentDetails
{ "ShipmentDetails":{
"SecureshipTrackingNo":"secureshiptracking",
"CarrierTrackingNos":[
"carrierTrackingNo1",
"carrierTrackingNo2"
],
"ShippingDocuments":""
}
}

SecureshipTrackingNo: The Secureship Tracking Number associated to this shipment.

CarrierTrackingNos: List of Carrier Tracking Numbers associated to this shipment.

ShippingDocuments: A PDF containing the shipping label(s) and commercial invoice (if applicable). Other required documents may also be included in the PDF. All documents should be included with the shipment. Base64 encoding of the PDF file is returned here.

 
Status
{ "Status": "OK" }

Indicates status of the request.
  • OK
  • ERROR
  • FAIL
 
Messages
{ "Messages": ["Successful"] }

Any errors or warnings returned by the web service will be returned here in a list format.
 
Endpoints
POST
/webship/api/createshipment
Get the carrier compliant shipping label(s) for the selected carrier.
Sample
POST /webship/api/createshipment
{
"ApiKey":"api123",
"TestMode":true,
"AccountNumber":"123456",
"Username":"user@mycompany.com",
"ReturnSampleData":true,
"ShippingDateTime":"2015-08-13T15:59:00",
"FromAddress":{
"Company":"Company 123",
"Contact":"Contact 123",
"Tel":"613‐555‐1234",
"addr1":"1 Main St.",
"CountryCode":"CA",
"PostalCode":"K1K1K1",
"City":"Ottawa",
"Province":"ON"
},
"ToAddress":{
"Company":"Company ABC",
"Contact":"Contact ABC",
"Tel":"613‐555‐1234",
"addr1":"1 Main St",
"CountryCode":"US",
"PostalCode":"90210",
"City":"Beverly Hills",
"Province":"CA",
"Residential":false
},
"LabelSize":"Paper_85x11",
"SelectedCarrier":"UPS",
"SelectedServiceLevel":2,
"BillingOption":"Prepaid",
"BillingAccountNumber":"Required for Collect Shipments",
"EmailNotifications":[
{
"EmailAddress":"user@mycompany.com",
"DeliveryConfirmation":true
}
],
"Reference":"Reference",
"DeliveryComments":"Delivery Comments",
"DocumentsOnly":false,
"SaturdayDelivery":false,
"PackageType":"MyPackage",
"Packages":[
{
"Weight":1.5,
"WeightUnits":"KGS"
},
{
"Weight":3,
"WeightUnits":"LBS",
"Length":1,
"Width":1,
"Height":1,
"DimensionUnits":"INCHES",
"Insurance":100,
"AdditionalHandling":true,
"SignatureOption":"SignatureRequired"
}
],
"CommercialInvoice":
{
"GeneralDescriptionOfGoods":"Promotional Material Given out Free of Charge",
"ReasonForExport":4,
"Remarks":"Promotional Material Given out Free of Charge",
"CurrencyCode":"CAD",
"Parts":[
{
"Qty":"500",
"QtyUnits":"Each",
"DetailedDescription":"Promotional Key Chains with Company logo given out free of charge ‐ Unsolicited gift",
"CountryOfOrigin":"CN",
"UnitValue":"0.5000"
}
]
}
}

Response:
{
"ShipmentDetails":{
"SecureshipTrackingNo":"secureshiptracking",
"CarrierTrackingNos":[
"carrierTrackingNo1",
"carrierTrackingNo2"
],
"ShippingDocuments":""
},
"Status":"OK",
"Messages":[ "Successful"]
}
 
Sample using CURL
> curl -X POST https://secureship.ca/webship/api/createshipment --data "[insert your json here]"
>
or
> curl -X POST https://secureship.ca/webship/api/createshipment --data @datafile.json
>
Sample in .NET using WebClient
string jsonData = "...";
WebClient request = new WebClient();
request.Encoding = System.Text.Encoding.UTF8;
var results = request.UploadString(new Uri(CREATESHIPMENT_URL), "POST",jsonData);
System.Diagnostics.Debug.WriteLine(results);
Sample in .NET using HttpWebRequest
// Create the web request
HttpWebRequest request = WebRequest.Create(CREATESHIPMENT_URL) as HttpWebRequest;

// Set type to POST
request.Method = "POST";
request.ContentType = "application/x‐www‐form‐urlencoded";

System.Text.StringBuilder data = new System.Text.StringBuilder();
data.Append(System.IO.File.ReadAllText(@"yourfile.json"));

byte[] byteData = System.Text.UTF8Encoding.UTF8.GetBytes(data.ToString());

// Set the content length in the request headers
request.ContentLength = byteData.Length;

// Write data
using (System.IO.Stream postStream = request.GetRequestStream())
{
postStream.Write(byteData, 0, byteData.Length);
}

// Get response
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
{
// Get the response stream
System.IO.StreamReader reader = new
System.IO.StreamReader(response.GetResponseStream());

// Console application output
System.Diagnostics.Debug.WriteLine(reader.ReadToEnd());
}
Sample using PHP
<?php
$username = ' ';
$apikey = ' ';
$json = “insert your json code here”;
$ch = curl_init($CREATESHIPMENT_URL);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "$json");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Basic " .
base64_encode($username . ":" . $apikey)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$output = curl_exec($ch);
echo $output;
curl_close($ch);
?>




Click for the BBB Business Review of Secureship, an Online Shipping Broker in Ottawa ON
© 2007-2021 Secureship Inc. - An Easier Way to Ship