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.

A box with a Pandion label on a blue background.

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.

POST
{
   "serviceId": "EXPRESS",
   "origin": {
      "externalShipperFacilityId": "SHIPPER_HQ",
      "name": "null",
      "businessName": "Some Shipper"
   },
   "returnFacility": {
      "externalShipperFacilityId": "SHIPPER_RETURNS",
      "name": "null",
      "businessName": "Some Shipper"
   },
   "dimensions": {
      "lengthInches": 3,
      "widthInches": 2,
      "heightInches": 1
   },
   "weightOz": 16,
   "recipient": {
      "name": "Some Customer",
      "businessName": null,
      "address": {
         "streetLine1": "121 W Glebe Rd",
         "streetLine2": null,
         "city": "Alexandria",
         "postalCode": "07901",
         "countrySubdivisionCode": "US-VA"
      },
      "phoneNumber": null,
      "emailAddress": null
   },
   "deliverySignatureLevel": null,
   "customerRefNo": "123456",
   "customerRefNo2": null,
   "customerTags": {
      "orderNumber": "456",
      "orderDate": "2023-01-01T12:34Z"
   },
   "shippingInstructions": null,
   "reservedTrackingId": null,
   "hazardousMaterials": [
      {
         "identifier": {
            "type": "UNNumber",
            "value": "UN3481"
         },
         "description": "Lithium ion batteries contained in equipment including lithium ion polymer batteries"
      },
      {
         "identifier": {
            "type": "UNNumber",
            "value": "UN3090"
         },
         "description": "Lithium metal batteries including lithium alloy batteries"
      }
   ],
   "label": {
      "format": "ZPL",
      "dpi": "DPI_203"
   }
}
RESPONSE
{
    "trackingId": "2P100000073259728", 
    "inductionSortCenterName": "ABE-1", 
    "recipient": { 
        "name": "John Tester", 
        "businessName": "ACME Dynamite", 
        "phoneNumber": "18008008000", 
        "emailAddress": "test@example.com", 
        "address": { 
            "streetLine1": "1252 Pierson Drive", 
            "city": "Batavia", 
            "countrySubdivisionCode": "US-IL", 
            "postalCode": "60510-1499" 
        } 
     }, 
     "externalTrackingId": "1234567890", 
     "labelBase64": "CgoKXkZYI..."
}

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

POST
{
  "shipmentOrigin": { 
    "streetLine1": "110 W Pumping Station Rd", 
    "streetLine2": null, 
    "city": "Quakertown", 
    "postalCode": "18951", 
    "subdivisionCode": "PA", 
    "countryCode": "US" 
  }, 
  "shipmentDestination": { 
    "streetLine1": "1252 Pierson Drive", 
    "streetLine2": null, 
    "city": "Batavia", 
    "postalCode": "60510", 
    "subdivisionCode": "IL", 
    "countryCode": "US" 
  }, 
  "packageDimensions": { 
    "lengthInches": 1.0, 
    "widthInches": 1.0, 
    "heightInches": 1.0 
  }, 
  "packageWeightInOunces": 2.2 
 }
RESPONSE
{
  "shippingZone": 3, 
  "availableServices": [ 
    { 
      "serviceExternalId": "EXPRESS", 
      "serviceName": "Pandion Express", 
      "baseRateUsdCents": 205, 
      "surcharges": [ 
        { 
          "surchargeName": "Fuel Surcharge", 
          "surchargeRateUsdCents": 55 
        } 
      ], 
"discounts": [ 
        { 
          "discountName": "Discount #1", 
          "discountRateUsdCents": 40 
        } 
      ], 
      "totalRateUsdCents": 220, 
      "estimatedTransitTime": "P2D", 
      "billableWeightOunces": 16.0, 
      "billableWeightType": "SCALE" 
    } 
  ]
}

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 – Delivered

  • estimatedDeliveryDate 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 -   Final

  • typeName 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

GET

 curl -X GET "https://shipper.pandionpro.com/api/v1/packages/statuses?TrackingIDs=2P100000000082889" -H "accept: text/plain" -H "X-Api-Key: KeyValue"
RESPONSE
{
   "trackingId": "2P100000000082889",
   "deliveryProgress": 3,
   "estimatedDeliveryDate": "2021-10-14T00:00:00",
   "destination": {
      "state": "PA",
      "city": "QUAKERTOWN",
      "zip": "18951"
   },
   "externalTracking": {
      "externalTrackingId": "420189519274890306639700046663",
      "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=420189519274890306639700046663"
   },
   "packageStatuses": [
      {
         "status": 15,
         "timestamp": "2021-10-12T14:28:00",
         "name": "Delivered",
         "description": "Delivered.",
         "type": 2,
         "typeName": "Final",
         "role": 0,
         "details": "Delivered, In/At Mailbox, QUAKERTOWN, PA, 18951",
         "city": null,
         "state": null,
         "zip": null,
         "location": ""
      },
      {
         "status": 13,
         "timestamp": "2021-10-12T06:10:00",
         "name": "Out for delivery",
         "description": "Out for delivery today.",
         "type": 0,
         "typeName": "Progress",
         "role": 0,
         "details": "Out for Delivery, Expected Delivery by 9:00pm, QUAKERTOWN, PA, 18951",
         "city": null,
         "state": null,
         "zip": null,
         "location": ""
      }
   ]
}

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.

RESPONSE
The HTTP header will include a key/value pair that matches the customer provided value. An example would be: Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== The HTTP body of a sample Pandion web request to the customer webhook is shown below. 
{
   "trackingId": "2P100000000082889",
   "status": {
      "statusCode": "Delivered",
      "statusCodeInt": 15,
      "details": "Delivered, In/At Mailbox, QUAKERTOWN, PA, 18951"
   },
   "location": {
      "postalCode": "18951",
      "city": "QUAKERTOWN",
      "subdivisionCode": "PA"
   },
   "timestamp": "2021-10-12T14:28:00.943110300Z",
   "timezone": "America/New_York",
   "customerRefNo": "12345678",
   "customerRefNo2": null,
   "customerTags": {
      "orderNumber": "456",
      "orderDate": "2023-01-01T12:34Z"
   }
}

Ship with Pandion

Tap into our diversified network of 1M+ final-mile drivers with just one integration.

Talk to sales