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 
{
  "balance": 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 
{
  "isAutoBuy": true,
  "autoBuyAmount": 100,
  "autoBuyThreshold": 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 
{
  "accountId": "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
email 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 
{
  "key": "ShipmentId",
  "value": "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
  • You must approve the Terms and Conditions before using this account
  • This account has been closed
ACCOUNT.NOT_FOUND
  • Provided account id doesn't exist
ACCOUNT.PAYMENT_FAILED
  • Failed to {Debit/Credit} ${amount} from customer's CreditCard/ACH
ACCOUNT.VALIDATION_FAILED
  • Start date must be less than end date
  • Message is required
  • Account can only be closed when there are no active customer associated to your account
  • Account creation failed due to insufficiant MID(s). Contact Support
  • Account Creation Failed. Contact Support
  • The Terms & Conditions have already been accepted for this account
  • Please add your support email in company profile section
  • AccountType is not supported
  • Provided email address already exist
  • Incorrect credentials
  • Account already exists either for the provided email or company name
ACCOUNT.APP.AUTHENTICATION_FAILED
  • Server failed to authenticate the request. Make sure the value of the Authorization header is formed correctly
  • Invalid Api key or Api Secret
  • Token is not valid
ACCOUNT.APP.VALIDATION_FAILED
  • Test token not supported for carrier {Carrier}. It is supported only for USPS-eVS and USPS-ePostage carriers
ACCOUNT.BALANCE.VALIDATION_FAILED
  • Insufficient Fund
  • {Amount} must be greater than or equals to $1
ACCOUNT.PARENT.NOT_FOUND
  • Either ParentAccountId or PartnerAppId is empty or invalid
  • PartnerAppId is either empty, invalid or is not associated with parent
ACCOUNT.PARENT.VALIDATION_FAILED
  • You can register more apps only via your current partner {Partner}. Please contact customer support for more info
ADDRESS.VALIDATION_FAILED
  • Either save, verify or both should be set to true
  • Country Code {CountryCode} is not valid
  • Requested address is invalid
CARRIER.NOT_ACTIVE
  • {Carrier} is temporarily disabled by admin for all users
CARRIER.NOT_SUPPORTED
  • Provided carrier {Carrier} is not supported
CARRIERACCOUNT.NOT_ACTIVE
  • Provided CarrierAccount {CarrierAccount} is in requested status and waiting for approval
  • Provided CarrierAccount {CarrierAccount} has been disabled by the admin. Please contact support
CARRIERACCOUNT.NOT_FOUND
  • No CarrierAccount exists for the provided CarrierAccountId
  • No carrier accounts are associated with your app
  • Requested resource doesn't exist
  • The value of {carrierCode} is not valid
CARRIERACCOUNT.VALIDATION_FAILED
  • Invalid AppID
  • Carrier account already exist for the provided name
MANIFEST.NOT_FOUND
  • Requested Id doesn't exist
MANIFEST.NOT_SUPPORTED
  • Manifest is not supported for carrier {Carrier}
MANIFEST.VALIDATION_FAILED
  • Start date must be less than end date
  • {Key} with {Value} is not supported
  • Shipment(s) with invalid ship date should be removed from manifest request: {transaction_id}
PACKAGETYPE.NOT_ACTIVE
  • {packageType} is temporarily disabled by admin for all users
  • {Carrier} is temporarily disabled by admin for all users
PACKAGETYPE.NOT_FOUND
  • Requested resource doesn't exist
PACKAGETYPE.NOT_SUPPORTED
  • Package not found for carrier
  • {Carrier} does not support packagetype {packageType}
PACKAGETYPE.VALIDATION_FAILED
  • Dimension is required
  • Maximum weight should be {MaxWeight} lbs for {service}
  • Maximum Length+Grith should be {lengthPlusGirth} Inch for {service}
SERVICE.NOT_ACTIVE
  • {Service} is temporarily disabled by admin for all users
SERVICE.NOT_SUPPORTED
  • {Service} not supported by {Carrier}
SHIPMENT.BAD_REQUEST
  • {Module}: The {Module} field is required
SHIPMENT.NOT_FOUND
  • Shipment not found
  • OrderNotFound
SHIPMENT.VALIDATION_FAILED
  • Transaction Id already exists
  • Return label is only supported for domestic shipment
  • Customs Info and Customs Item are required
  • ShipDate must be set to today or a future day time
SHIPMENT.LABEL.VALIDATION_FAILED
  • The element 'eVSPriorityMailIntlRequest' has invalid child element 'Agreement'. List of possible elements expected: 'ContentType'
  • CustomText1 and CustomText2 are not allowed for International shipments
SHIPMENT.REFUND.NOT_SUPPORTED
  • Refund is not supported for carrier {Carrier}
SHIPMENT.REFUND.VALIDATION_FAILED
  • Refund not allowed as manifest has been already generated for this shipment
  • You have already initiated refund for this shipment
  • You cannot request a refund after 30 days of creating shipment
SHIPMENT.TRACKING.NOT_SUPPORTED
  • Tracking is not supported for carrier {Carrier}
SHIPMENTRATE.NOT_FOUND
  • Cannot retrieve data
  • Could not find rates for requested shipment
SHIPMENTRATE.VALIDATION_FAILED
  • Customs Info and Customs Item are required
  • {package} and {service} is not supported for {country} by {carrierType}
  • The combination of Service and Package Type is not suppported for the provided carrier
SPECIALSERVICE.NOT_SUPPORTED
  • Carrier {Carrier} does not support special service(s) {1}
SPECIALSERVICE.VALIDATION_FAILED
  • Invalid selection of special services
USER.NOT_FOUND
  • Provided email address doesn't exist
USER.VALIDATION_FAILED
  • Provided email address already exist, try signing in
  • Incorrect credentials
  • Security code expired
  • Please provide your username instead of email

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