Parcel Protection Reports

HTTP Request

GET /v1/parcel-protection/{developerId}/policies

Summary

This operation retrieves the policy status and other information on the Parcel Protection policies you have purchased for your shipments.

Prerequisites

To use this API, both your developer account and the merchant’s account must be enabled for Parcel Protection. For instructions, see Enabling Parcel Protection Coverage.

Path Parameter

Name Description
developerId
Required. Your Pitney Bowes developer ID.

Query Parameters

Query parameters are optional.

Name Description
policyCreatedFromDate The beginning of the date range. Specify this value in UTC using the ISO 8601 standard. You must include both date and time, and you must end the time with Z to indicate a zero offset.
policyCreatedToDate

The end of the date range. Specify this value in UTC using the ISO 8601 standard. You must include both date and time, and you must end the time with Z to indicate a zero offset. For example:

toDate=2018-01-02T23:59:00Z

policyReferenceId The unique identifier for the PB Parcel Protection policy.
parcelTrackingNumber The parcel tracking number of the shipment that the policy applies to.
merchantId The merchant’s Shipper ID. This is the value of the postalReportingNumber element in the Merchant Object.
policyStatus Whether the policy is active or voided.
size

The number of transactions to return per page in the result set.

Default: 20

page The index number of the page to return. Page index numbering starts at 0. Specifying page=0 returns the first page of the result set.
sort

Defines a property to sort on and the sort order. Sort order can be ascending (asc) or descending (desc). Use the following form:

sort=<property_name>,<sort_direction>

For example:

sort=policyDate,desc

Request Headers

Name
Description
Authorization Required. OAuth token generated using the Generate an OAuth Token API.
X-PB-TransactionId

A unique identifier for the transaction, up to 25 characters.

Important: You must ensure this is a unique id.

X-PB-UnifiedErrorStructure Recommended. Set this to true to use the standard error object if an error occurs.

Response Elements

Name Data Type Description
content Array[Policy Object] The parcel protection policies. Each object in the array is a separate policy.
totalPages Number Total Number of pages in the result set.
totalElements Number Total number of transactions in the result set.
last Boolean If true, this is the last page of the result set.
first Boolean If true, this is the first page of the result set.
numberOfElements Number The number of transactions in the current page.
sort Array[Object] The property used to sort the transactions and the sort order.
size Number The number of transactions per page in the result set. The default size is 20.
number Number The index number of the page being returned. Page index numbering starts at 0. If number is set to 4, this is the 5th page of the result set.

Response Elements: Content Object

Each object in the content array describes a Parcel Protection policy.

Name
Data Type Description
transactionID String A unique string that identifies the transaction.
developerId String Your Pitney Bowes developer ID.
subscriptionAccNo String The type of Parcel Protection account.
clientTransactionId String Your Pitney Bowes developer ID joined by an underscore (_) to the value entered in the X-PB-TransactionId header in the Request Parcel Protection Coverage API.
policyDetails Object An object containing the policy’s status, costs, and other information.
    policyId String The unique identifier for the PB Parcel Protection policy. Use this identifier when you want to reference this policy.
    policyDate String The date and time the Parcel Protection policy was created, returned in UTC/GMT time in the ISO 8601 format.
    policyStatus String

The status of the policy. The possible values are:

  • ACTIVE
  • VOIDED
    claimStatus String

The status of a claim against the policy. The possible values are:

  • Null
  • Denied
  • Requested
  • Approved
    claimStatusUpdateDate String The date and time the claim status was updated, returned in UTC/GMT time in the ISO 8601 format.
    valueOfGoods BigDecimal The value of the goods being insured.
    insuranceValue BigDecimal The amount being insured.
    premiumValue BigDecimal The policy premium in USD. The policy premium includes the base premium and a technology fee.
    basePremium BigDecimal The base premium value in USD.
    technologyFee BigDecimal The technology fee in USD.
    currencyCode String The ISO currency code. For example: USD, CAD, EUR
    mailClass String The abbreviated name of the carrier-specific service. For abbreviations, see the Services table on the carrier’s reference page.
    mailClassOption String The parcel type. For supported parcel types, see the carrier’s reference page.
shipmentDetails Object An object containing information about the policy’s shipment.
    shipmentDate String The date of the shipment in ISO 8601.
    shipmentTransactionId String  
    shipmentId String  
    parcelTrackingNumber String The shipment’s tracking number.
    carrier String The carrier used to ship the parcel.
    amount BigDecimal Invoice value of the shipment. This might differ from the requested coverage value.
    packageLength BigDecimal The parcel length, in inches.
    packageWidth BigDecimal The parcel width, in inches.
    packageHeight BigDecimal The parcel height, in inches.
    weight BigDecimal The parcel weight, in ounces.
    zone String The shipment zone.
shipperInfo Object An object containing information about the merchant.
    shipperID String The merchant’s Shipper ID.
    firstName String The merchant’s first name.
    middleName String The merchant’s middle hame.
    lastName String The merchant’s last name.
    company String The merchant’s company name.
    email String The merchant’s email address.
    phoneNumber1 String The merchant’s primary phone number.
    phoneNumber2 String The merchant’s secondary phone number.
    faxNumber String The merchant’s fax number.
    address Object An object containing the merchant’s address.
consigneeInfo Object The buyer’s information.
    shipperID String An ID assigned by the merchant to the buyer.
    firstName String The buyer’s first name.
    middleName String The buyer’s middle hame.
    lastName String The buyer’s last name.
    company String The buyer’s company name.
    email String The buyer’s email address.
    phoneNumber1 String The buyer’s primary phone number.
    phoneNumber2 String The buyer’s secondary phone number.
    faxNumber String The buyer’s fax number.
    address Object An object containing the buyer’s address.
createdAt String The date and time this record was created, in ISO 8601.
updatedAt String The date and time this record was updated, in ISO 8601.
parcelProtectionAccountID String Parcel Protection account ID, if applicable.
parcelProtectionProgramID String Parcel Protection program ID, if applicable.

Sample Request

curl -X GET .../v1/parcel-protection/<developerId>/policies \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: ABC123" \
-H "X-PB-UnifiedErrorStructure: true"

Sample Response

{
    "content": [ {
        "transactionId": "44397664_ABC123_1e142741-c3a1-4b51-bfe5-15c6c39e70b4",
        "developerId": "44397664",
        "subscriptionAccNo": "23456789",
        "clientTransactionId": "44397664_ABC123",
        "policyDetails": {
            "policyId": "IPPOL000000123456789",
            "policyDate": "2019-11-01 18:32:44.101+0000",
            "policyStatus": "ACTIVE",
            "claimStatus": null,
            "claimStatusUpdateDate": null,
            "valueOfGoods": 1000.000,
            "insuranceValue": 1000.000,
            "premiumValue": 7.500,
            "basePremium": 7.250,
            "technologyFee": 0.250,
            "currencyCode": "USD",
            "mailClass": "PM",
            "mailClassOption": "PKG"
        },
        "shipmentDetails": {
            "shipmentDate": null,
            "shipmentTransactionId": null,
            "shipmentId": null,
            "parcelTrackingNumber": "9405809898647123456789",
            "carrier": "USPS",
            "amount": null,
            "packageLength": null,
            "packageWidth": null,
            "packageHeight": null,
            "weight": null,
            "zone": null
        },
        "shipperInfo": {
            "shipperID": "9024324564",
            "firstName": "John",
            "middleName": "James",
            "lastName": "Smith",
            "company": null,
            "email": "company@example.com",
            "phoneNumber1": "1234567890",
            "phoneNumber2": null,
            "faxNumber": null,
            "address": {
                "street1": "545 Market St",
                "street2": "",
                "street3": "",
                "city": "San Francisco",
                "region": "CA",
                "country": "US",
                "postalCode": "94105-2847"
            }
        },
        "consigneeInfo": {
            "shipperID": "myBuyer0048",
            "firstName": "Mary",
            "middleName": "Anne",
            "lastName": "Jones",
            "company": null,
            "email": "shop@example.com",
            "phoneNumber1": "1234567890",
            "phoneNumber2": "1234567890",
            "faxNumber": null,
            "address": {
                "street1": "284 W Fulton",
                "street2": "",
                "street3": "",
                "city": "Garden City",
                "region": "KS",
                "country": "US",
                "postalCode": "67846"
            }
        },
        "createdAt": "2019-11-01 18:37:56.356+0000",
        "updatedAt": "2019-11-01 18:37:56.356+0000"
    },
    { ... }
    ],
    "last": false,
    "totalElements": 61,
    "totalPages": 4,
    "first": true,
    "numberOfElements": 20,
    "sort": [ {
            "direction": "DESC",
            "property": "policyDetails.policyDate",
            "ignoreCase": false,
            "nullHandling": "NATIVE",
            "descending": true,
            "ascending": false
    } ],
    "size": 20,
    "number": 0
}

Error Codes

For a list of all PB Shipping APIs error codes, please see Error Codes.