postalref

Parcel Data Exchange (PDX) API

Parcel Data Exchange, or PDX, is a USPS web and API application that lets customers send manifest files to USPS and receive outbound files from it. Parcel shippers use it to send Shipping Services Files and get extracts and error-warning reports through a secure web service, not FTP or SFTP.

Updated October 28, 202637 sources

What it is

PDX is one of the ways customers send Shipping Services Files to Product Tracking and Reporting. A Shipping Services File is the electronic file that holds the manifest and payment information. PDX skips the Data Transfer Services account setup, so a shipper can enroll online and start shipping the same day. PDX is free for business customers and third-party vendors.

Customers reach PDX through the Business Customer Gateway in a browser, or through an API connection. The API serves software that uses REST, and users can automate their requests with REST clients. A PDX mailbox is a third way in, for files meant for USPS employees rather than for processing.

Files also flow back: PTR generates outbound files for the customer, and PDX holds them for download.

How it works

Every PDX call carries a Business Customer Gateway username and password, sent with HTTP basic authentication. A successful request returns HTTP status 200.

A shipper's setup, then one manifest and its outbound files through the API.

  1. Create a Business Customer Gateway account at https://gateway.usps.com.
  2. Upload manifests with that account, which needs no other setup to upload.
  3. To receive outbound files, ask the Help Desk at (800) 522-9085 for Web Services.
  4. Send the manifest to https://pdx.usps.com/api/manifests with its environment, filename and contents.
  5. Keep the manifest ID PDX returns, which shows the upload succeeded.
  6. List outbound files not yet downloaded at https://pdx.usps.com/api/extracts.
  7. Download each outbound file once from https://pdx.usps.com/api/outbound-files/{id}.

PDX processes extract data once every 15 minutes.

API calls

The API has six web service calls, three for manifests and three for outbound files.

CallMethodURL
Upload a FilePOSThttps://pdx.usps.com/api/manifests
Get a List of Uploaded FilesGEThttps://pdx.usps.com/api/manifests
Get an Uploaded FileGEThttps://pdx.usps.com/api/manifests/{id}
Get a List of Outbound FilesGEThttps://pdx.usps.com/api/extracts
Get an Outbound FileGEThttps://pdx.usps.com/api/outbound-files/{id}
Get Multiple Outbound Files in a Zip FolderGEThttps://pdx.usps.com/api/extracts/zip

The outbound file list leaves out files already downloaded unless fullList is true. List responses come in pages of 100 by default and at most 500.

The mid parameter takes a whole Mailer ID, the number that identifies a mailer, and does not match part of one. Without it, the list covers every Mailer ID on the account.

USPS asks clients to add User Agent information to their requests to log company information. Without it, the PDX support team cannot tell who sent a failing call.

Environments

Each manifest upload names the environment its data goes to.

environmentData
TEMTest Environment for Mailers, for non-production test data
PRODProduction data

The Customer Acceptance Test environment, or CAT, is a separate PDX for testing uploads, lists and downloads without touching production data. A CAT account comes from a separate gateway at https://gateway-cat.usps.com. It needs its own username and password. CAT calls are the production calls with pdx-cat.usps.com in place of pdx.usps.com. Users also request separate Mailer IDs for CAT.

Manifest files

PDX forwards each uploaded manifest to internal USPS processing and records the time. PDX does not check what a manifest holds; downstream systems check the content.

PDX accepts five file extensions and rejects a manifest with any other.

  • .manifest, the one to use when in doubt
  • .consolid
  • .delivery
  • .subscribe
  • .podsub

A manifest filename should be 88 or fewer alphanumeric characters. PDX changes reserved characters in a filename, such as &, to underscores. A file named Sprockets&01%06082022083100.manifest is saved as Sprockets_01_06082022083100.manifest.

A manifest can be at most 250MB. The web application takes up to 25 files at once, with at most 250 MB in all.

An upload returns a JSON record of the manifest.

ElementMeaning
idThe PDX manifest identifier, used to download the manifest
environmentPRODUCTION or TEST ENVIRONMENT FOR MAILERS
createdTimeWhen the manifest was uploaded, in Central Time
sentTimeWhen PDX forwarded it to internal USPS processing, empty at first
filenameThe name PDX saved it under

Outbound files

Outbound files, also called extracts, are the files PTR generates for a customer. Their record layouts are in Publication 199, section 5.6 and Appendix G.

To receive them, the account must be configured in the USPS Program Registration system. The web application shows outbound files from the last 45 days for every Mailer ID on the account.

The fileType parameter takes a value from the File Type column of the API guide's Appendix 4.3. A value with spaces, such as Customer Daily Extract, may need its spaces encoded. Some outbound files arrive as ZIP files, and PDX may add suffixes to a filename to keep it unique.

USPS asks customers to request the list of outbound files every 15 minutes or less often. Each download of an outbound file raises its download count.

PDX mailboxes

A PDX mailbox moves files that are not processed or forwarded between external customers and USPS employees. A customer gets one when their Postal representative submits an approval form.

The mailbox API runs under https://pdx.usps.com/api. It lets a user upload, download and list files. PDX deletes mailbox files 45 days after upload and keeps no long-term copy.

Rules

All PDX Web Service calls require a USPS® Business Customer Gateway (BCG) username and password.

Every PDX call must carry a Business Customer Gateway username and password.

If you need to download Outbound Files (Extracts), your BCG account must be registered to a program and configured to Web Services.

A gateway account must be registered to a program and set to Web Services before it can download outbound files.

To configure the MID, you must either be the owner of that MID or you will need to be granted access by your account Business Service Administrator (BSA)

To receive outbound files for a Mailer ID, a user must own it or get access from the account's Business Service Administrator.

Manifest file contents must be alphanumeric text without encoding; special characters or encoding will cause manifest processing to fail.

A manifest must be plain alphanumeric text. Special characters or an encoding make its processing fail.

Overloading PDX with five or more manifest uploads per minute may cause your account to be deactivated.

Five or more manifest uploads in one minute may get the account deactivated.

Uploading the same named manifest repeatedly can delay processing and potentially cause data loss.

Uploading a manifest under the same name again and again can delay processing and may lose data.

PDX users are responsible for downloading and saving files for their own historic purposes.

PDX keeps manifests and outbound files for 45 days, then deletes them. Users are responsible for saving their own copies.

Executing both may result in duplicate extract downloads.

A client that runs both the list-and-download calls and the ZIP call may download the same extracts twice.

What goes wrong

A PDX account inactive for more than 90 days is deactivated automatically. An API call from a deactivated account returns Error 401: API Access Denied. An email to DTS-PDX@usps.gov can reactivate the account.

Three or more invalid login attempts within 24 hours lock the account. An expired gateway password makes API requests fail authentication, and it must be reset. The USPS help desk at (800) 522-9085 resets it.

PDX rejects a bad manifest at upload with an HTTP error code and message.

ProblemError
The manifest is emptyError 417: File is EMPTY!
The manifest is too smallError 412: File size below allowed size of {minimum size}
The manifest is too largeError 413: File exceeds maximum allowed size of {maximum size}
The extension is not validError 417: File Extension not valid
The filename is too longError 413: File name exceeds maximum allowed number of char in the file name size of {size} digits
The file is encoded, such as UTF-8-BOMError 415: Wrong encoding of the file. Char at position: X is Y=Z
A .subscribe manifest is sent to TEMError 415: File upload rejected. Cause: subscribe file type (extension); not accepted in TEM

Requests that use older protocols, such as HTTP1.0 or TLS1.0, fail. During maintenance or planned downtime, PDX is unavailable, and the client should retry later.

An outbound file downloaded more than 20 times returns HTTP 304 Not Modified from the API. The web application still downloads it.

PDX denies a ZIP request while another is running. After a failed ZIP, new ZIP requests fail for up to 10 minutes.

Files older than 45 days cannot be downloaded. A fromDate more than 45 days back is rejected.

Terms

Business Customer GatewayBCG, BCG (Business Customer Gateway)
where shippers can manage their mailing activity
Shipping Services FileSSF, Shipping Service Files
The electronic file containing all manifest and payment information.
Manifest
A manifest consists of one Header Record and one or more D1 Records.
Mailer IdentifierMID, Mailer IDs, Mailer Identification, Mailer Identification Number, USPS Mailer ID
MID is a unique 6- or 9-digit number that identifies the mailer or the mailer’s client.
Business Service AdministratorBSA, Business Services Administrator, Business Server Administrator, Business Systems Administrator
a representative within your company, for each service
Test Environment for MailersTEM, Testing Environment for Mailers, TEM (Testing Environment for Mailers)
The Test Environment for mailers (TEM) is a test platform designed to allow mailers to test their ability to submit electronic mailing information such as Full Service (FS) mailings to the Postal Service.
PDX CAT environment
separate from PDX Production and provides an isolated testing environment or “sandbox” for customers to test PDX file uploads, lists and downloads without impacting any Production data
Product Tracking and ReportingPTR, PTS, Product Tracking and Reporting system, Product Tracking Reporting, Product Tracking and Reporting (PTR) system, Product Tracking System
Each time a mailer submits a Shipping Services File, PTR processes and edits the file.

Documents

Quick Service Guides

User Guides

Contacts

  • The PDX team takes questions and comments at dts-pdx@usps.gov.
  • The USPS help desk is at (800) 522-9085.
  • The Help Desk at (877) 264-9693 answers questions about mailboxes and access.
  • The eVS help desk at eVS@usps.gov helps with outbound file information.

Sources