Docs
API Endpoint
Base API URL: https://packagehub-api.visiblescm.com/v3.1/
Authentication
Description
Before sending your first packages using the PackageHub API, you will need to register for a free PackageHub account to receive an API token used for authentication.
Authentication and identification to the PackageHub API is done by providing a JWT token received in response of Account /Token with every request. Requests made without a proper JWT token will fail.
The PackageHub API provides two types of API Key: Test and Production. You can test all PackageHub API functionality using the Test token generated from your Test key in the Sandbox environment for free immediately after signing up. Test labels created in the Sandbox environment will not be billed to your account. If a label is mistakenly created in the Production environment, a cancel shipment request can be made to avoid accidental charges.
Account
POST /Account/Token
Description
Use this POST method to retrieve your account token, for use in the header as request authorization.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
apiKey* |
Body | string | 90a56104388c4b15b5773d |
apiSecret* |
Body | string | iLNvrse+HOAjp3NM1cmJbOdfRi7X4fxxxxxxxxxxx |
userName* |
Body | string | example@domain.com |
password* |
Body | string | Password123 |
{
"apiKey": "90a56104388c4b15b5773d",
"apiSecret": "iLNvrse+HOAjp3NM1cmJbOdfRi7X4fxxxxxxxxxxx",
"userName": "example@domain.com",
"password": "Password123"
}
Code Samples
curl -X POST \
https://packagehub-api.visiblescm.com/v3.1/Account/Token \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d '{
"apiKey": "90a56104388c4b15b5773d",
"apiSecret": "iLNvrse+HOAjp3NM1cmJbOdfRi7X4fxxxxxxxxxxx",
"userName": "example@domain.com",
"password": "Password123"
}'
GET /Account/Postage/Balance
Description
To access information about your account and payment information, use this GET method. The response returns additional account settings such as AutoBuy settings, rate set, and account balance.
Note
Request object is empty because all required input parameters are provided in the authorization token in Header.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/Account/Postage/Balance \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
PUT /Account/Postage/Balance
Description
Use this PUT method to add funds to your shipping account. When this method is called, funds will be added to the account, using the payment method on file.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
transactionId* |
Header | string | 123456789 |
balance* |
Body | number | 100 |
Code Samples
curl -X PUT \
https://packagehub-api.visiblescm.com/v3.1/Account/Postage/Balance \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'TransactionId: 721' \
-H 'cache-control: no-cache' \
-d '{
"balance": 100
}'
PUT /Account/Postage/AutoBuy
Description
For accounts using a credit card to prepay for postage, use this PUT method to turn AutoBuy functionality on and off and to set recharge limits.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
isAutoBuy* |
Body | boolean | true/false |
autoBuyAmount* |
Body | number | 100 |
autoBuyThreshold* |
Body | number | 50 |
Code Samples
curl -X PUT \
https://packagehub-api.visiblescm.com/v3.1/Account/Postage/AutoBuy \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d '{
"isAutoBuy": true,
"autoBuyAmount": 100,
"autoBuyThreshold": 50
}'
GET /Account/Postage/BalanceHistory
Description
Use this GET method to retrieve the account balance history. The response will return each payment event and adjustment. Use the available parameters to filter your search.
Note
Request object is empty because all required input parameters are provided in the Query Param.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
pageToken | Query Param | string | NULL for first request, for further pages use pageToken as returned in response of current request |
startDate | Query Param | Date(yyyy-mm-dd) | 2019-10-18T07:28:56.864Z |
endDate | Query Param | Date(yyyy-mm-dd) | 2019-10-18T07:28:56.864Z |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/Account/Postage/BalanceHistory?startDate=2019-09-01T18:29:59.999Z,2019-09-23T18%3A30%3A00.000Z&endDate=2019-09-25T18:29:59.999Z&pageToken=ewoiY3VycmVudFBhZ2UiOiAiMSIsCiJuZXh0UGFnZSI6ICIyIgp9 \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
User
POST /User/SignUp/Customer
Description
Use this POST method to register as a customer.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
email* |
Body | string | user@example.com |
password* |
Body | string | Password123 |
companyName* |
Body | string | ABC Company |
firstName* |
Body | string | John |
lastName* |
Body | string | Ships |
signupKey | Body | string | 674a65db-4318-430f-980c-0f408409b91c |
{
"email": "user@example.com",
"password": "Password123",
"companyName": "ABC Company",
"firstName": "John",
"lastName": "Ships",
"signupKey": "674a65db-4318-430f-980c-0f408409b91c"
}
Code Samples
curl -X POST \
https://packagehub-api.visiblescm.com/v3.1/User/SignUp/Customer \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
-d '{
"email": "user@example.com",
"password": "Password123",
"companyName": "ABC Company",
"firstName": "John",
"lastName": "Ships",
"signupKey": "674a65db-4318-430f-980c-0f408409b91c"
}'
POST /User/ApproveTermsAndConditions
Description
Use this POST method to approve terms and conditions for the newly created account.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
accountId* |
Body | string | 674a65db-4318-430f-980c-0f408409b91c |
Code Samples
curl -X POST \
https://packagehub-api.visiblescm.com/v3.1/User/ApproveTermsAndConditions \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d '{
"accountId": "674a65db-4318-430f-980c-0f408409b91c"
}'
Address
Address
Description
Address objects contain all necessary information for the generation of address required a shipments.
Parameters
param | in | Type | Comments |
---|---|---|---|
name | Body | string | John Ships |
company | Body | string | Maersk |
street1 | Body | string | 5160 W WILEY POST WAY |
street2 | Body | string | |
street3 | Body | string | |
city | Body | string | SALT LAKE CITY |
state | Body | string | UT |
zip | Body | string | 84116-2833 |
country | Body | string | US |
phone | Body | string | 8888888888 |
Body | string | support@packagehub.com | |
save | Body | boolean | true |
verify | Body | boolean | true |
source | Body | string | Shipment |
verificationStatus | Body | string | true |
isResidential | Body | boolean | false |
referenceType | Body | string | Possible values are: TaxCode, VATNumber, and ImportExportCode |
referenceValue | Body | string | 123456 |
{
"name": "John Ships",
"company": "Maersk",
"street1": "5160 W WILEY POST WAY",
"street2": "",
"street3": "",
"city": "SALT LAKE CTY",
"state": "UT",
"zip": "84116-2833",
"country": "US",
"phone": "8888888888",
"email": "support@packagehub.com",
"save": true,
"verify": true,
"source": "Shipment",
"verificationStatus": "Success",
"isResidential": false,
"referenceType": "TaxCode",
"referenceValue": "H123"
}
GET /Address/:id
Description
Use this GET method to find an existing address.
Note
Request object is empty because all required input parameters are provided in the Route Param.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
id* |
Route Param | string | aa5b3c5f-ebe1-468f-a099-92792ea042e7 |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/Address/aa5b3c5f-ebe1-468f-a099-92792ea042e7 \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
POST /Address
Description
Use this POST method to create an address. The id generated in address response can be used in ShipmentRate, Shipment and Manifest request address object.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
address* |
Body | <Address> |
{
"name": "John Ships",
"company": "Maersk",
"street1": "5160 W WILEY POST WAY",
"street2": "",
"street3": "",
"city": "SALT LAKE CTY",
"state": "UT",
"zip": "84116-2833",
"country": "US",
"phone": "8888888888",
"email": "support@packagehub.com",
"save": true,
"verify": true,
"source": "Shipment",
"verificationStatus": "Success",
"isResidential": false,
"referenceType": "TaxCode",
"referenceValue": "H123"
}
Code Samples
curl -X POST \
https://packagehub-api.visiblescm.com/v3.1/Address \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
-d '{
"name": "John Ships",
"company": "Maersk",
"street1": "5160 W WILEY POST WAY",
"street2": "",
"street3": "",
"city": "SALT LAKE CTY",
"state": "UT",
"zip": "84116-2833",
"country": "US",
"phone": "8888888888",
"email": "support@packagehub.com",
"save": true,
"verify": true,
"source": "Shipment",
"verificationStatus": "Success",
"isResidential": false,
"referenceType": "TaxCode",
"referenceValue": "H123"
}'
POST /Address/:id/Validate
Description
Use this POST method to validate an existing address.
Note
Request object is empty because all required input parameters are provided in the Route Param.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
id* |
Route Param | string | aa5b3c5f-ebe1-468f-a099-92792ea042e7 |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/Address/91234b72-78ed-4a94-8448-0fef1b761455/Validate \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
Carrier
GET /Carrier
Description
Use this GET method to retrieve a list of available carriers that can be configured on the account.
Note
Request object is empty because all required input parameters are provided in the authorization token in Header.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/Carrier \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
CarrierAccount
GET /CarrierAccount
Description
Use this GET method to retrieve a list of available carriers configured on the account.
Note
Request object is empty because all required input parameters are provided in the authorization token in Headers.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/CarrierAccount \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
POST /CarrierAccount
Description
Use this POST method to configure a new carrier against the account.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
name* |
Body | string | USPS |
carrierCode* |
Body | string | USPS-eVS |
configuration* |
Body | Object | {} |
description | Body | string | Postal solution for large shippers that require a scheduled carrier pickup, powered by Maersk. |
logo | Body | string | https://visibleshippingqastorage.blob.core.windows.net/public-dev-container/logo/USPS.svg |
status | Body | string | Possible values are: Enabled and Disabled |
{
"name": "USPS",
"description": "Postal solution for large shippers that require a scheduled carrier pickup, powered by Maersk.",
"carrierCode": "USPS-eVS",
"configuration": {
"shipFromAddressId": "5a3d6676-6568-49a8-ab7f-b7e8b7dabc80"
},
"logo": "https://visibleshippingqastorage.blob.core.windows.net/public-dev-container/logo/USPS.svg",
"status": "Enabled"
}
Code Samples
curl -X POST \
https://packagehub-api.visiblescm.com/v3.1/CarrierAccount \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
"name": "USPS",
"description": "Postal solution for large shippers that require a scheduled carrier pickup, powered by Maersk.",
"carrierCode": "USPS-eVS",
"configuration": {
"shipFromAddressId": "5a3d6676-6568-49a8-ab7f-b7e8b7dabc80"
},
"logo": "https://visibleshippingqastorage.blob.core.windows.net/public-dev-container/logo/USPS.svg",
"status": "Enabled"
}'
PUT /CarrierAccount
Description
Use this PUT method to update an already configured carrier account.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
name* |
Body | string | USPS |
carrierCode* |
Body | string | USPS-eVS |
configuration* |
Body | Object | {} |
description | Body | string | Postal solution for large shippers that require a scheduled carrier pickup, powered by Maersk. |
logo | Body | string | https://visibleshippingqastorage.blob.core.windows.net/public-dev-container/logo/USPS.svg |
status | Body | string | Possible values are: Enabled and Disabled |
{
"name": "USPS",
"description": "Postal solution for large shippers that require a scheduled carrier pickup, powered by Maersk.",
"carrierCode": "USPS-eVS",
"configuration": {},
"logo": "https://visibleshippingqastorage.blob.core.windows.net/public-dev-container/logo/USPS.svg",
"status": "Enabled"
}
Code Samples
curl -X PUT \
https://packagehub-api.visiblescm.com/v3.1/CarrierAccount \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d '{
"name": "USPS",
"description": "Postal solution for large shippers that require a scheduled carrier pickup, powered by Maersk.",
"carrierCode": "USPS-eVS",
"configuration": {},
"logo": "https://visibleshippingqastorage.blob.core.windows.net/public-dev-container/logo/USPS.svg",
"status": "Enabled"
}'
DELETE /CarrierAccount/:carrierAccountId
Description
Use this DELETE method to remove the configured carrier account.
Note
Request object is empty because all required input parameters are provided in the Route Param.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
carrierAccountId* |
Route Param | string | b8cffe1f-2769-4607-a0a6-1b5200f185e1 |
Code Samples
curl -X DELETE \
https://packagehub-api.visiblescm.com/v3.1/CarrierAccount/b8cffe1f-2769-4607-a0a6-1b5200f185e1
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
GET /CarrierAccount/Service
Description
This GET method will provide a list of all available services for each carrier that are configured on the account.
Note
Request object is empty because all required input parameters are provided in the authorization token in Header.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/CarrierAccount/Service \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
GET /CarrierAccount/SpecialService
Description
Use this GET method to retrieve all the special services offered by the carrier that are configured on the account.
Note
Request object is empty because all required input parameters are provided in the authorization token in Header.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/CarrierAccount/SpecialService \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
GET /CarrierAccount/PackageType
Description
Use this GET method to retrieve all the available package types for the carrier that are configured on the account.
Note
Request object is empty because all required input parameters are provided in the authorization token in Header.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/CarrierAccount/PackageType \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
ShipmentRate
ShipmentRate is used to create the shipping rates with the provided shipment information. If no carrier or services are included in the request, rates for all carriers and services configured on the PackageHub shipping account will be included in the response.
POST /ShipmentRate
Description
Use this POST method to get shipping rates for the provided shipment information. If no carrier(s) or service type(s) are provided, rates for all carriers and/or service types configured for the PackageHub shipping account will be retrieved. It only returns error when not even a single rate is returned in rate[]. If any specific rate is not returned in rateshop then please rate with specific CarrierAccountId, Service and PackageType to find out error details.
Request Parameters
param | in | Type | Comments | |
---|---|---|---|---|
authorization* |
Header | string | <Account /Token> | |
fromAddress* |
Body | <Address> | either address id or complete address detail can be passed in fromAddress object | |
toAddress* |
Body | <Address> | either address id or complete address detail can be passed in toAddress object | |
packages* |
Body | <Package> | ||
service | Body | string | Possible values are: PriorityMail, PriorityMailExpress, ParcelSelect, GroundAdvantage, PriorityMailExpressIntl, PriorityMailIntl, GlobalExpressGuaranteed, FirstClassIntl, LibraryMail, MediaMail, BoundPrintedMatter, FirstClass, Ecommerce, Express12:00DOC, Express12:00, Express9:00DOC, Express9:00, ExpressWorldwide, GlobalMailBusiness, SecondDayAir, SecondDayAirAM, ThreeDaySelect, Ground, NextDayAir, NextDayAirSaver, StandardToCanada, StandardToMexico, WorldWideExpedited, WorldWideExpress, WorldWideExpressPlus, and WorldWideSaver | |
carrierAccountId | Body | string | 000f4008-190b-419e-bd51-1048c3135a56 | |
specialService | Body | string | Possible values are: RestrictedDelivery, SundayDelivery, HolidayDelivery, CrematedRemains, LiveAnimals, HAZMAT, COD, RegisteredMail, Insurance, CertifiedMail, ElectronicReturnReceipt, AdultSignature, Tracking, SignatureConfirmation, and Delivery1030AM | |
customsInfo | Body | <CustomsInfo> | ||
specialServiceParam | Body | <SpecialService> |
{
"fromAddress": {
"id": "0bc5b3b5-7828-4994-8928-a38e9ce388aa"
},
"toAddress": {
"name": "Jane Ships",
"company": "Maersk",
"street1": "5160 Wiley Post Way",
"street2": "",
"city": "Salt Lake City",
"state": "UT",
"zip": "84116",
"country": "US",
"phone": "4151234567",
"verify": false
},
"packages": [
{
"packageType": "Parcel",
"isRectangle": true,
"length": 35,
"width": 10,
"height": 10,
"dimensionUnit": "in",
"weight": 5,
"weightUnit": "lb"
}
],
"carrierAccountId": "000f4008-190b-419e-bd51-1048c3135a56",
"specialService": ["SundayDelivery"],
"customsInfo": {
"customsItem": [
{
"weightUnit": "oz",
"description": "Custom Description is Here",
"quantity": 1,
"weight": 5,
"value": 2.2,
"hsTariffNumber": "123456",
"originCountry": "US"
}
],
"contentType": "DOCUMENTS",
"nonDeliveryOption": "RETURN"
}
}
Code Samples
curl -X POST \
https://packagehub-api.visiblescm.com/v3.1/ShipmentRate \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Cache-Control: no-cache' \
-H 'Connection: keep-alive' \
-H 'Content-Length: 2428' \
-H 'Content-Type: application/json' \
-H 'Host: packagehub-api.visiblescm.com' \
-H 'User-Agent: Mozilla/5.0' \
-H 'cache-control: no-cache' \
-d '{
"fromAddress": {
"id": "0bc5b3b5-7828-4994-8928-a38e9ce388aa"
},
"toAddress": {
"name": "Jane Ships",
"company": "Maersk",
"street1": "5160 Wiley Post Way",
"street2": "",
"city": "Salt Lake City",
"state": "UT",
"zip": "84116",
"country": "US",
"phone": "4151234567",
"verify": false
},
"packages": [
{
"packageType": "Parcel",
"isRectangle": true,
"length": 5,
"width": 3,
"height": 2,
"dimensionUnit": "cm",
"weight": 5,
"weightUnit": "lb"
}
],
"carrierAccountId": "000f4008-190b-419e-bd51-1048c3135a56",
"specialService": ["RestrictedDelivery"],
"customsInfo": {
"customsItem": [
{
"weightUnit": "oz",
"description": "Custom Description is Here",
"quantity": 1,
"weight": 5,
"value": 2.2,
"hsTariffNumber": "123456",
"originCountry": "US"
}
],
"contentType": "DOCUMENTS",
"nonDeliveryOption": "RETURN"
}
}'
Shipment
The shipment is central to the PackageHub API. A shipment consists of a to and from address, at least a single package, a carrier, and service type. This information is used to generate a shipping label.
GET /Shipment
Description
Use this GET method to retrieve an individual shipment or a list of shipments that have been created. Use parameters to filter values to find the shipment(s) you need to view.
Note
Request object is empty because all required input parameters are provided in the Query Param.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
key | Query Param | string | Possible values are: Id, ShipmentId, TransactionId, and TrackingNumber |
value | Query Param | string | e77e7eb7-6062-4e6d-b1ab-fafb58a611cd |
packageNumber | Query Param | number | 1 |
pageToken | Query Param | string | NULL for first request, for further pages use pageToken as returned in response of current request |
startDate | Query Param | Date(yyyy-mm-dd) | 2019-10-18 |
endDate | Query Param | Date(yyyy-mm-dd) | 2019-10-18 |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/Shipment?key=Id&value=e77e7eb7-6062-4e6d-b1ab-fafb58a611cd&packageNumber=1&pageToken=ewoiY3VycmVudFBhZ2UiOiAiMSIsCiJuZXh0UGFnZSI6ICIyIgp9&startDate=2019-10-18T07:28:56.864Z&endDate=2019-10-18T07:28:56.864Z \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
POST /Shipment
Description
Use this POST method to create a new shipment. A label will be generated in the response with the defined format requested.
In case of shipping to/from same address, its preferrable to use address id instead of complete address object, however its not mandatory.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
transactionId* |
Header | string | 123456789, unique for each transaction |
fromAddress* |
Body | <Address> | either address id or complete address detail can be passed in fromAddress object |
toAddress* |
Body | <Address> | either address id or complete address detail can be passed in toAddress object |
packages* |
Body | <Package> | |
service* |
Body | string | Possible values are: PriorityMail, PriorityMailExpress, ParcelSelect, GroundAdvantage, PriorityMailExpressIntl, PriorityMailIntl, GlobalExpressGuaranteed, FirstClassIntl, LibraryMail, MediaMail, BoundPrintedMatter, FirstClass, Ecommerce, Express12:00DOC, Express12:00, Express9:00DOC, Express9:00, ExpressWorldwide, GlobalMailBusiness, SecondDayAir, SecondDayAirAM, ThreeDaySelect, Ground, NextDayAir, NextDayAirSaver, StandardToCanada, StandardToMexico, WorldWideExpedited, WorldWideExpress, WorldWideExpressPlus, and WorldWideSaver |
carrierAccountId* |
Body | string | 000f4008-190b-419e-bd51-1048c3135a56 |
customsInfo* |
Body | <CustomsInfo> | Required in case of International Shipment Request |
altReturnAddress | Body | <Address> | either address id or complete address detail can be passed in altReturnAddress object |
postageLabel | Body | <PostageLabel> | |
shipDate | Body | Date(yyyy-mm-dd) | 2021-10-18 |
specialService | Body | string | Possible values are: RestrictedDelivery, SundayDelivery, HolidayDelivery, CrematedRemains, LiveAnimals, HAZMAT, COD, RegisteredMail, Insurance, CertifiedMail, ElectronicReturnReceipt, AdultSignature, Tracking, SignatureConfirmation, and Delivery1030AM |
specialServiceParam | Body | <SpecialServiceParam> |
{
"toAddress": {
"name": "John Ships",
"company": "Maersk",
"street1": "1545 s 4800 w",
"street2": "",
"city": "Salt Lake City",
"state": "UT",
"zip": "84104",
"country": "US",
"phone": "5708208072",
"verify": false
},
"fromAddress": {
"name": "Jane Ships",
"company": "Maersk",
"street1": "5160 Wiley Post Way",
"street2": "",
"city": "Salt Lake City",
"state": "UT",
"zip": "84116",
"country": "US",
"phone": "4151234567",
"verify": false
},
"altReturnAddress": {
"name": "Jane Ships",
"company": "Maersk",
"street1": "5160 Wiley Post Way",
"street2": "",
"city": "Salt Lake City",
"state": "UT",
"zip": "84116",
"country": "US",
"phone": "4151234567",
"verify": false
},
"packages": [
{
"packageType": "Parcel",
"length": 35,
"width": 10,
"height": 10,
"weight": 1
}
],
"service": "PriorityMail",
"carrierAccountId": "0fe85d6e-6aca-4dc6-930e-de970965f585",
"postageLabel": {
"labelFileType": "PNG",
"labelType": "Url"
}
}
Code Samples
curl -X POST \
https://packagehub-api.visiblescm.com/v3.1/shipment \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'TransactionId: 243' \
-H 'cache-control: no-cache' \
-d '{
"toAddress": {
"name": "John Ships",
"company": "Maersk",
"street1": "1545 s 4800 w",
"street2": "",
"city": "Salt Lake City",
"state": "UT",
"zip": "84104",
"country": "US",
"phone": "5708208072",
"verify": false
},
"fromAddress": {
"name": "Jane Ships",
"company": "Maersk",
"street1": "5160 Wiley Post Way",
"street2": "",
"city": "Salt Lake City",
"state": "UT",
"zip": "84116",
"country": "US",
"phone": "4151234567",
"verify": false
},
"altReturnAddress": {
"name": "Jane Ships",
"company": "Maersk",
"street1": "5160 Wiley Post Way",
"street2": "",
"city": "Salt Lake City",
"state": "UT",
"zip": "84116",
"country": "US",
"phone": "4151234567",
"verify": false
},
"packages": [
{
"packageType": "Parcel",
"length": 12,
"width": 12,
"height": 12,
"weight": 1
}
],
"service": "PriorityMail",
"carrierAccountId": "0fe85d6e-6aca-4dc6-930e-de970965f585",
"postageLabel": {
"labelFileType": "PNG",
"labelType": "Url"
}
}'
POST /Shipment/Refund
Description
POST to this method to request a refund for a shipment. Processing time for label refunds are dependent on the carrier and may take up to 2-4 weeks to process.
Refund Status
Status | Description |
---|---|
Initiated | Refund initiated but request is not yet processed. |
Approved | Refund approved by carrier but refund amount has not been processed yet. |
Rejected | Refund rejected by carrier. |
Refunded | Refund approved and refund amount has been processed. |
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
transactionId* |
Header | string | 12345665, unique for each transaction |
key* |
Body | string | Possible values are: Id, ShipmentId, and TrackingNumber |
value* |
Body | string | fe09ea71-7329-4757-afe5-f7a7cf057e3e |
Code Samples
curl -X POST \
https://packagehub-api.visiblescm.com/v3.1/Shipment/Refund \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'TransactionId: 35345' \
-H 'Cache-Control: no-cache' \
-H 'Connection: keep-alive' \
-H 'Content-Length: 41' \
-H 'Content-Type: application/json' \
-H 'Host: packagehub-api.visiblescm.com' \
-H 'User-Agent: Mozilla/5.0' \
-H 'cache-control: no-cache' \
-d '{
"key": "ShipmentId",
"value": "fe09ea71-7329-4757-afe5-f7a7cf057e3e"
}'
GET /Shipment/:id/Label
Description
Use this GET method to print a label for an existing shipment. Warehouses are complicated spaces and oftentimes labels will get lost or damaged. Utilize this API call to print a label in such situations.
Note
Request object is empty because all required input parameters are provided in the Route and Query Param.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
id* |
Route Param | string | fe09ea71-7329-4757-afe5-f7a7cf057e3e |
packageNumber | Query Param | number | 1 |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/Shipment/{id}/Label \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Cache-Control: no-cache' \
-H 'Connection: keep-alive' \
-H 'Content-Type: application/json' \
-H 'Host: packagehub-api.visiblescm.com' \
-H 'User-Agent: Mozilla/5.0' \
-H 'cache-control: no-cache'
Manifest
The Manifest, also referred to as SCAN Form or end-of-day form, alerts the carrier(s) to shipments entering their network and provides couriers with a way to accept packages in bulk.
POST /Manifest
Description
Use this POST method to create a Manifest for shipments to notify carrier(s) of the packages that will be put in their network.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
fromAddress* |
Body | <Address> | either address id or complete address detail can be passed in fromAddress object |
carrierAccountId* |
Body | string | 0fe85d6e-6aca-4dc6-930e-de970965f585 |
key* |
Body | string | Possible values are: ShipmentId, TrackingNumber, and TransactionId |
value* |
Body | string[] | [Array of shipmentIds] |
shipDate | Body | Date(yyyy-mm-dd) | 2021-10-30 |
{
"fromAddress": {
"id": "6bc099e7-53b9-4051-bc14-354cd924018a"
},
"carrierAccountId": "0fe85d6e-6aca-4dc6-930e-de970965f585",
"key": "ShipmentId",
"value": ["ef01bffa-f0b7-47b2-9eed-56a01b786dfd"],
}
Code Samples
curl -X POST \
https://packagehub-api.visiblescm.com/v3.1/Manifest \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d '{
"fromAddress": {
"id": "6bc099e7-53b9-4051-bc14-354cd924018a"
},
"carrierAccountId": "0fe85d6e-6aca-4dc6-930e-de970965f585",
"key": "ShipmentId",
"value": [
"ef01bffa-f0b7-47b2-9eed-56a01b786dfd"
]
}'
GET /Manifest
Description
Use this GET method to retrieve a Manifest you have submitted. You may also request a list of some or all of the Manifests that have been submitted.
Note
Request object is empty because all required input parameters are provided in the Query Param.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
key* |
Query Param | string | Id |
value* |
Query Param | string | 000f4008-190b-419e-bd51-1048c3135a56 |
pageToken | Query Param | string | NULL for first request, for further pages use pageToken as returned in response of current request |
startDate | Query Param | Date(yyyy-mm-dd) | 2021-10-18 |
endDate | Query Param | Date(yyyy-mm-dd) | 2021-10-18 |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/Manifest?Key=Id&Value=f179a731-fd01-4997-986c-c494c71106e8&pageToken=ewoiY3VycmVudFBhZ2UiOiAiMSIsCiJuZXh0UGFnZSI6ICIyIgp9&startDate=2019-10-18T07:28:56.864Z&endDate=2019-10-18T07:28:56.864Z \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
Tracking
Tracking is used to retrieve shipment tracking information. The trackingNumber is generated after a successful shipment is created. The status is updated as the package moves from the origin to destination. The carrier provides the PackageHub API with updated tracking status data as package statuses and destinations change.
Different Tracking Status
Status | Description | Possible Sub Status |
---|---|---|
PreTransit | Label has been printed but carrier has not yet picked up the package | Label generated, Shipping info sent to carrier, Ready for pickup |
InTransit | Package is traveling to its destination | Origin scan, Departure scan, Arrival, Destination scan, Damaged, Pickup scan, Received by local post office, Transferred to local post office, Import scan, Export scan, Carrier changed delivery, Arrived at carrier facility, Departed carrier facility |
Delayed | Package has been delayed but still in transit | Pickup delayed, Weather delay, Bad delivery address |
OutForDelivery | Package has reached the delivery area and is in process of being delivered | Delivery attempted |
DeliveryFailed | Delivery of the package has failed and it will either be discarded or start moving to original shipper | Refused, Cannot deliver to POBox, Undeliverable, Returning, Returned |
Delivered | Package has been delivered | Delivered, Delivered to agent |
Cancelled | Shipment has been cancelled by the shipper | Sender stopped, Void info received |
Other | Less common or exception statuses | Unknown, Pending, Failure, Lost package, Hold for future delivery, Pickup at carrier facility |
GET /Tracking
Description
Use this GET method to retrieve a specific shipment tracking detail via ShipmentId or TrackingNumber
Note
Request object is empty because all required input parameters are provided in the Query Param.
Request Parameters
param | in | Type | Comments |
---|---|---|---|
authorization* |
Header | string | <Account /Token> |
key* |
Query Param | string | Possible values are: Id, ShipmentId, and TrackingNumber |
value* |
Query Param | string | 9200190242327032670326 |
Code Samples
curl -X GET \
https://packagehub-api.visiblescm.com/v3.1/Tracking?Key={Id/ShipmentId/TrackingNumber/TransactionId}&Value={String} \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Cache-Control: no-cache' \
-H 'Connection: keep-alive' \
-H 'Content-Type: application/json' \
-H 'Host: packagehub-api.visiblescm.com' \
-H 'User-Agent: Mozilla/5.0' \
-H 'cache-control: no-cache'
Errors
Description
When a client or the server encounters an error, a subsequent response will be returned with information on why the call was not successful, which will enable you to identify fixes quickly and easily.
An easy-to-understand JSON message will be returned with a standard 4xx or 5xx code and with an accompanying body description explaining the issue.
Every response will contain a header X-Correlation-ID which correlates HTTP requests between your client and our server.
Response Body
attribute | type | specification |
---|---|---|
StatusCode | HttpStatusCode | Http status code denoting the cause of failure |
TimeStamp | String | Date and time at the moment of failure |
Path | String | Request URL where failure occured |
Source | String | Indicates the subsystem or external provider where actual error is generated |
Errors | Array of Error objects | Breakdown of the failure |
Error Object
attribute | type | specification |
---|---|---|
Code | String | Machine readable description of the failure |
Message | String | Human readable description of the failure |
AdditionalInfo | Object | It contains error code and message as returned by external providers when name of provider is not PHv3 |
Error Codes
Error Codes mapping with HttpsStatusCodes
HttpStatusCode | Package Hub Error Code |
---|---|
400 (Bad Request) | [Module.[SubModule]].BAD_REQUEST |
401 (Unauthorized) | [Module.[SubModule]].AUTHENTICATION_FAILED |
404 (Not Found) | [Module.[SubModule]].NOT_FOUND |
422 (Unprocessable Entity) | [Module.[SubModule]].VALIDATION_FAILED [Module.[SubModule]].NOT_SUPPORTED [Module.[SubModule]].NOT_ACTIVE [Module.[SubModule]].PAYMENT_FAILED |
500 (Internal Server Errror) | PH.INTERNAL_SERVER_ERROR |
Error Codes with some example description(s)
Package Hub Error Code | Error Codes with some example description(s) |
---|---|
ACCOUNT.NOT_ACTIVE |
|
ACCOUNT.NOT_FOUND |
|
ACCOUNT.PAYMENT_FAILED |
|
ACCOUNT.VALIDATION_FAILED |
|
ACCOUNT.APP.AUTHENTICATION_FAILED |
|
ACCOUNT.APP.VALIDATION_FAILED |
|
ACCOUNT.BALANCE.VALIDATION_FAILED |
|
ACCOUNT.PARENT.NOT_FOUND |
|
ACCOUNT.PARENT.VALIDATION_FAILED |
|
ADDRESS.VALIDATION_FAILED |
|
CARRIER.NOT_ACTIVE |
|
CARRIER.NOT_SUPPORTED |
|
CARRIERACCOUNT.NOT_ACTIVE |
|
CARRIERACCOUNT.NOT_FOUND |
|
CARRIERACCOUNT.VALIDATION_FAILED |
|
MANIFEST.NOT_FOUND |
|
MANIFEST.NOT_SUPPORTED |
|
MANIFEST.VALIDATION_FAILED |
|
PACKAGETYPE.NOT_ACTIVE |
|
PACKAGETYPE.NOT_FOUND |
|
PACKAGETYPE.NOT_SUPPORTED |
|
PACKAGETYPE.VALIDATION_FAILED |
|
SERVICE.NOT_ACTIVE |
|
SERVICE.NOT_SUPPORTED |
|
SHIPMENT.BAD_REQUEST |
|
SHIPMENT.NOT_FOUND |
|
SHIPMENT.VALIDATION_FAILED |
|
SHIPMENT.LABEL.VALIDATION_FAILED |
|
SHIPMENT.REFUND.NOT_SUPPORTED |
|
SHIPMENT.REFUND.VALIDATION_FAILED |
|
SHIPMENT.TRACKING.NOT_SUPPORTED |
|
SHIPMENTRATE.NOT_FOUND |
|
SHIPMENTRATE.VALIDATION_FAILED |
|
SPECIALSERVICE.NOT_SUPPORTED |
|
SPECIALSERVICE.VALIDATION_FAILED |
|
USER.NOT_FOUND |
|
USER.VALIDATION_FAILED |
|
Extras
BillTo
Description
Use BillTo object to bill the correct account for the shipment. This object is optional and it works for DHL, UPS and FedEx only.
Parameters
param | in | Type | Comments |
---|---|---|---|
type | Body | string | Supported values are: Sender, Recipient, ThirdParty. Defaults to Sender. |
account | Body | string | Setting account number. Required for Recipient and ThirdParty. |
zip | Body | string | Setting zip code that the account is based in. Only applicable to UPS. Required for Recipient and ThirdParty. |
countryCode | Body | string | Setting country code that the account is based in. Only applicable to UPS. Required for ThirdParty. |
{
"type": "Recipient",
"account": "168974560",
"zip": "87226",
"countryCode": "US"
}
CustomsInfo
Description
CustomsInfo objects contain CustomsItem objects and all necessary information for the generation of customs form required for international shipments.
Parameters
param | in | Type | Comments |
---|---|---|---|
customsItem | Body | <CustomsItem> | |
id | Body | string | |
contentType | Body | string | Possible values are: Documents, Gift, Merchandise, ReturnedGoods, Sample, Other, Humanitarian, and DangerousGoods |
contentsExplanation | Body | string | |
customsCertify | Body | boolean | |
customsSigner | Body | string | |
currency | Body | string | |
nonDeliveryOption | Body | string | Possible values are: Return and Abandon |
restrictionType | Body | string | Possible values are: Quarantine, SanitaryInspection, Phytosanitary, Inspection, and Other |
restrictionComments | Body | string | |
eelpfc | Body | string | Possible values are: NOEEI3037a, NOEEI3036, NOEEI3037h, NOEEI3037y, and AES_ITN |
aesitn | Body | string |
{
"customsItem": [
{
"weightUnit": "oz",
"customsInfoId": "string",
"description": "string",
"quantity": 0,
"weight": 0,
"value": 0,
"hsTariffNumber": "string",
"originCountry": "string",
"itemCode": "string",
"id": "string",
"packageNumber": 0,
"createdDate": "2020-10-08T19:32:18.764Z"
}
],
"id": "string",
"contentType": "Documents",
"contentsExplanation": "string",
"customsCertify": true,
"customsSigner": "string",
"currency": "string",
"nonDeliveryOption": "Return",
"restrictionType": "Quarantine",
"restrictionComments": "string",
"eelpfc": "NOEEI3037a",
"aesitn": "string"
}
CustomsItem
Description
CustomsItem object describes goods for international shipment and should be included in a CustomsInfo object.
Parameters
param | in | Type | Comments |
---|---|---|---|
weightUnit | Body | string | Possible values are: oz, lb, g, and kg |
customsInfoId | Body | string | |
description | Body | string | |
quantity | Body | number | |
weight | Body | number | |
value | Body | number | |
hsTariffNumber | Body | string | Required when shipping to EU, Norway and Switzerland |
originCountry | Body | string | |
itemCode | Body | string | |
id | Body | string | |
packageNumber | Body | number | |
createdDate | Body | string |
{
"weightUnit": "oz",
"customsInfoId": "string",
"description": "string",
"quantity": 0,
"weight": 0,
"value": 0,
"hsTariffNumber": "string",
"originCountry": "string",
"itemCode": "string",
"id": "string",
"packageNumber": 0,
"createdDate": "2020-10-08T19:32:18.764Z"
}
Packages
Description
Packages object specifies the type of package being used for shipment and its corresponding properties.
Parameters
param | in | Type | Comments |
---|---|---|---|
id | Body | string | |
packageType | Body | string | Possible values are: Parcel, FlatRateEnvelope, SmallFlatRateBox, PaddedFlatRateEnvelope, LargeFlatRateBox, LegalFlatRateEnvelope, SoftPack, MediumFlatRateBox1, and MediumFlatRateBox2 |
isRectangle | Body | boolean | Set this to false to inform carrier that your package is not of regular shape |
length | Body | number | |
width | Body | number | |
height | Body | number | |
dimensionUnit | Body | string | Possible values are: cm, mm, m, in, ft, and yd |
weight | Body | number | |
weightUnit | Body | string | Possible values are: oz, lb, g, and kg |
{
"id": "string",
"packageType": "Parcel",
"isRectangle": true,
"length": 0,
"width": 0,
"height": 0,
"dimensionUnit": "cm",
"weight": 0,
"weightUnit": "oz"
}
PostageLabel
Description
Postage label object describes label type, label file type and custom text.
Parameters
param | in | Type | Comments |
---|---|---|---|
labelType | Body | string | Possible values are: Base64 and Url |
labelFileType | Body | string | Possible values are: PDF, TIF, ZPL, PNG, ZPL2, and JPEG |
labelSize | Body | string | Possible values are: 4x6, 6x4, 4x8, 7x3, and Letter |
labelOrientation | Body | string | Possible values are: Portrait and Landscape |
customText1 | Body | string | |
customText2 | Body | string | |
customText3 | Body | string |
{
"labelType": "Base64",
"labelFileType": "PDF",
"labelSize": "4x6",
"labelOrientation": "Portrait",
"customText1": "Custom Text 1",
"customText2": "Custom Text 2",
"customText3": "Custom Text 3"
}
SpecialServiceParam
Description
Use these parameter when specifying any special services.
Parameters
param | in | Type | Comments |
---|---|---|---|
hazmatDescription | Body | string | |
hazmatPhone | Body | string | |
hazmatType | Body | string | Possible values are: AirEligibleEthanol, Class1, Class3, Class7_Radioactive, Class8_Corrosive, Class8_WetBattery, Class9_LithiumGroundOnly, Class9_LithiumReturns, Class9_LithiumMarked, Class9_DryIce, Class9_LithiumUnmarked, Class9_Magnetize, Div4.1, Div5.1, Div5.2, Div6.1, Div6.2, ExceptedQuantityProvision, GroundOnly, ConsumerCommodity, Lighters, LimitedQuantity, and SmallQuantityProvision |
codAmount | Body | number | |
registeredMailAmount | Body | number | |
insuranceAmount | Body | number | |
liveAnimalsType | Body | string | Possible values are: Bees, DayOldPoultry, AdultBirds, and Other |
{
"hazmatDescription": "string",
"hazmatPhone": "string",
"hazmatType": "AirEligibleEthanol",
"codAmount": 0,
"registeredMailAmount": 0,
"insuranceAmount": 0,
"liveAnimalsType": "Bees"
}
Change logs
You can preview all of the changes logs and breaking changes here
You can find out what changed in the public API from the v3 to v3.1 here