API

The JSON API that will allow you to get your rates...everywhere.

Getting Started

Need Help? We're here.

If you have any questions at any step of the integration process, let us know, we're here to help! Send us an email at developers@flagshipcompany.com

Authentication

You will need to create a TOKEN from the SmartShip Authentication Gateway. Your regular FlagShip credentials can be used on this page to generate an app-specific TOKEN.

NOTE:

The Token is one way encrypted. If you lose it, there is no way to get it back - you'll need to get a new one.

The API is stateless and requires authentication for every request.

HTTPS only

HTTPS is required to connect to the API and furthermore it is rate-limited to 1 request per second, with bursts of 5 allowed. Exceeding this limit will return a 429 - Too many requests error.

How to create a request

Once you have generated a new token, you need to create a special header for the API to accept the request.

x-smartship-token should contain the TOKEN value obtained when generating the token.

To submit a valid request, your headers should look like this: 

GET /test/ HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCVM0pCgB7QB5cp-DlnIo3TA77xZE_yqWqwnia1pGc
Content-Type: application/json
The Token header must be present for all requests.

FlagShip REST PHP Client Library

One quick way to integrate FlagShip API into your PHP App.
To get started with FlagShip API SDK: learn more.

NOTE:

This library is fully compatible to all entry-points specified in this document.

Responses

The response HTTP codes are important. They follow the REST principles, notably:

  • 200 OK
  • 201 Created - The request created the ressource on our server.
  • 204 No Content - Means the query executed successfuly but we have no content in the body.
  • 206 Partial Content - Used for partial quotes, e.g: UPS failed but we have an answer for Purolator and FedEx.
  • 400 Bad Request - This means there is a problem with the request you submitted. Usually the explaination is in the body.
  • 401 Unauthorized - There is a problem with the identification.
  • 403 Forbidden - Means you are identified properly but have no access to the ressource.
  • 409 Conflict - Means you cannot do this operation at this time for this request.
  • 412 Precondition Failed - Means that while the request is valid, your account lacks sufficient funds to proceed with this shipment.
  • 500 Internal Server Error - Means FlagShip API crashed. A error message should accompany this code.
  • 502 Bad Gateway - Means one of our partners' API returned an error response.
  • 503 Service Unavailable - Means we temporarily down for maintenance.

Errors

For 4xx and 5xx you will receive different errors type. In case of a 400 the error will show where the problem occurs, e.g : 

{
    "content": null,
    "errors": {
        "from": {
            "country": ["This value is not valid."]
        }
    },
    "notices": null
}
In this case for example, the "country" field in the "from" section of your request has an error.

In the case of a courier errors (502) it will show which courier, with an array of all the errors returned by the courier.: 
{
    "content": null,
    "errors": {
        "ups": ["The maximum per package weight for the selected service from the selected country is 150.00 pounds."],
        "fedex": ["There are no valid services available. "],
        "purolator": ["The weight of an individual piece cannot exceed 150 lb"]
    },
    "notices": null
}

NOTE:

In the examples both in requests and responses, arrays are truncated with the following: 

"..."
These are to keep the documentation succinct and are of course not part of them.

Shipping

This resource allows to shop rates, confirm, list and cancel shipments

Create a Quote

This will allow to get rates for packages, courier packs or courier letters going from Canada to anywhere in the world.

Action

[POST] /ship/rates

Request

POST /ship/rates HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "from": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "to": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "packages": {
        "items": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description"
            },
            "..."
        ],
        "units": "imperial",
        "type": "package",
        "content": "goods"
    },
    "payment": {
        "payer": "F"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "description": "Children books"
        },
        "cod": {
            "method": "check",
            "payable_to": "Bob",
            "receiver_phone": "18663208383",
            "amount": 123.45,
            "currency": "CAD"
        },
        "signature_required": false,
        "saturday_delivery": false,
        "shipping_date": "2015-12-11",
        "reference": "123 test",
        "driver_instructions": "Doorbell broken, knock on door",
        "address_correction": false,
        "return_documents_as": "url",
        "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
    }
}

Details

Name Example Value
from (Address)
Where the shipment is originating from
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
Where the shipment is going
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
packages (Packages)
What are you shipping?
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
payment (enum-objects)
Who is paying for this shipment?
Flagship Payment
Name Example Value
payer (string)
F - your Flagship Account, the most likely. 		F
Collect Payment
Name Example Value
payer (string)
C - Collect; the shipment will be billed on the receiver's account. 		C
payer_account (string)
The account of the payer with the selected courier. 		123456
Third Party Payment
Name Example Value
payer (string)
T - A Third Party will be charged for the shipment. 		T
payer_account (string)
The account of the payer with the selected courier. 		123456
payer_tp_address (Address)
The address of the third party payer
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
The options for this shipment. None of the options are required.
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com

Response

200 OK

{
    "content": [
        {
            "price": {
                "charges": {
                    "freight": 123.45,
                    "signature_required": 123.45,
                    "insurance": 123.45,
                    "multipiece": 123.45
                },
                "adjustments": null,
                "subtotal": 123.45,
                "total": 123.45,
                "taxes": {
                    "gst": 123.45,
                    "qst": 123.45,
                    "pst": 123.45,
                    "hst": 123.45
                }
            },
            "service": {
                "flagship_code": "expressEarlyAm",
                "courier_code": "FIRST_OVERNIGHT",
                "courier_desc": "First Overnight",
                "courier_name": "FedEx",
                "transit_time": 1,
                "estimated_delivery_date": "2015-12-03 23:30:00"
            }
        },
        "..."
    ],
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (array)
Name Example Value
price (Price Structure)
Price breakdown of the service
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (null)
Adjustments charged in addition to the original charges by the courier
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
service (Service)
The type of Courier service available
Name Example Value
flagship_code (string)
The internal flagship code for that courier's service 		expressEarlyAm
courier_code (string)
The internal courier code for that service. You will need it to confirm the shipment 		FIRST_OVERNIGHT
courier_desc (string)
The nice name of the service 		First Overnight
courier_name (string)
Name of the courier 		FedEx
transit_time (integer)
The time in transit the shipment will take, in business days. Can be null if not provided by the courier, but it will be present in the response. 		1
estimated_delivery_date (string)
Local date time of when the shipment will be delivered by. Usually is present if transit_time is null. Can be also null 		2015-12-03 23:30:00
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Domestic Confirmation

Confirmation request that is domestic.

Action

[POST] /ship/confirm

Request

POST /ship/confirm HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "from": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "to": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "packages": {
        "items": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description"
            },
            "..."
        ],
        "units": "imperial",
        "type": "package",
        "content": "goods"
    },
    "payment": {
        "payer": "F"
    },
    "service": {
        "courier_name": "fedex",
        "courier_code": "FIRST_OVERNIGHT"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "description": "Children books"
        },
        "cod": {
            "method": "check",
            "payable_to": "Bob",
            "receiver_phone": "18663208383",
            "amount": 123.45,
            "currency": "CAD"
        },
        "signature_required": false,
        "saturday_delivery": false,
        "shipping_date": "2015-12-11",
        "reference": "123 test",
        "driver_instructions": "Doorbell broken, knock on door",
        "address_correction": false,
        "return_documents_as": "url",
        "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
    }
}

Details

Name Example Value
from (Address)
Where the shipment is originating from
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
Where the shipment is going
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
packages (Packages)
What are you shipping?
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
payment (enum-objects)
Who is paying for this shipment?
Flagship Payment
Name Example Value
payer (string)
F - your Flagship Account, the most likely. 		F
Collect Payment
Name Example Value
payer (string)
C - Collect; the shipment will be billed on the receiver's account. 		C
payer_account (string)
The account of the payer with the selected courier. 		123456
Third Party Payment
Name Example Value
payer (string)
T - A Third Party will be charged for the shipment. 		T
payer_account (string)
The account of the payer with the selected courier. 		123456
payer_tp_address (Address)
The address of the third party payer
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
service (Service)
What courier and courier service are we using?
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
options (Options)
The options for this shipment. None of the options are required.
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com

Response

201 CREATED

{
    "content": {
        "shipment_id": "201012221",
        "tracking_number": "329018797020",
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": null,
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "service": {
            "flagship_code": "expressEarlyAm",
            "courier_code": "FIRST_OVERNIGHT",
            "courier_desc": "First Overnight",
            "courier_name": "FedEx",
            "transit_time": 1,
            "estimated_delivery_date": "2015-12-03 23:30:00"
        },
        "labels": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "packages": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description",
                "pin": "72909513411"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
shipment_id (number)
The shipment id as it appears in the Flagship API 		201012221
tracking_number (string)
The tracking number associated with your shipment. This is a courier generated value 		329018797020
price (Price Structure)
A price breakdown for the requested service
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (null)
Adjustments charged in addition to the original charges by the courier
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
service (Service)
Details about the service selected
Name Example Value
flagship_code (string)
The internal flagship code for that courier's service 		expressEarlyAm
courier_code (string)
The internal courier code for that service. You will need it to confirm the shipment 		FIRST_OVERNIGHT
courier_desc (string)
The nice name of the service 		First Overnight
courier_name (string)
Name of the courier 		FedEx
transit_time (integer)
The time in transit the shipment will take, in business days. Can be null if not provided by the courier, but it will be present in the response. 		1
estimated_delivery_date (string)
Local date time of when the shipment will be delivered by. Usually is present if transit_time is null. Can be also null 		2015-12-03 23:30:00
labels (Labels)
The shipping labels provided from the courier
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
packages (array)
List of the packages in the shipment, along with the courier-assigned PIN numbers
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
pin (string)
The pin associated to the package. 		72909513411
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

International Confirmation

Confirmation request that is being sent internationally.

Action

[POST] /ship/confirm

Request

POST /ship/confirm HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "from": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "to": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "packages": {
        "items": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description"
            },
            "..."
        ],
        "units": "imperial",
        "type": "package",
        "content": "goods"
    },
    "payment": {
        "payer": "F"
    },
    "service": {
        "courier_name": "fedex",
        "courier_code": "FIRST_OVERNIGHT"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "description": "Children books"
        },
        "cod": {
            "method": "check",
            "payable_to": "Bob",
            "receiver_phone": "18663208383",
            "amount": 123.45,
            "currency": "CAD"
        },
        "signature_required": false,
        "saturday_delivery": false,
        "shipping_date": "2015-12-11",
        "reference": "123 test",
        "driver_instructions": "Doorbell broken, knock on door",
        "address_correction": false,
        "return_documents_as": "url",
        "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
    },
    "sold_to": {
        "sold_to_address": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "duties_payer": "F",
        "duties_payer_account": "1231234",
        "reason_for_export": "P",
        "is_nafta": true
    },
    "inquiry": {
        "company": "ACME inc.",
        "name": "Bob",
        "broker_id": "1",
        "sender_tax_id": "",
        "receiver_tax_id": "",
        "inquiry_phone": "18663208383",
        "inquiry_phone_ext": ""
    },
    "declared_items": {
        "currency": "CAD",
        "ci_items": [
            {
                "product_name": "Cologne",
                "description": "1 bottle of Cologne",
                "HS_code": "",
                "country_of_origin": "CA",
                "quantity": "2",
                "unit_price": "20",
                "unit_weight": "22.50",
                "unit_of_measurement": "kilograms"
            },
            "..."
        ]
    }
}

Details

Name Example Value
from (Address)
Where the shipment is originating from
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
Where the shipment is going
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
Can go anywhere except Iran, Syria and North Korea 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
packages (Packages)
What are you shipping?
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
payment (enum-objects)
Who is paying for this shipment?
Flagship Payment
Name Example Value
payer (string)
F - your Flagship Account, the most likely. 		F
Collect Payment
Name Example Value
payer (string)
C - Collect; the shipment will be billed on the receiver's account. 		C
payer_account (string)
The account of the payer with the selected courier. 		123456
Third Party Payment
Name Example Value
payer (string)
T - A Third Party will be charged for the shipment. 		T
payer_account (string)
The account of the payer with the selected courier. 		123456
payer_tp_address (Address)
The address of the third party payer
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
service (Service)
What courier and courier service are we using?
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
options (Options)
The options for this shipment. None of the options are required.
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com
sold_to (Sold To)
Information about buyer.
Name Example Value
sold_to_address (Address)
Buyer's contact information
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
duties_payer (enum)
Who is paying duties: F (Flagship Account), C (Collect) or T (Third Party) 		F|C|T
duties_payer_account (string)
The duties payer account number. Only applicable if the duties_payer field is set to T 		1231234
reason_for_export (enum)
Reason for export: P (Permanent), T (Temporary), R (Return), G (Gift), S (Sample) 		P|T|R|G|S
is_nafta (boolean)
Whether the shipped goods are NAFTA compliant 		1
inquiry (Inquiry)
Inquiry contact and broker information
Name Example Value
company (string)
ACME inc.
name (string)
Bob
broker_id (number)
Broker ID as assigned by the Flagship API. Refer to the list of brokers that are available 		1
sender_tax_id (string)
The tax ID/business number for your business
receiver_tax_id (string)
The tax ID/business number of the receiver
inquiry_phone (number)
18663208383
inquiry_phone_ext (number)
declared_items (Declared Items)
Details about package contents
Name Example Value
currency (enum)
The currency at which items were valued at 		CAD|USD
ci_items (array)
Detailed description of package contents
Name Example Value
product_name (string)
Cologne
description (string)
1 bottle of Cologne
HS_code (string)
The HS code associated with the product. You can find a list of HS codes or search for them here
country_of_origin (string)
ISO 3166-1 alpha-2 two letter country code 		CA
quantity (number)
The number of said product contained in the shipment 		2
unit_price (float)
The unit value of the product 		20
unit_weight (float)
The unit weight of the product 		22.50
unit_of_measurement (string)
The unit of measurement used for the weight of the product 		kilograms

Response

201 CREATED

{
    "content": {
        "shipment_id": "201012221",
        "tracking_number": "329018797020",
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": null,
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "service": {
            "flagship_code": "expressEarlyAm",
            "courier_code": "FIRST_OVERNIGHT",
            "courier_desc": "First Overnight",
            "courier_name": "FedEx",
            "transit_time": 1,
            "estimated_delivery_date": "2015-12-03 23:30:00"
        },
        "labels": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "packages": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description",
                "pin": "72909513411"
            },
            "..."
        ],
        "documents_only": false,
        "commercial_invoice": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=statement",
        "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
shipment_id (number)
The shipment id as it appears in the Flagship API 		201012221
tracking_number (string)
The tracking number associated with your shipment. This is a courier generated value 		329018797020
price (Price Structure)
A price breakdown for the requested service
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (null)
Adjustments charged in addition to the original charges by the courier
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
service (Service)
Details about the service selected
Name Example Value
flagship_code (string)
The internal flagship code for that courier's service 		expressEarlyAm
courier_code (string)
The internal courier code for that service. You will need it to confirm the shipment 		FIRST_OVERNIGHT
courier_desc (string)
The nice name of the service 		First Overnight
courier_name (string)
Name of the courier 		FedEx
transit_time (integer)
The time in transit the shipment will take, in business days. Can be null if not provided by the courier, but it will be present in the response. 		1
estimated_delivery_date (string)
Local date time of when the shipment will be delivered by. Usually is present if transit_time is null. Can be also null 		2015-12-03 23:30:00
labels (Labels)
The shipping labels provided from the courier
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
packages (array)
List of the packages in the shipment, along with the courier-assigned PIN numbers
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
pin (string)
The pin associated to the package. 		72909513411
documents_only (boolean)
Is this shipment containing documents only? 		false
commercial_invoice (url)
URL for the Flagship generated commercial invoice required for an international shipment 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=statement
nafta_form_url (url)
URL for NAFTA form (Only appears when the field is_nafta of sold_to in the request is true) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Create Record

Creates a record for the shipment in the database, in a "prequoted" status. Can subsequently be used to be confirmed with "Confirm By id" function.

Action

[POST] ship/prepare

Request

POST ship/prepare HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "from": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "to": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "packages": {
        "items": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description"
            },
            "..."
        ],
        "units": "imperial",
        "type": "package",
        "content": "goods"
    },
    "payment": {
        "payer": "F"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "description": "Children books"
        },
        "cod": {
            "method": "check",
            "payable_to": "Bob",
            "receiver_phone": "18663208383",
            "amount": 123.45,
            "currency": "CAD"
        },
        "signature_required": false,
        "saturday_delivery": false,
        "shipping_date": "2015-12-11",
        "reference": "123 test",
        "driver_instructions": "Doorbell broken, knock on door",
        "address_correction": false,
        "return_documents_as": "url",
        "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
    }
}

Details

Name Example Value
from (Address)
Where the shipment is originating from
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
Where the shipment is going
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
packages (Packages)
What are you shipping?
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
payment (enum-objects)
Who is paying for this shipment?
Flagship Payment
Name Example Value
payer (string)
F - your Flagship Account, the most likely. 		F
Collect Payment
Name Example Value
payer (string)
C - Collect; the shipment will be billed on the receiver's account. 		C
payer_account (string)
The account of the payer with the selected courier. 		123456
Third Party Payment
Name Example Value
payer (string)
T - A Third Party will be charged for the shipment. 		T
payer_account (string)
The account of the payer with the selected courier. 		123456
payer_tp_address (Address)
The address of the third party payer
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
The options for this shipment. None of the options are required.
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com

Response

200 OK

{
    "content": {
        "id": 1122341,
        "tracking_number": "1P0075H07633636542",
        "pickup_id": 1122342,
        "status": "prequoted",
        "from": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "to": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "options": {
            "insurance": {
                "value": 123.45,
                "description": "Children books"
            },
            "cod": {
                "method": "check",
                "payable_to": "Bob",
                "receiver_phone": "18663208383",
                "amount": 123.45,
                "currency": "CAD"
            },
            "signature_required": false,
            "saturday_delivery": false,
            "shipping_date": "2015-12-11",
            "reference": "123 test",
            "driver_instructions": "Doorbell broken, knock on door",
            "address_correction": false,
            "return_documents_as": "url",
            "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
        },
        "pickup_details": {
            "confirmation": "2929602E9CP",
            "address": {
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1A1A1",
                "phone": "18663208383",
                "ext": "11",
                "is_commercial": false
            },
            "boxes": 4,
            "weight": 6,
            "units": "imperial",
            "date": "2015-12-31",
            "from": "09:00:00",
            "until": "17:00:00",
            "location": "Reception",
            "instruction": "contain glass product, etc.",
            "is_cancelled": false
        },
        "service": {
            "courier_name": "fedex",
            "courier_code": "FIRST_OVERNIGHT"
        },
        "packages": {
            "items": [
                {
                    "width": 22,
                    "height": 22,
                    "length": 22,
                    "weight": 22,
                    "description": "Item description"
                },
                "..."
            ],
            "units": "imperial",
            "type": "package",
            "content": "goods"
        },
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": {
                "fuel_surchage": 123.45
            },
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "brokerage_details": {
            "description": "Chocolate covered gift box",
            "items": [
                {
                    "country_of_origin": "CA",
                    "description": "Sweet Biscuits",
                    "duty_value": 3074.67,
                    "class_number": "1905312900",
                    "duty": 0,
                    "excise_tax_rate": 0,
                    "excise_tax_amount": 0,
                    "gst_hst_rate": 0,
                    "gst_hst_amount": 0,
                    "tax_value": 0,
                    "sima_assess": 0,
                    "total_customs": 0
                },
                "..."
            ],
            "total_duty": 3074.67,
            "currency": "CAD",
            "billed_weight": 6,
            "weight_units": "imperial",
            "package_count": 4,
            "invoice_number": "1234567"
        },
        "documents": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf",
        "transit_details": [
            {
                "last_update": "2017-06-09 23:00:00",
                "status": "D",
                "message": "Shipment delivered to YALE via GUELPH, ON depot"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
id (integer)
The shipment id 		1122341
tracking_number (string)
The tracking number 		1P0075H07633636542
pickup_id (integer)
The pickup id is associated to the shipment 		1122342
status (enum)
The shipment status 		prequoted|quoted|predispatched|dispatched|manifested|cancelled
from (Address)
The from address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
The to address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com
pickup_details (Pickup Details)
The Pickup information
Name Example Value
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (string)
The shipment unit (imperia|metric) 		imperial
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		09:00:00
until (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		17:00:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
is_cancelled (boolean)
can be 0|1 		false
service (Service)
The service
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
packages (Packages)
The packages contained in the shipment
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
price (Invoiced Price Structure)
The list of charges for the shipment
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (Shipment Adjustments)
Adjustments charged in addition to the original charges by the courier
Name Example Value
fuel_surchage (decimal)
Cost of fuel 		123.45
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
brokerage_details (Brokerage Details)
Brokerage information
Name Example Value
description (string)
Item description 		Chocolate covered gift box
items (array)
Array of all the items for that shipment
Name Example Value
country_of_origin (string)
ISO 3166-1 alpha-2 two letter country code 		CA
description (string)
description of the item 		Sweet Biscuits
duty_value (decimal)
Duty value 		3074.67
class_number (string)
Class number 		1905312900
duty (decimal)
Duty amount 		0
excise_tax_rate (integer)
Excise tax rate 		0
excise_tax_amount (decimal)
Excise tax amount 		0
gst_hst_rate (integer)
GST HST rate 		0
gst_hst_amount (decimal)
GST HST amount 		0
tax_value (decimal)
Tax value 		0
sima_assess (integer)
Antidumping and countervailing duties are assessed against subject goods that originate in, or are exported from a specific country 		0
total_customs (decimal)
Total customs 		0
total_duty (decimal)
Total duty 		3074.67
currency (enum)
The currency at which items were valued at 		CAD|USD
billed_weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
weight_units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
package_count (integer)
Package counts 		4
invoice_number (string)
The invoice number 		1234567
documents (Labels)
The shipping labels provided by the courier and commercial invoice, if applicable
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
nafta_form_url (url)
URL for NAFTA form (Only applicable to shipments destined to NAFTA countries with goods that for the reduced or eliminated duties allowed under NAFTA) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
transit_details (array)
The transit details for shipment
Name Example Value
last_update (string)
Courier update for shipment. 		2017-06-09 23:00:00
status (string)
The shipment status 		D
message (string)
Status description for the shipment. 		Shipment delivered to YALE via GUELPH, ON depot
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Find by id

Get a shipment's details by id.

Action

[GET] /ship/shipments/{shipmentId}

Request

GET /ship/shipments/{shipmentId} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK

{
    "content": {
        "id": 1122341,
        "tracking_number": "1P0075H07633636542",
        "pickup_id": 1122342,
        "status": "prequoted",
        "from": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "to": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "options": {
            "insurance": {
                "value": 123.45,
                "description": "Children books"
            },
            "cod": {
                "method": "check",
                "payable_to": "Bob",
                "receiver_phone": "18663208383",
                "amount": 123.45,
                "currency": "CAD"
            },
            "signature_required": false,
            "saturday_delivery": false,
            "shipping_date": "2015-12-11",
            "reference": "123 test",
            "driver_instructions": "Doorbell broken, knock on door",
            "address_correction": false,
            "return_documents_as": "url",
            "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
        },
        "pickup_details": {
            "confirmation": "2929602E9CP",
            "address": {
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1A1A1",
                "phone": "18663208383",
                "ext": "11",
                "is_commercial": false
            },
            "boxes": 4,
            "weight": 6,
            "units": "imperial",
            "date": "2015-12-31",
            "from": "09:00:00",
            "until": "17:00:00",
            "location": "Reception",
            "instruction": "contain glass product, etc.",
            "is_cancelled": false
        },
        "service": {
            "courier_name": "fedex",
            "courier_code": "FIRST_OVERNIGHT"
        },
        "packages": {
            "items": [
                {
                    "width": 22,
                    "height": 22,
                    "length": 22,
                    "weight": 22,
                    "description": "Item description"
                },
                "..."
            ],
            "units": "imperial",
            "type": "package",
            "content": "goods"
        },
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": {
                "fuel_surchage": 123.45
            },
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "brokerage_details": {
            "description": "Chocolate covered gift box",
            "items": [
                {
                    "country_of_origin": "CA",
                    "description": "Sweet Biscuits",
                    "duty_value": 3074.67,
                    "class_number": "1905312900",
                    "duty": 0,
                    "excise_tax_rate": 0,
                    "excise_tax_amount": 0,
                    "gst_hst_rate": 0,
                    "gst_hst_amount": 0,
                    "tax_value": 0,
                    "sima_assess": 0,
                    "total_customs": 0
                },
                "..."
            ],
            "total_duty": 3074.67,
            "currency": "CAD",
            "billed_weight": 6,
            "weight_units": "imperial",
            "package_count": 4,
            "invoice_number": "1234567"
        },
        "documents": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf",
        "transit_details": [
            {
                "last_update": "2017-06-09 23:00:00",
                "status": "D",
                "message": "Shipment delivered to YALE via GUELPH, ON depot"
            },
            "..."
        ],
        "invoice_details": {
            "201712-52": {
                "cycle_id": "201712-52",
                "invoice_id": "123",
                "originals": {
                    "freight": {
                        "reason": "special handling",
                        "amount": 123.45
                    },
                    "0": "..."
                },
                "adjustements": {
                    "freight": {
                        "reason": "special handling",
                        "amount": 123.45
                    },
                    "0": "..."
                },
                "credits": {
                    "freight": {
                        "reason": "special handling",
                        "amount": 123.45
                    },
                    "0": "..."
                },
                "payments": {
                    "freight": {
                        "reason": "special handling",
                        "amount": 123.45
                    },
                    "0": "..."
                }
            },
            "0": "..."
        }
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
id (integer)
The shipment id 		1122341
tracking_number (string)
The tracking number 		1P0075H07633636542
pickup_id (integer)
The pickup id is associated to the shipment 		1122342
status (enum)
The shipment status 		prequoted|quoted|predispatched|dispatched|manifested|cancelled
from (Address)
The from address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
The to address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com
pickup_details (Pickup Details)
The Pickup information
Name Example Value
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (string)
The shipment unit (imperia|metric) 		imperial
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		09:00:00
until (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		17:00:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
is_cancelled (boolean)
can be 0|1 		false
service (Service)
The service
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
packages (Packages)
The packages contained in the shipment
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
price (Invoiced Price Structure)
The list of charges for the shipment
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (Shipment Adjustments)
Adjustments charged in addition to the original charges by the courier
Name Example Value
fuel_surchage (decimal)
Cost of fuel 		123.45
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
brokerage_details (Brokerage Details)
Brokerage information
Name Example Value
description (string)
Item description 		Chocolate covered gift box
items (array)
Array of all the items for that shipment
Name Example Value
country_of_origin (string)
ISO 3166-1 alpha-2 two letter country code 		CA
description (string)
description of the item 		Sweet Biscuits
duty_value (decimal)
Duty value 		3074.67
class_number (string)
Class number 		1905312900
duty (decimal)
Duty amount 		0
excise_tax_rate (integer)
Excise tax rate 		0
excise_tax_amount (decimal)
Excise tax amount 		0
gst_hst_rate (integer)
GST HST rate 		0
gst_hst_amount (decimal)
GST HST amount 		0
tax_value (decimal)
Tax value 		0
sima_assess (integer)
Antidumping and countervailing duties are assessed against subject goods that originate in, or are exported from a specific country 		0
total_customs (decimal)
Total customs 		0
total_duty (decimal)
Total duty 		3074.67
currency (enum)
The currency at which items were valued at 		CAD|USD
billed_weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
weight_units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
package_count (integer)
Package counts 		4
invoice_number (string)
The invoice number 		1234567
documents (Labels)
The shipping labels provided by the courier and commercial invoice, if applicable
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
nafta_form_url (url)
URL for NAFTA form (Only applicable to shipments destined to NAFTA countries with goods that for the reduced or eliminated duties allowed under NAFTA) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
transit_details (array)
The transit details for shipment
Name Example Value
last_update (string)
Courier update for shipment. 		2017-06-09 23:00:00
status (string)
The shipment status 		D
message (string)
Status description for the shipment. 		Shipment delivered to YALE via GUELPH, ON depot
invoice_details (multi-object)
The breakdown of all invoiced charges for this shipment
Name Example Value
cycle_id (string)
The cycle id for where the charges have been invoiced 		201712-52
invoice_id (integer)
The invoice id for where the charges have been invoiced 		123
originals (multi-object)
The breakdown of charges for when the shipment was confirmed. Includes freight charges and any additional surcharges.
Name Example Value
reason (string)
The reason of that charge 		special handling
amount (decimal)
The total amount for that charge 		123.45
adjustements (multi-object)
The breakdown of adjustements this shipment was charged for when it was invoiced.
Name Example Value
reason (string)
The reason of that charge 		special handling
amount (decimal)
The total amount for that charge 		123.45
credits (multi-object)
Any credits on existing charges.
Name Example Value
reason (string)
The reason of that charge 		special handling
amount (decimal)
The total amount for that charge 		123.45
payments (multi-object)
Any payments or refunds applied to the shipment.
Name Example Value
reason (string)
The reason of that charge 		special handling
amount (decimal)
The total amount for that charge 		123.45
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Modify

Update the shipment identified by id field from the request uri

Action

[PUT] ship/shipments/{id}

Request

PUT ship/shipments/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "from": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "to": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "packages": {
        "items": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description"
            },
            "..."
        ],
        "units": "imperial",
        "type": "package",
        "content": "goods"
    },
    "payment": {
        "payer": "F"
    },
    "service": {
        "courier_name": "fedex",
        "courier_code": "FIRST_OVERNIGHT"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "description": "Children books"
        },
        "cod": {
            "method": "check",
            "payable_to": "Bob",
            "receiver_phone": "18663208383",
            "amount": 123.45,
            "currency": "CAD"
        },
        "signature_required": false,
        "saturday_delivery": false,
        "shipping_date": "2015-12-11",
        "reference": "123 test",
        "driver_instructions": "Doorbell broken, knock on door",
        "address_correction": false,
        "return_documents_as": "url",
        "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
    }
}

Details

Name Example Value
from (Address)
Where the shipment is originating from
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
Where the shipment is going
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
packages (Packages)
What are you shipping?
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
payment (enum-objects)
Who is paying for this shipment?
Flagship Payment
Name Example Value
payer (string)
F - your Flagship Account, the most likely. 		F
Collect Payment
Name Example Value
payer (string)
C - Collect; the shipment will be billed on the receiver's account. 		C
payer_account (string)
The account of the payer with the selected courier. 		123456
Third Party Payment
Name Example Value
payer (string)
T - A Third Party will be charged for the shipment. 		T
payer_account (string)
The account of the payer with the selected courier. 		123456
payer_tp_address (Address)
The address of the third party payer
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
service (Service)
What courier and courier service are we using?
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
options (Options)
The options for this shipment. None of the options are required.
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com

Response

200 OK

{
    "content": {
        "id": 1122341,
        "tracking_number": "1P0075H07633636542",
        "pickup_id": 1122342,
        "status": "prequoted",
        "from": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "to": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "options": {
            "insurance": {
                "value": 123.45,
                "description": "Children books"
            },
            "cod": {
                "method": "check",
                "payable_to": "Bob",
                "receiver_phone": "18663208383",
                "amount": 123.45,
                "currency": "CAD"
            },
            "signature_required": false,
            "saturday_delivery": false,
            "shipping_date": "2015-12-11",
            "reference": "123 test",
            "driver_instructions": "Doorbell broken, knock on door",
            "address_correction": false,
            "return_documents_as": "url",
            "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
        },
        "pickup_details": {
            "confirmation": "2929602E9CP",
            "address": {
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1A1A1",
                "phone": "18663208383",
                "ext": "11",
                "is_commercial": false
            },
            "boxes": 4,
            "weight": 6,
            "units": "imperial",
            "date": "2015-12-31",
            "from": "09:00:00",
            "until": "17:00:00",
            "location": "Reception",
            "instruction": "contain glass product, etc.",
            "is_cancelled": false
        },
        "service": {
            "courier_name": "fedex",
            "courier_code": "FIRST_OVERNIGHT"
        },
        "packages": {
            "items": [
                {
                    "width": 22,
                    "height": 22,
                    "length": 22,
                    "weight": 22,
                    "description": "Item description"
                },
                "..."
            ],
            "units": "imperial",
            "type": "package",
            "content": "goods"
        },
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": {
                "fuel_surchage": 123.45
            },
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "brokerage_details": {
            "description": "Chocolate covered gift box",
            "items": [
                {
                    "country_of_origin": "CA",
                    "description": "Sweet Biscuits",
                    "duty_value": 3074.67,
                    "class_number": "1905312900",
                    "duty": 0,
                    "excise_tax_rate": 0,
                    "excise_tax_amount": 0,
                    "gst_hst_rate": 0,
                    "gst_hst_amount": 0,
                    "tax_value": 0,
                    "sima_assess": 0,
                    "total_customs": 0
                },
                "..."
            ],
            "total_duty": 3074.67,
            "currency": "CAD",
            "billed_weight": 6,
            "weight_units": "imperial",
            "package_count": 4,
            "invoice_number": "1234567"
        },
        "documents": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf",
        "transit_details": [
            {
                "last_update": "2017-06-09 23:00:00",
                "status": "D",
                "message": "Shipment delivered to YALE via GUELPH, ON depot"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
id (integer)
The shipment id 		1122341
tracking_number (string)
The tracking number 		1P0075H07633636542
pickup_id (integer)
The pickup id is associated to the shipment 		1122342
status (enum)
The shipment status 		prequoted|quoted|predispatched|dispatched|manifested|cancelled
from (Address)
The from address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
The to address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com
pickup_details (Pickup Details)
The Pickup information
Name Example Value
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (string)
The shipment unit (imperia|metric) 		imperial
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		09:00:00
until (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		17:00:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
is_cancelled (boolean)
can be 0|1 		false
service (Service)
The service
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
packages (Packages)
The packages contained in the shipment
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
price (Invoiced Price Structure)
The list of charges for the shipment
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (Shipment Adjustments)
Adjustments charged in addition to the original charges by the courier
Name Example Value
fuel_surchage (decimal)
Cost of fuel 		123.45
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
brokerage_details (Brokerage Details)
Brokerage information
Name Example Value
description (string)
Item description 		Chocolate covered gift box
items (array)
Array of all the items for that shipment
Name Example Value
country_of_origin (string)
ISO 3166-1 alpha-2 two letter country code 		CA
description (string)
description of the item 		Sweet Biscuits
duty_value (decimal)
Duty value 		3074.67
class_number (string)
Class number 		1905312900
duty (decimal)
Duty amount 		0
excise_tax_rate (integer)
Excise tax rate 		0
excise_tax_amount (decimal)
Excise tax amount 		0
gst_hst_rate (integer)
GST HST rate 		0
gst_hst_amount (decimal)
GST HST amount 		0
tax_value (decimal)
Tax value 		0
sima_assess (integer)
Antidumping and countervailing duties are assessed against subject goods that originate in, or are exported from a specific country 		0
total_customs (decimal)
Total customs 		0
total_duty (decimal)
Total duty 		3074.67
currency (enum)
The currency at which items were valued at 		CAD|USD
billed_weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
weight_units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
package_count (integer)
Package counts 		4
invoice_number (string)
The invoice number 		1234567
documents (Labels)
The shipping labels provided by the courier and commercial invoice, if applicable
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
nafta_form_url (url)
URL for NAFTA form (Only applicable to shipments destined to NAFTA countries with goods that for the reduced or eliminated duties allowed under NAFTA) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
transit_details (array)
The transit details for shipment
Name Example Value
last_update (string)
Courier update for shipment. 		2017-06-09 23:00:00
status (string)
The shipment status 		D
message (string)
Status description for the shipment. 		Shipment delivered to YALE via GUELPH, ON depot
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Confirm by id

Confirms the shipment identified by id field from the request uri

Action

[PUT] /ship/{Id}/confirm

Request

PUT /ship/{Id}/confirm HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json

Response

200 OK

{
    "content": {
        "shipment_id": "201012221",
        "tracking_number": "329018797020",
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": null,
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "service": {
            "flagship_code": "expressEarlyAm",
            "courier_code": "FIRST_OVERNIGHT",
            "courier_desc": "First Overnight",
            "courier_name": "FedEx",
            "transit_time": 1,
            "estimated_delivery_date": "2015-12-03 23:30:00"
        },
        "labels": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "packages": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description",
                "pin": "72909513411"
            },
            "..."
        ],
        "documents_only": false,
        "commercial_invoice": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=statement",
        "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
shipment_id (number)
The shipment id as it appears in the Flagship API 		201012221
tracking_number (string)
The tracking number associated with your shipment. This is a courier generated value 		329018797020
price (Price Structure)
A price breakdown for the requested service
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (null)
Adjustments charged in addition to the original charges by the courier
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
service (Service)
Details about the service selected
Name Example Value
flagship_code (string)
The internal flagship code for that courier's service 		expressEarlyAm
courier_code (string)
The internal courier code for that service. You will need it to confirm the shipment 		FIRST_OVERNIGHT
courier_desc (string)
The nice name of the service 		First Overnight
courier_name (string)
Name of the courier 		FedEx
transit_time (integer)
The time in transit the shipment will take, in business days. Can be null if not provided by the courier, but it will be present in the response. 		1
estimated_delivery_date (string)
Local date time of when the shipment will be delivered by. Usually is present if transit_time is null. Can be also null 		2015-12-03 23:30:00
labels (Labels)
The shipping labels provided from the courier
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
packages (array)
List of the packages in the shipment, along with the courier-assigned PIN numbers
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
pin (string)
The pin associated to the package. 		72909513411
documents_only (boolean)
Is this shipment containing documents only? 		false
commercial_invoice (url)
URL for the Flagship generated commercial invoice required for an international shipment 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=statement
nafta_form_url (url)
URL for NAFTA form (Only appears when the field is_nafta of sold_to in the request is true) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Cancel

Cancel the shipment identified by its shipment id field from the request uri

Action

[DELETE] /ship/shipments/{id}

Request

DELETE /ship/shipments/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json

Response

204 NO CONTENT

List

Get the list of shipments

Action

[GET] /ship/shipments

URI Parameters

Parameter Value Description
courier ups Filter by the courier. Options are ups|dhl|fedex|purolator|canpar
status dispatched Filter by the shipment status. Options are prequoted|quoted|predispatched|dispatched|manifested|cancelled
reference Some reference Filter by the shipment reference
tracking_number 1234321445 The shipment's tracking number.
package_pin 112234 A shipment's package pin
page 2 The page wanted in the list of results
limit 23 The number of results wanted per page. Maximum 50.

Request

GET /ship/shipments HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK

{
    "content": {
        "records": [
            {
                "id": 1122341,
                "tracking_number": "1P0075H07633636542",
                "pickup_id": 1122342,
                "status": "prequoted",
                "from": {
                    "name": "ACME inc.",
                    "attn": "Bob",
                    "address": "123 Main Street",
                    "suite": "227",
                    "city": "Montreal",
                    "country": "CA",
                    "state": "QC",
                    "postal_code": "A1A1A1",
                    "phone": "18663208383",
                    "ext": "123",
                    "department": "Reception",
                    "is_commercial": true
                },
                "to": {
                    "name": "ACME inc.",
                    "attn": "Bob",
                    "address": "123 Main Street",
                    "suite": "227",
                    "city": "Montreal",
                    "country": "CA",
                    "state": "QC",
                    "postal_code": "A1A1A1",
                    "phone": "18663208383",
                    "ext": "123",
                    "department": "Reception",
                    "is_commercial": true
                },
                "options": {
                    "insurance": {
                        "value": 123.45,
                        "description": "Children books"
                    },
                    "cod": {
                        "method": "check",
                        "payable_to": "Bob",
                        "receiver_phone": "18663208383",
                        "amount": 123.45,
                        "currency": "CAD"
                    },
                    "signature_required": false,
                    "saturday_delivery": false,
                    "shipping_date": "2015-12-11",
                    "reference": "123 test",
                    "driver_instructions": "Doorbell broken, knock on door",
                    "address_correction": false,
                    "return_documents_as": "url",
                    "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
                },
                "pickup_details": {
                    "confirmation": "2929602E9CP",
                    "address": {
                        "name": "ACME inc.",
                        "attn": "Bob",
                        "address": "123 Main Street",
                        "suite": "227",
                        "city": "Montreal",
                        "country": "CA",
                        "state": "QC",
                        "postal_code": "A1A1A1",
                        "phone": "18663208383",
                        "ext": "11",
                        "is_commercial": false
                    },
                    "boxes": 4,
                    "weight": 6,
                    "units": "imperial",
                    "date": "2015-12-31",
                    "from": "09:00:00",
                    "until": "17:00:00",
                    "location": "Reception",
                    "instruction": "contain glass product, etc.",
                    "is_cancelled": false
                },
                "service": {
                    "courier_name": "fedex",
                    "courier_code": "FIRST_OVERNIGHT"
                },
                "packages": {
                    "items": [
                        {
                            "width": 22,
                            "height": 22,
                            "length": 22,
                            "weight": 22,
                            "description": "Item description"
                        },
                        "..."
                    ],
                    "units": "imperial",
                    "type": "package",
                    "content": "goods"
                },
                "price": {
                    "charges": {
                        "freight": 123.45,
                        "signature_required": 123.45,
                        "insurance": 123.45,
                        "multipiece": 123.45
                    },
                    "adjustments": {
                        "fuel_surchage": 123.45
                    },
                    "subtotal": 123.45,
                    "total": 123.45,
                    "taxes": {
                        "gst": 123.45,
                        "qst": 123.45,
                        "pst": 123.45,
                        "hst": 123.45
                    }
                },
                "brokerage_details": {
                    "description": "Chocolate covered gift box",
                    "items": [
                        {
                            "country_of_origin": "CA",
                            "description": "Sweet Biscuits",
                            "duty_value": 3074.67,
                            "class_number": "1905312900",
                            "duty": 0,
                            "excise_tax_rate": 0,
                            "excise_tax_amount": 0,
                            "gst_hst_rate": 0,
                            "gst_hst_amount": 0,
                            "tax_value": 0,
                            "sima_assess": 0,
                            "total_customs": 0
                        },
                        "..."
                    ],
                    "total_duty": 3074.67,
                    "currency": "CAD",
                    "billed_weight": 6,
                    "weight_units": "imperial",
                    "package_count": 4,
                    "invoice_number": "1234567"
                },
                "documents": {
                    "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
                    "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
                },
                "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf",
                "transit_details": [
                    {
                        "last_update": "2017-06-09 23:00:00",
                        "status": "D",
                        "message": "Shipment delivered to YALE via GUELPH, ON depot"
                    },
                    "..."
                ]
            },
            "..."
        ],
        "current_page": 2,
        "max_per_page": 20,
        "nb_of_pages": 7,
        "nb_of_records": 131
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment List)
Name Example Value
records (array)
Array with the shipments belonging to the requested page
Name Example Value
id (integer)
The shipment id 		1122341
tracking_number (string)
The tracking number 		1P0075H07633636542
pickup_id (integer)
The pickup id is associated to the shipment 		1122342
status (enum)
The shipment status 		prequoted|quoted|predispatched|dispatched|manifested|cancelled
from (Address)
The from address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
The to address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com
pickup_details (Pickup Details)
The Pickup information
Name Example Value
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (string)
The shipment unit (imperia|metric) 		imperial
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		09:00:00
until (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		17:00:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
is_cancelled (boolean)
can be 0|1 		false
service (Service)
The service
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
packages (Packages)
The packages contained in the shipment
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
price (Invoiced Price Structure)
The list of charges for the shipment
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (Shipment Adjustments)
Adjustments charged in addition to the original charges by the courier
Name Example Value
fuel_surchage (decimal)
Cost of fuel 		123.45
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
brokerage_details (Brokerage Details)
Brokerage information
Name Example Value
description (string)
Item description 		Chocolate covered gift box
items (array)
Array of all the items for that shipment
Name Example Value
country_of_origin (string)
ISO 3166-1 alpha-2 two letter country code 		CA
description (string)
description of the item 		Sweet Biscuits
duty_value (decimal)
Duty value 		3074.67
class_number (string)
Class number 		1905312900
duty (decimal)
Duty amount 		0
excise_tax_rate (integer)
Excise tax rate 		0
excise_tax_amount (decimal)
Excise tax amount 		0
gst_hst_rate (integer)
GST HST rate 		0
gst_hst_amount (decimal)
GST HST amount 		0
tax_value (decimal)
Tax value 		0
sima_assess (integer)
Antidumping and countervailing duties are assessed against subject goods that originate in, or are exported from a specific country 		0
total_customs (decimal)
Total customs 		0
total_duty (decimal)
Total duty 		3074.67
currency (enum)
The currency at which items were valued at 		CAD|USD
billed_weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
weight_units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
package_count (integer)
Package counts 		4
invoice_number (string)
The invoice number 		1234567
documents (Labels)
The shipping labels provided by the courier and commercial invoice, if applicable
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
nafta_form_url (url)
URL for NAFTA form (Only applicable to shipments destined to NAFTA countries with goods that for the reduced or eliminated duties allowed under NAFTA) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
transit_details (array)
The transit details for shipment
Name Example Value
last_update (string)
Courier update for shipment. 		2017-06-09 23:00:00
status (string)
The shipment status 		D
message (string)
Status description for the shipment. 		Shipment delivered to YALE via GUELPH, ON depot
current_page (integer)
The page the returned records belong to 		2
max_per_page (integer)
The results per page 		20
nb_of_pages (integer)
The number of pages necessary to show all the list elements 		7
nb_of_records (integer)
The total number of records found 		131
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Packing

This will find out how package items can be fitted into the available boxes (Items are assumed to be shipped flat)

Action

[POST] /ship/packing

Request

POST /ship/packing HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "items": [
        {
            "length": 22,
            "width": 22,
            "height": 10,
            "weight": 10,
            "description": "computer screen"
        },
        "..."
    ],
    "boxes": [
        {
            "box_model": "S4319",
            "length": 52,
            "width": 52,
            "height": 30,
            "weight": 1,
            "max_weight": 50
        },
        "..."
    ],
    "units": "imperial"
}

Details

Name Example Value
items (array)
Array of all the items
Name Example Value
length (decimal)
length of the item 		22
width (decimal)
width of the item 		22
height (decimal)
height of the item 		10
weight (decimal)
weight of the item 		10
description (string)
name of the item 		computer screen
boxes (array)
Array of all the available boxes (the models of boxes based on size)
Name Example Value
box_model (string)
A name given to a model of boxes for easier identification 		S4319
length (decimal)
length of the box(outer size) 		52
width (decimal)
width of the box(outer size) 		52
height (decimal)
height of the box(outer size) 		30
weight (decimal)
weight of the box 		1
max_weight (decimal)
maximum weight the box can hold 		50
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial

Response

200 OK

{
    "content": {
        "packages": [
            {
                "box_model": "S-4319",
                "length": 52,
                "width": 52,
                "height": 30,
                "weight": 32,
                "items": [
                    "computer screen",
                    "computer screen",
                    "album"
                ]
            },
            "..."
        ],
        "units": "imperial"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Packing Result)
Name Example Value
packages (array)
The boxes with items filled inside
Name Example Value
box_model (string)
The name of the box model given in the request 		S-4319
length (decimal)
length of the packed box(outer size) 		52
width (decimal)
width of the packed box(outer size) 		52
height (decimal)
height of the packed box(outer size) 		30
weight (decimal)
weight of the packed box (including the box itself and all the items inside) 		32
items (Item Descriptions)
A list of the descriptions of the items inside the packed box
Name Example Value
0 (string)
Item 1 		computer screen
1 (string)
Item 2 		computer screen
2 (string)
Item 3 		album
units (string)
imperial or metric 		imperial
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Available courier services

This will return a list of all available courier services

Action

[GET] /ship/available_services

URI Parameters

Parameter Value Description
courier_code ups Filter by the courier. Options are ups|dhl|fedex|purolator|canpar

Request

GET /ship/available_services HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK

{
    "content": {
        "ups": [
            {
                "flagship_code": "expressAm",
                "courier_code": "PRIORITY_OVERNIGHT",
                "courier_description": "Priority Overnight"
            },
            "..."
        ],
        "fedex": [
            {
                "flagship_code": "expressAm",
                "courier_code": "PRIORITY_OVERNIGHT",
                "courier_description": "Priority Overnight"
            },
            "..."
        ],
        "purolator": [
            {
                "flagship_code": "expressAm",
                "courier_code": "PRIORITY_OVERNIGHT",
                "courier_description": "Priority Overnight"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Available Services)
List of couriers with their services
Name Example Value
ups (array)
Available services from UPS
Name Example Value
flagship_code (string)
The service code given by Flagship 		expressAm
courier_code (string)
The service code given by courier 		PRIORITY_OVERNIGHT
courier_description (string)
The description of service by courier 		Priority Overnight
fedex (array)
Available services from FedEx
Name Example Value
flagship_code (string)
The service code given by Flagship 		expressAm
courier_code (string)
The service code given by courier 		PRIORITY_OVERNIGHT
courier_description (string)
The description of service by courier 		Priority Overnight
purolator (array)
Available services from Purolator
Name Example Value
flagship_code (string)
The service code given by Flagship 		expressAm
courier_code (string)
The service code given by courier 		PRIORITY_OVERNIGHT
courier_description (string)
The description of service by courier 		Priority Overnight
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Pickup

This will allow to get one(many), modify, and create pick-up for shipment.

Find by id

Get the pickup identified by id field from the request uri

Action

[GET] /pickups/{id}

Request

GET /pickups/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK

{
    "content": {
        "id": 48979792,
        "confirmation": "2929602E9CP",
        "address": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "11",
            "is_commercial": false
        },
        "courier": "ups",
        "boxes": 4,
        "weight": 6,
        "date": "2015-12-31",
        "from": "09:00",
        "until": "17:00",
        "location": "Reception",
        "instruction": "contain glass product, etc.",
        "cancelled": "0",
        "units": "imperial",
        "shipments": [
            "integer",
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Pickup)
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the pickup.
[]
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Create

Create a pickup without shipment ids.

Action

[POST] /pickups

Request

POST /pickups HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "address": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "211",
        "is_commercial": true
    },
    "courier": "ups",
    "boxes": 4,
    "weight": 6,
    "units": "imperial",
    "date": "2015-12-31",
    "from": "09:00",
    "until": "17:00",
    "location": "Reception",
    "to_country": "CA",
    "is_ground": false,
    "instruction": "contain glass product, etc."
}

Details

Name Example Value
address (Address)
Pickup address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
Telephone extension 		211
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar
boxes (integer)
Number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
Weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (enum)
Units of measurement 		imperial|metric
date (date)
Can be YYYY-MM-DD. The default is the current date. 		2015-12-31
from (timestamp)
Can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
Can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is. The default is "Reception". 		Reception
to_country (string)
Destination country code in ISO 3166-1 alpha-2 two letter country code format 		CA
is_ground (boolean)
It has to be true for Fedex Ground pickup. 		false
instruction (string)
Special attention for delivery 		contain glass product, etc.

Response

201 CREATED

{
    "content": {
        "id": 48979792,
        "confirmation": "2929602E9CP",
        "address": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "11",
            "is_commercial": false
        },
        "courier": "ups",
        "boxes": 4,
        "weight": 6,
        "date": "2015-12-31",
        "from": "09:00",
        "until": "17:00",
        "location": "Reception",
        "instruction": "contain glass product, etc.",
        "cancelled": "0",
        "units": "imperial",
        "shipments": [
            "integer",
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Pickup)
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the pickup.
[]
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Create with shipments

Create a list of pickups for confirmed shipments. One pickup will be created for shipments that have the same courier, postal code, street number, and suite number (if applicable). (Note: Fedex Ground and other Fedex services are treated seperately for pickups).

Action

[POST] /pickups

Request

POST /pickups HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "address": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "211",
        "is_commercial": true
    },
    "date": "2015-12-31",
    "from": "09:00",
    "until": "17:00",
    "location": "Reception",
    "instruction": "contain glass product, etc.",
    "shipments": [
        "integer",
        "..."
    ]
}

Details

Name Example Value
address (Address)
If the address is provided, it will override the addresses of all the associated shipments as the pickup address for all the shipments.
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
Telephone extension 		211
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
date (date)
Can be YYYY-MM-DD. The default is the current date. 		2015-12-31
from (timestamp)
Can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
Can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is. The default is "Reception". 		Reception
instruction (string)
Special attention for delivery 		contain glass product, etc.
shipments (array)
Shipment Ids (e.g., 123456, 234567,)
[]

Response

201 CREATED

{
    "content": [
        {
            "id": 48979792,
            "confirmation": "2929602E9CP",
            "address": {
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1A1A1",
                "phone": "18663208383",
                "ext": "11",
                "is_commercial": false
            },
            "courier": "ups",
            "boxes": 4,
            "weight": 6,
            "date": "2015-12-31",
            "from": "09:00",
            "until": "17:00",
            "location": "Reception",
            "instruction": "contain glass product, etc.",
            "cancelled": "0",
            "units": "imperial",
            "shipments": [
                "integer",
                "..."
            ]
        },
        "..."
    ],
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (array)
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the created pickup.
[]
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

206 PARTIAL CONTENT

{
    "content": [
        {
            "id": 48979792,
            "confirmation": "2929602E9CP",
            "address": {
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1A1A1",
                "phone": "18663208383",
                "ext": "11",
                "is_commercial": false
            },
            "courier": "ups",
            "boxes": 4,
            "weight": 6,
            "date": "2015-12-31",
            "from": "09:00",
            "until": "17:00",
            "location": "Reception",
            "instruction": "contain glass product, etc.",
            "cancelled": "0",
            "units": "imperial",
            "shipments": [
                "integer",
                "..."
            ]
        },
        "..."
    ],
    "errors": {
        "fedex": {
            "message": "Service is not available to this location",
            "shipments": "12345,123232"
        }
    },
    "notices": []
}

Details

Name Example Value
content (array)
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the created pickup.
[]
errors (object)
Messages that AFFECT the outcome of the request will be shown here
Name Example Value
fedex (object)
Shows error returning from courier
Name Example Value
message (string)
Service is not available to this location
shipments (string)
12345,123232
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Modify

Update the pickup identified by id field from the request uri

Action

[PUT] /pickups/{id}

Request

PUT /pickups/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "address": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "211",
        "is_commercial": true
    },
    "courier": "ups",
    "boxes": 4,
    "weight": 6,
    "units": "imperial",
    "date": "2015-12-31",
    "from": "09:00",
    "until": "17:00",
    "location": "Reception",
    "to_country": "CA",
    "is_ground": false,
    "instruction": "contain glass product, etc."
}

Details

Name Example Value
address (Address)
Pickup address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
Telephone extension 		211
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar
boxes (integer)
Number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
Weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (enum)
Units of measurement 		imperial|metric
date (date)
Can be YYYY-MM-DD. The default is the current date. 		2015-12-31
from (timestamp)
Can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
Can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is. The default is "Reception". 		Reception
to_country (string)
Destination country code in ISO 3166-1 alpha-2 two letter country code format 		CA
is_ground (boolean)
It has to be true for Fedex Ground pickup. 		false
instruction (string)
Special attention for delivery 		contain glass product, etc.

Response

200 OK

{
    "content": {
        "id": 48979792,
        "confirmation": "2929602E9CP",
        "address": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "11",
            "is_commercial": false
        },
        "courier": "ups",
        "boxes": 4,
        "weight": 6,
        "date": "2015-12-31",
        "from": "09:00",
        "until": "17:00",
        "location": "Reception",
        "instruction": "contain glass product, etc.",
        "cancelled": "0",
        "units": "imperial",
        "shipments": [
            "integer",
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Pickup)
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the pickup.
[]
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Cancel

Cancel the pickup identified by id field from the request uri

Action

[DELETE] /pickups/{id}

Request

DELETE /pickups/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json

Response

204 NO CONTENT

List

List pick-ups filter by parameters

Action

[GET] /pickups

URI Parameters

Parameter Value Description
courier ups Courier service provider
date 2015-12-31 Can be YYYY-MM-DD
page 2 The page wanted in the list of results
limit 23 The number of results wanted per page. Maximum 50.

Request

GET /pickups HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK

{
    "content": {
        "records": [
            {
                "id": 48979792,
                "confirmation": "2929602E9CP",
                "address": {
                    "name": "ACME inc.",
                    "attn": "Bob",
                    "address": "123 Main Street",
                    "suite": "227",
                    "city": "Montreal",
                    "country": "CA",
                    "state": "QC",
                    "postal_code": "A1A1A1",
                    "phone": "18663208383",
                    "ext": "11",
                    "is_commercial": false
                },
                "courier": "ups",
                "boxes": 4,
                "weight": 6,
                "date": "2015-12-31",
                "from": "09:00",
                "until": "17:00",
                "location": "Reception",
                "instruction": "contain glass product, etc.",
                "cancelled": "0",
                "units": "imperial",
                "shipments": [
                    "integer",
                    "..."
                ]
            },
            "..."
        ],
        "current_page": 2,
        "max_per_page": 20,
        "nb_of_pages": 7,
        "nb_of_records": 131
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Pickup List)
Name Example Value
records (array)
Array with the pickups belonging to the requested page
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the pickup.
[]
current_page (integer)
The page the returned records belong to 		2
max_per_page (integer)
The results per page 		20
nb_of_pages (integer)
The number of pages necessary to show all the list elements 		7
nb_of_records (integer)
The total number of records found 		131
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Broker

This will allow to get a list of custom brokers

List

Returns a list of all the available custom brokers

Action

[GET] /brokers

Request

GET /brokers HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK

{
    "content": [
        {
            "id": 12,
            "code": "555",
            "name": "TCARATAC Inc",
            "street_lines": "2094 Grand Island Blvd.",
            "city": "Grand Island",
            "state_province_code": "NY",
            "postal_code": "14072",
            "country_code": "US",
            "phone": "716-773-9207"
        },
        "..."
    ],
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (array)
Name Example Value
id (integer)
The broker id that you will use in your confirmation request 		12
code (string)
The code associated to the broker 		555
name (string)
The broker name 		TCARATAC Inc
street_lines (string)
The broker address 		2094 Grand Island Blvd.
city (string)
The broker address's city 		Grand Island
state_province_code (string)
The broker address's state or province 		NY
postal_code (string)
The broker address's postal code 		14072
country_code (string)
The broker address's country code 		US
phone (string)
The broker phone number 		716-773-9207
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Tracking

This allows to get tracking information about shipments that you processed through FlagShip

Track shipment

Returns the tracking information related to a specific shipment

Action

[GET] /ship/track

URI Parameters

Parameter Value Description
shipment_id 1234567 The shipment id. Required if tracking_number is not specified.
tracking_number 1234567 The shipment's tracking number. Required if shipment_id is not specified.

Request

GET /ship/track HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK

{
    "content": {
        "current_status": "D",
        "courier_update": "2015-10-01 16:43:00",
        "status_desc": "Description: Shipment delivered to K BONCI via BURNABY, BC depot",
        "shipment_id": "1406346"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (array)
Name Example Value
current_status (string)
'M'-Manifested | 'P'-Pickup | 'T'-In transit | 'D'-Delivered | 'U'-Unknown | 'X'-Exception 		D
courier_update (string)
When the tracking data was last updated 		2015-10-01 16:43:00
status_desc (string)
Description of the shiment status provided by the courier 		Description: Shipment delivered to K BONCI via BURNABY, BC depot
shipment_id (string)
The shipment's id 		1406346
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Address Group

This allows to list, create, modify, and delete address groups.

Find an address group by id

Get an address group's details by id.

Action

[GET] /addresses/groups/{groupId}

Request

GET /addresses/groups/{groupId} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK

{
    "content": {
        "id": 1122341,
        "name": "Your company addresses",
        "number_of_addresses": 10,
        "deletable": false,
        "type": "company_addresses"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Address Group)
Name Example Value
id (integer)
The group id 		1122341
name (string)
Name of the address group 		Your company addresses
number_of_addresses (integer)
The total number of addresses in the address group 		10
deletable (boolean)
Indicates whether this address group can be deleted (Note: groups that contain system addresses (headquarter, pickup, billing) of a company cannot be deleted 		false
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses) 		company_addresses
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

List

Get the list of address groups

Action

[GET] /addresses/groups

URI Parameters

Parameter Value Description
name Your company addresses Filter by group name
group_type company_addresses Filter by the type of address group. Options are company_addresses|shipping_addresses|pickup_addresses|other_addresses
contains_address_name John Doe Find address groups that contain at least one address with the provided recipient name

Request

GET /addresses/groups HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK

{
    "content": {
        "records": [
            {
                "id": 1122341,
                "name": "Your company addresses",
                "number_of_addresses": 10,
                "deletable": false,
                "type": "company_addresses"
            },
            "..."
        ],
        "current_page": 2,
        "max_per_page": 20,
        "nb_of_pages": 7,
        "nb_of_records": 131
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Address Group List)
Name Example Value
records (array)
Array with address groups that satisfy the search criteria
Name Example Value
id (integer)
The group id 		1122341
name (string)
Name of the address group 		Your company addresses
number_of_addresses (integer)
The total number of addresses in the address group 		10
deletable (boolean)
Indicates whether this address group can be deleted (Note: groups that contain system addresses (headquarter, pickup, billing) of a company cannot be deleted 		false
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses) 		company_addresses
current_page (integer)
The page the returned records belong to 		2
max_per_page (integer)
The results per page 		20
nb_of_pages (integer)
The number of pages necessary to show all the list elements 		7
nb_of_records (integer)
The total number of records found 		131
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Create

Create an address group.

Action

[POST] /addresses/groups

Request

POST /addresses/groups HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "name": "Your company addresses",
    "type": "company_addresses"
}

Details

Name Example Value
name (string)
Name of the address group 		Your company addresses
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses). Default: other_addresses. 		company_addresses

Response

200 OK

{
    "content": {
        "id": 1122341,
        "name": "Your company addresses",
        "type": "company_addresses"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Address Group)
Name Example Value
id (integer)
The group id 		1122341
name (string)
Name of the address group 		Your company addresses
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses) 		company_addresses
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Modify

Update the address group identified by id field from the request uri.

Action

[PUT] /addresses/groups/{id}

Request

PUT /addresses/groups/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "name": "Your company addresses",
    "type": "company_addresses"
}

Details

Name Example Value
name (string)
Name of the address group 		Your company addresses
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses). Default: other_addresses. 		company_addresses

Response

200 OK

{
    "content": {
        "id": 1122341,
        "name": "Your company addresses",
        "type": "company_addresses"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Address Group)
Name Example Value
id (integer)
The group id 		1122341
name (string)
Name of the address group 		Your company addresses
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses) 		company_addresses
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Delete

Delete the address group identified by id field from the request uri (Note: groups that contain transaction addresses of a company cannot be deleted).

Action

[DELETE] /addresses/groups/{id}

Request

DELETE /addresses/groups/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json

Response

204 NO CONTENT