Note

The Fulfillment APIs are coming soon.

Find an ASN

HTTP Requests

Return all ASN Data

POST /v1/receiving-asn/search

Return a Subset of ASN Data

POST /v1/receiving-asn/status/search

Summary

Use this operation to find ASNs (Advanced Shipment Notifications) based on your search criteria. The operation provides two HTTP requests. The Return all ASN Data request returns all the relevant fields in the ASN object for each result. The Return a Subset of ASN Data request returns a smaller payload focused on current status.

Request URLs

Return all ASN Data

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/v1/receiving-asn/search
Production: https://shipping-api.pitneybowes.com/shippingservices/fulfillment/v1/receiving-asn/search

Return a Subset of ASN Data

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/fulfillment/v1/receiving-asn/status/search
Production: https://shipping-api.pitneybowes.com/shippingservices/fulfillment/v1/receiving-asn/status/search

Query Parameters

Query parameters are optional.

Name

Description

page

The page number to return in the result set. Page numbering starts at 1.

Default value: 1

size

The number of results per page.

Default value: 20

Request Headers

Name


Description

Authorization

Required. OAuth token generated using the Generate an OAuth Token API.

X-PB-TransactionId

Required. A unique identifier for the request, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_).

Important: Ensure this is a unique id.

Request Elements

The POST request sends an object with the fields described here. Required fields are marked Required. All other fields are optional.

Name

Data Type

Description

clientId

String

Required. The client identifier assigned by Pitney Bowes.

sort

Array[String]

Defines a property upon which to sort and defines the sort order. Use the following syntax:

<property>-<sort_direction>

Where <property> is one of the following:

  • createDate

  • updateDate

  • pbCreateDate

  • pbUpdateDate

  • pbDeliveredDate

And <sort_direction> is either of the following:

  • asc: ascending

  • desc: descending

For example: "pbCreateDate-asc"

searchFields

Array[Object]

Defines search criteria. Each object in the array defines a search field and search values. The object takes the following elements:

  • name. Required. The name of the search field, entered as a String. Possible value:

    • receivingAsnIds

    • clientAsnIds

    • status

    • receivingNodes

    • pbCreateDate

    • pbUpdateDate

    • pbDeliveredDate

  • values. Required when name is set to receivingAsnIds, clientAsnIds, status, or receivingNodes. This field takes a String array. Enter the values to search for as separate Strings in the array.

  • from. Applies when name is set to pbCreateDate, pbUpdateDate, or pbDeliveredDate. Enter the beginning of the date range, as a String.

  • to. Applies when name is set to pbCreateDate, pbUpdateDate, or pbDeliveredDate. Enter the end of the date range, as a String.

If no date filter is specified, the API returns orders created in the last six months.

Response Elements

The response returns an object with the fields described here.

Name

Data Type

Description

totalPages

Number

The number of pages in the result set.

totalElements

Number

The number of ASNs in the result set.

first

Boolean

If true, this is the first page of the result set.

last

Boolean

If true, this is the last page of the result set.

size

Number

The number of ASNs per page in the result set.

page

Number

The page number to return. Page numbering starts at 1.

sort

Array[String]

The sort order.

asnList

Array[ASN Object]

The ASNs. Each object in the array is a separate ASN.

asnStatusList

Array[ASN Object]

The ASNs. Each object in the array is a separate ASN.

ASN Object

The asnStatusList array in the response contains the ASN object, which is described in the table below. (The table describes the ASN object for all operations that use it. Some fields in the table are labeled Required, meaning they are required in operations that send this object in the payload.)

Depending on which HTTP request you use, this operation returns all ASN data or a subset of the data, as shown in the Sample Request to Return a Subset of ASN Data.

Name

Data Type

Description

clientId

String

Required. The client ID assigned by Pitney Bowes.

brand

String

The manufacturer’s brand name for the item.

Maximum length: 30 characters

inboundType

String

Required. The type of inbound shipment. Possible values:

  • PO: Purchase Order

  • ASN: Advanced Shipment Notification

clientASNId

String

Required. A unique order ID assigned by the client.

Maximum length: 35 characters

purchaseOrderNumber

String

The purchase order number.

Maximum length: 35 characters

invoiceNumber

String

Reserved for future use.

receivingNode

String

Required. The ID of the facility that will receive the incoming shipment.

vendorDetails

Object

Required. The vendor.

vendorDetails.name

String

The name of the vendor.

Maximum length: 50 characters

vendorDetails.code

String

The unique code assigned to the vendor.

receivingASNId

String

RESPONSE ONLY. The ASN ID assigned by Pitney Bowes.

status

String

RESPONSE ONLY. The status of the ASN. Possible values:

  • CREATED

  • INPROGRESS

  • UPDATED

  • ARRIVED

  • COMPLETE

  • CANCELED

shippingDetails

Shipping Details Object

The carrier details for the shipment.

orderDate

String

Required. The date and time the ASN was ordered, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ

expectedDeliveryDate

String

Required. The date and time the shipment is expected to be delivered to Pitney Bowes, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ

pbCreateDate

String

RESPONSE ONLY. The date and time the ASN was created in the Pitney Bowes system, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ

pbUpdateDate

String

RESPONSE ONLY. The date and time the ASN was updated in the Pitney Bowes system, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ

pbDeliveredDate

String

RESPONSE ONLY. The date and time the ASN was delivered to Pitney Bowes, specified in the ISO 8601 format: YYYY-MM-DDThh:mm:ssZ

totalWeight

Weight Object

The weight of the shipment.

totalWeight.weight

Number

The weight.

totalWeight.unitOfMeasurement

String

The weight’s unit of measurement. Possible value:

  • LB: Pounds

totalVolume

Object

The volume of the shipment.

totalVolume.volume

String

The volume.

totalVolume.unitOfMeasurement

String

The volume’s unit of measurement. Possible values:

  • CubicInches

  • CubicFeet

  • CubicCentimeters

  • CubicMeter

fromAddress

Address Object

The address of the shipper.

toAddress

Address Object

Required. The address of the facility where the shipment will be received. The toAddress object requires the following fields:

  • name

  • addressLines

  • cityTown

  • stateProvince

  • postalCode

  • countryCode

billingAddress

Address Object

Reserved for future use.

additionalReferences

Array[Object]

Defines customer reference information for the ASN. The objects in the array take the following two fields:

  • name: Takes a String value that defines the reference the field.

    Maximum length: 50 characters

  • value: Takes a String value that defines the reference value.

    Maximum length: 255 characters

asnLines

Array[ASN Lines Object]

The line-level details of the ASN.

Sample Requests

See the following examples:

Sample Request to Return all ASN Data

This operation returns the full ASN object.

Example Request
curl -X POST ../v1/receiving-asn/search \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "NGST",
    "sort": [
        "pbCreateDate-asc"
    ],
    "searchFields": [ {
        "name": "status",
        "values": [
            "UPDATED"
        ]
    }, ... ]
}'
Example Response
{
    "totalPages": 1,
    "totalElements": 2,
    "first": true,
    "last": true,
    "size": 2,
    "page": 1,
    "sort": [
        "pbCreateDate-desc"
    ],
    "asnList": [ {
        "clientId": "NGST",
        "inboundType": "ASN",
        "clientASNId": "ORASN123-2112-11232",
        "purchaseOrderNumber": "Not Applicable",
        "receivingASNId": "ASN156A0029204893659052712,",
        "status": "CANCELLED",
        "receivingNode": "160",
        "vendorDetails": {
            "name": "Vendor ABC",
            "code": "VENDOR-121"
        },
        "shippingDetails": {
            "carrier": "UPS",
            "serviceId": "UPSG"
        },
        "orderDate": "2022-04-06T20:01:39Z",
        "expectedDeliveryDate": "2022-04-23T00:00:00Z",
        "pbCreateDate": "2022-04-07T14:09:21Z",
        "pbUpdateDate": null,
        "pbDeliveredDate": null,
        "toAddress": {
            "name": "Pitney Bowes Facility",
            "email": "pb@example.com",
            "addressLines": [
                "1200 WORLDWIDE BLVD"
            ],
            "cityTown": "Hebron",
            "stateProvince": "KY",
            "postalCode": "41048",
            "countryCode": "US"
        },
        "notes": "Note 1",
        "additionaReferences": [ {
            "name": "REFERENCE-1",
            "value": "Ref1"
        } ],
        "asnLines": [ {
            "lineId": 100,
            "purchaseOrderNumberLineId": 100,
            "PBlineId": 1,
            "sku": "PRODUCT-SKU-001",
            "inventoryType": "NEW",
            "originCountryCode": "US",
            "expectedQuantity": 100,
            "unitOfMeasurement": "EACH",
            "estimatedDeliveryDate": "2022-04-06T20:01:39Z",
            "costDetails": {
                "retailPrice": 15,
                "wholeSalePrice": 10,
                "unitCost": 15,
                "currency": "USD"
            }
        }, ... ]
    }, ... ]
}

Sample Request to Return a Subset of ASN Data

This operation returns a subset of fields in the ASN object.

Example Request
curl -X POST ../v1/receiving-asn/status/search \
-H "Authorization: Bearer <oauth_token>" \
-H "X-PB-TransactionId: <unique_identifier>" \
-d '
{
    "clientId": "A1234",
    "sort": [
      "pbCreateDate-desc"
    ],
    "searchFields": [ {
        "name": "receiving-asn",
        "values": [
            "ASN156A0029204893659052712",
            "ASN156A0029204893659061212"
        ],
        "to": "2022-02-06T20:01:39",
        "from": "2022-03-06T20:01:39"
    } ]
}'
Example Response
{
    "totalPages": 1,
    "totalElements": 2,
    "first": true,
    "last": true,
    "size": 2,
    "page": 1,
    "sort": [
      "pbCreateDate-desc"
    ],
    "asnStatusList": [ {
        "clientId": "NGST",
        "inboundType": "ASN",
        "clientASNId": "ORASN123-2112-11232",
        "purchaseOrderNumber": "Not Applicable",
        "receivingASNId": "ASN156A0029204893659052712,",
        "status": "CANCELLED",
        "receivingNode": "FACILITY-1",
        "vendorDetails": {
            "name": "Vendor ABC",
            "code": "VENDOR-121"
        },
        "orderDate": "2022-02-06T20:01:39Z",
        "expectedDeliveryDate": "2022-02-11T00:00:00Z",
        "pbCreateDate": "2022-02-07T14:09:21Z",
        "pbUpdateDate": null,
        "pbDeliveredDate": null
    }, ... ]
}

Error Codes

For lists of error codes returned by the Fulfillment APIs, please see 80-Prefix Error Codes (Fulfillment APIs).