Getting Started with the APIs

1. Sign up or log in

Sign up for a free Pitney Bowes developer account at the Developer Hub Sign Up page. If you already have an account, log into your account at Developer Hub.

2. Get your API key and secret

Your developer account comes with a key and secret that give you access to the PB Shipping APIs on the sandbox test environment. The key and secret are unique to your account.

In your developer account, click the Ship menu, then click API Keys. Copy the sandbox key and secret.

3. Get your Developer ID

Your Developer ID is required by certain API calls.

In your developer account, click your username, then click Profile. Copy your Developer ID.

4. Get your default merchant’s Shipper ID

To get you started quickly, your developer account comes with a default merchant. You can use the default merchant for all your development and testing. As with all merchants, the default merchant is identified by its unique Shipper ID.

In your developer account, click the Ship menu, then click Onboarding Merchants. Copy the Shipper ID.

5. Ensure your system meets the TLS requirement.

The minimum supported security protocol for connection to the PB Shipping APIs is TLS v1.2. To test whether your environment supports TLS v1.2, issue the following GET operation:

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

A response of TLS_Connection_Success indicates your system meets the requirement.

6. Generate an OAuth token

Each request to the PB Shipping APIs requires an OAuth token. The token identifies and authenticates the developer account making the request.

To generate a token, first encode your API key and secret in the following format using a Base64 encoder. Be sure to include the colon between the key and secret.

<API_key>:<API_secret>

Generate the OAuth token using the following API call, replacing <base64_value> with the Base64-encoded value:

curl -X POST https://api-sandbox.pitneybowes.com/oauth/token \
-H "Authorization: Basic <base64_value>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"

The API returns an OAuth token in the access_token field, as shown in the example response below. The token is valid for 10 hours:

{
    "access_token": "mL3Ec6yp67uYGm0DnLiqPjux0AFY",
    "tokenType": "BearerToken",
    "issuedAt": "1498168771002",
    "expiresIn": "35999",
    "clientID": "a3cDEFghI1jK2LMnOP3qRstU4vWX5Yz",
    "org": "pitneybowes"
}

7. Begin testing the PB Shipping APIs

Test the APIs using the sandbox environment, which provides all API operations but does not use real money. The sandbox environment uses the following base URL:

https://api-sandbox.pitneybowes.com/shippingservices/

You can test the APIs directly or through the C# SDK. To use the SDK, see C# SDK.

A good place to start testing the APIs is with the Validate an Address API call.

To create additional merchants, see Merchant Enrollment.

8. Upgrade to production

To upgrade to a production account, you can either contact Pitney Bowes Support at ShippingAPISupport@pb.com or upgrade directly through Developer Hub. If you upgrade through Developer Hub, credit card is the only payment option available.

Printing Your First Production Label

When printing your first production label, you must ensure your postage account has sufficient funds to cover the cost of the label. In case of insufficient funds, you might encounter an error while your account is being funded.