API Overview

Introduction

The Pitney Bowes Shipping APIs let you integrate shipping services from multiple carriers, including USPS and Newgistics, into your services and applications. The PB Shipping APIs provide a unified interface for all carriers. The APIs follow the principles of the REST architectural style.

Developer Account

To use the PB Shipping APIs, you must have a Pitney Bowes developer account. You can create a free account and access the sandbox test environment by going to Pitney Bowes Developer Hub Signup.

Note: In the PB Shipping APIs, developers are also referred to as integrators.

Developer Hub

Once you have created a developer account, you can access it at any time at Pitney Bowes Developer Hub.

Merchants

To request transactions for your shippers, you must add them to your developer account as merchants. Once you add a merchant, you can use the PB Shipping APIs to print labels and request transactions on the merchant’s behalf. Each merchant has a unique Shipper ID that you reference when requesting the merchant’s transactions.

Your account can have multiple merchants. For information on adding merchants, see Merchant Enrollment.

Note: In the PB Shipping APIs, merchants are also referred to as shippers, customers, and clients.

API Environments

The PB Shipping APIs provide the sandbox and production environments. Each environment has its own set of base URLs, as described in the following sections. Note that the base URL is just one part of the API call:

Base URL

Sandbox Environment

The sandbox environment is a free test environment that is intended for all your development and testing work prior to deployment on production. Sandbox gives full access to all the API calls available on production but prints only test labels. Sandbox does not use real money. Your Pitney Bowes developer account provides free access to the sandbox environment.

The sandbox environment has daily limits on the number of requests you can make per API resource. The limits differ per resource but are large enough to accommodate daily testing and development. The limits do not accommodate load tests. If you exceed the daily limit for a resource, contact Support at ShippingAPISupport@pb.com and ask that your limit be reset for the day.

The following are the base URLs for sandbox. Note that token generation has a separate base URL:

Sandbox Base URL: https://api-sandbox.pitneybowes.com/shippingservices/

Sandbox Base URL for token generation: https://api-sandbox.pitneybowes.com/

Production Environment

To use the production environment you must upgrade your developer account. Production uses real money and prints labels used for real shipments. Never use the production environment for testing. Before you can upgrade to production, you must add a payment method to your developer account. Note that you cannot use your existing sandbox merchants in the production environment but instead must add the merchants to production separately.

The following are the base URLs for production. Note that token generation has a separate base URL:

Production Base URL: https://api.pitneybowes.com/shippingservices/

Production Base URL for token generation: https://api.pitneybowes.com/

See also What are the differences between sandbox and production?

HTTPS

All API requests must use HTTPS. HTTPS uses Transport Layer Security (TLS) to verify the identity of the accessed API server and to encrypt communications.

TLS Requirement

The minimum supported security protocol for connection to the PB Shipping APIs is TLS v1.2.

To test whether your servers support TLS v1.2: From your servers, issue the following GET operation. The operation retrieves a resource that accepts only the TLS v1.2 protocol:

curl -X GET https://api-test.pitneybowes.com/tlstest

The following response confirms your servers support TLS v1.2:

200 OK

TLS_Connection_Success

For help or questions, please contact us at ShippingAPISupport@pb.com.

Authentication

Each request to the PB Shipping APIs requires authentication via an OAuth token generated from the key and secret associated with your developer account. You pass the OAuth token in the Authorization header when making an API call. To generate a token, invoke the Generate OAuth Token API using the key and secret for the environment to be accessed (sandbox or production). Once generated, an OAuth token is reusable for 10 hours.

HTTP Headers

All API calls require one or more HTTP headers. All requests require the Authorization header, which authenticates the developer to the PB Shipping APIs. Please see each API call’s documentation for additional headers the API call uses. Do not pass a header that you do not intend to use. Instead, omit the header. Do not pass a header with the NULL value.

API Resources

For a list of all API resources, see the API Resources List. For descriptions of resource objects, see Core Resource Objects.

C# SDK

Pitney Bowes provides a C# interface to the PB Shipping APIs, available as a NuGet package.

For instructions on using the SDK, see any of the following:

API Status

Pitney Bowes provides a status portal with up-to-date status on the APIs as well as information on past incidents. To view current status of the APIs, go to https://apistatus.pitneybowes.com/.

Errors

For error codes and links to solutions see Error Codes.

FAQs

For answers to commonly asked questions, see the FAQs pages.

Support

For support, see Contact Us.