API Reference
Pandion API Docs
Pandion customers can easily integrate with Pandion’s APIs for creating shipments, downloading labels, sending manifests, and getting shipment status for the packages in transit. Once integrated, customers will get a full end-to-end automated capability to ship packages via Pandion’s API.
The basic interface is a REST API endpoint for each action within the system with a simple HTTP GET or POST request made for each interaction. These endpoints can be easily tested in a browser.
Authentication
Authentication is required to use any API. Authentication is performed with an API key scheme. Add an X-Api-Key header to the HTTP request with the API key for the value.
Two API keys are generated upon shipper/customer registration in the system and provided by Pandion to the customer. One of these API keys is for the test or staging environment, and another is intended for production usage once the implementation is complete.
URLs for the staging environment are on the domain https://shipper.staging.pandionpro.com/, while URLs for the production environment are hosted on https://shipper.pandionpro.com/.
Please contact customer support to obtain the API key if necessary at support@pandionpro.com. The API key must be passed as an “x-api-key" value in the request’s header.
Create Shipment
This endpoint provides shippers with the ability to create shipments. The request contains information like package dimensions, recipient details and label configuration data. Only one package can be created per call, so multi-package shipments will require multiple calls to this API.
The "return address" shown on the label is determined by the "originExternalShipperFacilityId" field of the payload, which represents one of the shipper's facilities where shipments can originate. Please contact customer support if you need to register these facilities with Pandion.
A shipper must register at least one facility to ship packages through Pandion. Optionally, the caller may request a label be created and returned during shipment creation. Shipment creation will automatically perform address validation on the destination address.
For minor address corrections, such as changing the zipcode, the address in the request will simply be updated to a new address shown in the response. If the destination address cannot be validated, such as if it is missing a street number, then this API call will fail.
A successful call will respond with Pandion's tracking id of the package, along with a base64-encoded representation of the label in the requested format (if the label itself is requested).
Endpoint URL POST
STAGING: https://shipper.staging.pandionpro.com/api/v1/shipments/final-mile
PRODUCTION: https://shipper.pandionpro.com/api/v1/shipments/final-mile
Attributes
serviceId string
Should be set to the constant string “EXPRESS” in this API version.
origin <Origin>
An <Origin> object specifying the package’s origin location.
returnFacility string
Optional fromAddress to print on the label location, defaults to “origin” value if this is missing.
dimensions string
A <Dimensions> object specifying the package’s dimensions.
weightOz Double
The package’s weight in ounces.
recipient string
A valid <Recipient> object detailing the recipient’s information.
deliverySignatureLevel string
One of the following, representing the required signature level for delivery:
- null
- BASIC
- RECIPIENT
- ADULT
- ADULT_RECIPIENT
customerRefNo string
A string representing customer-specific data. This is printed on the label, and visible in package status data feeds and invoices.
customerRefNo2 string
A string representing customer-specific data. This is printed on the label, and visible in package status data feeds and invoices.
customerTags string
Mapping of custom data provided by the customer. This is not printed on the label, but is visible in package status feeds.
shippingInstructions string
Specific shipping instructions. Ex: “Handle with care.”
hazardousMaterials string
List of 1 or more hazardous materials contained in the package.
reservedTrackingId string
Use only if using a block of pre-reserved Pandion tracking IDs. If so, this is the Pandion tracking ID pre-assigned to the package.
label string
A <Label> object requesting a label be provided in the response.
origin object
externalShipperFacilityId string
Must be the ID of the shipper’s agreed-upon facility. Ex: “FACILITY_1”.
name string
The package sender’s name.
businessName string
The package sender’s business name.
dimensions object
lengthInches Double
Package’s longest dimension in inches.
heightInches string
Value in inches.
widthInches string
Packages shortest dimension in inches.
recipient object
name string
Recipient’s full name
businessName string
Recipient’s business name.
address <Address>
<Address> object
phoneNumber string
Recipient’s phone number.
emailAddress string
Recipient’s email address.
address object
streetLine1 string
First street line of recipient’s address.
streetLine2 string
Second street line of recipient’s address.
city string
Recipient’s city.
postalCode string
Recipient’s postal code.
countrySubdivisionCode string
A string representing the customer’s country and primary national subdivision. Ex: “US-IL”.
Materials object
identifier <Identifier>
Hazmat Identifier Object
description string
Description of the hazardous contents within the package.
tags object
<key> string
Any customized string that the shipper wants to associate with this package. There should be no more than 100 unique keys in the map.
<value> string
String value associated with this key for this package.
identifier object
type string
The type of identifier for the material. Pandion currently only supports one value here: “UNNumber”
value string
The actual identifying number for the hazardous material. Pandion currently only supports lithium ion batteries of the following types: UN3480, UN3481, UN3090, and UN3091, and limited quantity volatile substances of the following types: UN1266, UN1170, and UN3082.
label object
format string
One of the following string values: PDF PNG ZPL ZPL_UCC_DISABLED
dpi string
One of the following string values: DPI_203 DPI_300
businessName string
The package sender’s business name.
Error Messages
If the Create Shipment API fails to return a label, it will return a 4xx HTTP error with an error message explaining the reason for the failure. Most errors during development are caused by missing required parameters or using test data that’s not accurate for the real world.
There are three common errors that this API will return in regular usage:
1 - Recipient address did not pass address validation Pandion uses several address validation services to check all destinations, and requires that the destination address is a deliverable address. If Pandion can automatically fix the address, such as normalizing a city name or correcting the zipcode, the returned address in the JSON response might not match the requested address and no error is returned. If Pandion cannot fix the address, such as a missing street number, then this error message is returned.
2 - Valid destination address is outside coverage area Pandion does not currently deliver internationally, or to all regions of the United States, such as Alaska or Hawaii. If the destination zipcode is outside Pandion’s service area, this error message is provided. To obtain the latest coverage map, please contact support@pandionpro.com
3- No route to valid destination address. Some addresses might be inside of Pandion’s coverage but not currently serviceable from this origin location. If so, this error message is returned. secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Rates & Service Availability
This endpoint provides shippers the ability to query for rates and service levels for a single package. If multiple packages are grouped into a shipment, they will need to be queried separately and the rates summed. The request requires the dimensions of the package, as well as the origin and destination zipcode.
In response, a list of services and associated rates with each service is provided.
As an alternative to this API, many customers use a flat file (in CSV or another file format) to load rates and time-in-transit information into their systems. Please contact support@pandionpro.com if it is desired to use a flat file for rate shopping.
Endpoint URL POST
STAGING: https://shipper.staging.pandionpro.com/api/v1/service-availability-pricing
PRODUCTION: https://shipper.pandionpro.com/api/v1/shipments/service-availability-pricing
request Attributes
shipmentDestination <AddressDetails>
Recipient address. Must be a valid address within the Pandion coverage area.
shipmentOrigin <AddressDetails>
Shipper address. Must be one of the shipper addresses provided when registering with Pandion.
packageDimensions <PackageDetails>
Package with height, length, and width
packageWeightInOunces string
Value in ounces
deliverySignatureLevel Double
One of the following, representing the required signature level for delivery:
- null
- BASIC
- RECIPIENT
- ADULT
- ADULT_RECIPIENT
address details object
streetLine1 string
First street line of recipient’s address.
streetLine2 string
Second street line of recipient’s address.
city string
Recipient’s city.
postalCode string
Recipient’s postal code.
countrySubdivisionCode string
A string representing the customer’s country and primary national subdivision. Ex: “US-IL”.
package details object
lengthInches Double
Package’s longest dimension in inches.
heightInches string
Value in inches.
widthInches string
Packages shortest dimension in inches.
response Attributes
shippingZone Integer
1 to 8, based on the distance from origin to destination
availableServices <ServiceDetails>
List of services available for this package
service details object
serviceExternalId string
Service ID
serviceName string
Service Name
baseRateUsdCents Integer
Service rate in USD
surcharges <SurchargeDetails>
List of surcharges
discounts <DiscountDetails>
List of discounts
totalRateUsdCents Integer
Total rate in USD
estimatedTransitTime string
Time in transit from origin to destination for this service level. This is an ISO-8601 duration, e.g. P2D means a “Period of 2 days”.
billableWeightOunces string
The actual weight used for billing purposes, after rounding and doing dimensional calculations.
billableWeightType string
Either SCALE or DIMENSIONAL depending on how this package’s rate was calculated.
surcharge details object
surchargeName string
Surcharge Name
surchargeRateUsdCents Integer
Surcharge rate in USD
discount details object
discountName string
Discount Name
discountRateUsdCents Integer
Discount rate in USD
Get Package Status
This API provides status history for a specified list of package tracking IDs. Note that the amount of information returned is tied to the API Key. For an unauthenticated user, or for a package that is not associated with this particular shipper’s API Key, then only the publicly available information is released. For authenticated users querying for packages that they sent with Pandion, they will receive additional package statuses and metadata when using this API.
In addition to this approach, Pandion also supports a callback with webhooks, as well as fetching bulk package status updates in either CSV or EDI214 file formats over SFTP. The bulk package updates are provided on a 15 minute cadence. Please contact support@pandionpro.com to obtain credentials to the SFTP server to download these package status files.
For this API, it can be polled whenever a package status update is needed, without any rate limitations. When selecting the best approach to getting package status information, here’s the tradeoffs to consider:
- the package status API was designed to answer “Where is my order?” inquiries from recipients. It provides a complete history for up to 25 packages at a time. It will not work well to keep a separate database up-to-date on hundreds or thousands of packages, as the caller will need to poll the API to get all the updates necessary. It works well for recipient oriented integrations, like with Narvar or Aftership, or when interfacing with internal tools for customer service teams.
- the webhooks were designed to keep a database up-to-date with all the package updates. It scales much better in this area, as only the new events are pushed to the webhooks URL. It also works well for integrations that push data directly to recipients, such as notifications in an ecommerce app for packages going out-for-delivery.
- the SFTP bulk data download was designed to keep an independent database up-to-date for business analytics or invoice reconciliation purposes. For example, it should be used when loading data from multiple carriers into a database to compare On-time Delivery metrics.
Endpoint URL GET
STAGING: https://shipper.staging.pandionpro.com/api/v1/packages/statuses
PRODUCTION: https://shipper.pandionpro.com/api/v1/packages/statuses
request Attributes
trackingIds string
One or more package tracking IDs
response Attributes
trackingId Integer
One or more package tracking IDs
deliveryProgress Integer
Package delivery progress status:
0 - Label printed
1 - Package shipped
2 - Arrived at Pandion facility
3 - Arrived at carrier facility
4 - Out for delivery
5 – DeliveredestimatedDeliveryDate string
Estimated delivery date
destination <Destination>
City, State, and Zipcode of the destination
packageStatuses <PackageDetails>
Package status list for specified tracking ID
Package details object
status Integer
Package status
timestamp Datetime
Status date/time in local time
utcTimestamp Datetime
Status date/time in UTC time
name string
Status name
description string
Status description
type Integer
Package status type:
0 - Progress
1 - Incident
2 - FinaltypeName string
Package status type name
role Integer
Package status role
details string
Status details
city string
City where the package status event occurred
state string
State where the package status event occurred
zip string
Zipcode where package status event occurred
location string
Human-readable location of package status event
Package Status Webhook
The regular package status API described above lets the customer call Pandion to fetch the status for any package. In contrast to this, the Package Status Webhook will have Pandion push the package status updates to the customer directly whenever they occur.
In order for the Pandion Support team to configure this, two pieces of information must be provided for each webhook setup:
1 - Webhook Delivery URL: This is the location of the URL on the customer’s system that Pandion will call whenever a package status update is ready for delivery.
2 - Webhook Authorization Header Value: This is the value of the “Authorization” key passed in the HTTP header to the Delivery URL. This can be Basic, Digest, or any standard HTTP authorization value described in https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization
Pandion supports multiple webhooks for both our testing and production environments. For each webhook configured, Pandion will notify all webhooks whenever a customer package is updated within that environment.
request Attributes
trackingId string
The Pandion Tracking ID for the package to be updated
status <PackageStatus>
Package status details
location <StatusLocation>
Location of the package status event
timestamp ISO 8601 timestamp
UTC timestamp of the package status event
timezone tz database timezone
Timezone where the event occurred
customerRefNo string
First customer reference number provided during shipment creation
customerRefNo2 string
Second customer reference number provided during shipment creation
customerTags <Tags>
Mapping of customized data provided by shipper during shipping creation.
Package status object
statusCode string
Package status name
statusCodeInt Integer
Package status identifier
details string
Additional details around package status event
status location object
city string
City where the package status event occurred
subdivisionCode string
State where the package status event occurred
postalCode string
Zipcode where the package status event occurred
response Attributes
Pandion expects to receive a 2XX HTTP response code from the customer url.
