API Overview

Introduction

The Pitney Bowes Complete Shipping APIs let you integrate shipping services from multiple carriers, including USPS and Newgistics, into your services and applications. The PB Complete Shipping APIs provide a unified interface for all carriers. The APIs follow the principles of the REST architectural style and use HTTP as the underlying protocol. Requests must be sent using HTTPS. Resource objects use JSON formatting.

Developer Account

To use the PB Complete 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.

Once you create a developer account, you can begin testing the APIs on the sandbox environment. You can use the default merchant that comes with your account or create additional merchants. For steps to create a developer account and begin testing the APIs, see the Getting Started page.

You can access your developer account at any time at Pitney Bowes Developer Hub. Developer Hub gives you access to your API keys, merchants, transaction history, and other information. If you upgrade to the production environment, Developer Hub also gives you access to your postage balances and payment options.

To upgrade to the production environment, you can contact Pitney Bowes Support at ShippingAPISupport@pb.com or upgrade directly through Developer Hub.

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

Merchant Accounts

When you print a label through the PB Complete Shipping APIs, you do so on behalf of a merchant. Your account comes with a default merchant, and you can add multiple additional merchants. Each merchant enrolled in your developer account has a unique Shipper ID that you reference when requesting the merchant’s transactions. For information on adding merchants to your developer account, see Merchant Accounts.

To request transactions for your real-life shippers, you must add them as merchants in your developer account. Once you do, you can use the APIs to print labels and request transactions on the shipper’s behalf.

API Environments

The PB Complete Shipping APIs provide the sandbox and production environments. Each environment has its own set of base URLs, as described below. 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 Requirement

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 Complete 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 Complete 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 Request Headers

All API requests require one or more HTTP headers. All requests require the Authorization header, which authenticates the developer to the PB Complete Shipping APIs. Please see a request’s documentation page for the required headers for that request.

Important: Do not pass a header that you do not intend to use. Instead, omit the header.

Important: Do not pass a header with the NULL value.

API Resources

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

API Responses

All API requests return an HTTP response that includes an HTTP status code, HTTP response headers, and, if applicable, a response body containing JSON-formatted data. The HTTP status code indicates the success or failure of the request. The request body, if present, contains either a resource object (returned by a successful request) or error information (if the request failed).

Errors

If an error occurs, the APIs return application-specific error information in the response body. Pitney Bowes provides a standard structure for returned errors. To use the standard structure, include the X-PB-UnifiedErrorStructure header set to true with each API request. For more information, see Error Object.

For a list of error codes and links to solutions, see Error Codes.

C# SDK

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

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

FAQs

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

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/.

Support

For support, see Contact Us.