# Receiving APIs The **Pitney Bowes Receiving APIs** help manage packages from the moment they arrive at a facility until they are delivered to the final recipient. These APIs allow organizations to track, update, and store package details, helping to manage internal package handling efficiently. **Why Receiving APIs** 1. Track every package from arrival to final delivery. 2. Maintain a complete history of package status and movements. 3. Update the current package details. 4. Quickly find packages within the system using tracking numbers or other search criteria. **How Receiving APIs Work** When a package arrives at a facility, it may have a barcode that either includes a tracking number or does not. 1. If the **barcode contains a tracking number**: - The system searches for an existing package with the same tracking number. - If no package exists, a new package entry is created. 2. If the **package does not have a tracking number**: - A new tracking number is generated. - A new package entry is created. 3. Once package added to the system, It can be tracked, and its details can be updated to reflect its current status, location, or latest activity. 4. When the package is delivered to its destination, it can be archived for record-keeping. **Step-by-Step Workflow for Receiving APIs** This section provides a structured process for handling packages using the Pitney Bowes Receiving APIs. **Step 1: Decode the Barcode on a Package** 1. Packages with barcodes must be scanned first. 2. If the barcode contains a tracking number, use the [Decode Tracking Number](/openapi/receiving/decode/decodetrackingnumber) API to extract key details, such as: - Tracking number - Package type - Carrier service - Sender and receiver information - Current location 3. The Decode API supports 2D barcodes. **Step 2: Generate a Unique Tracking Number (If Required)** 1. If a package does not have a tracking number, the user first needs to assign a unique tracking number to the package. 2. The [Generate Tracking Number](/openapi/receiving/packages/createtrackingnumber) API creates a unique tracking number, which serves as an identifier throughout the package lifecycle. **Step 3: Add Package to the System** 1. Every package must be added to the system using its tracking number. 2. The system verifies that no duplicate tracking number exists. If a duplicate is found, an error is returned. 3. Upon successful addition, the package is assigned a unique Package ID for tracking. 4. The package is linked to relevant sender and receiver information. **Additional Information to add a Package:** **Tracking Number:** Each package must have a unique tracking number. **Contact ID:** - Contacts can be of three types: Sender, Receiver, and Given To. - Contacts must be created first using the [Add Contact](/openapi/addressbook/contact/addcontact) API (Address Book APIs). - Once added, the system generates a unique Contact ID for each contact, which is used when adding a package. **Custom Fields:** Additional custom details can be associated with the package. Fetch the Custom fields using the [Get Custom Field](/openapi/customfields/custom-fields/getcustomfield) API. **Inbound Site ID:** If the package needs to be linked to an inbound site location, fetch the associated Inbound Site ID using the [Get Inbound Sites](/openapi/receiving/inbound-sites/getinboundsite) APIs. **Step 4: Search for a Package in the System** Users can find specific packages using the [Search Package](/openapi/receiving/packages/searchpackage) API by entering tracking numbers, statuses, or metadata. This API locates packages that are in transit, waiting for pickup, or already delivered. **Step 5: Retrieve Package Details** Use the [Get Package](/openapi/receiving/packages/getpackagepackageid) API to fetch detailed information about a package. 1. The package can be retrieved using either its unique package ID or tracking number. 2. The response includes the package's history, current status, current location, and latest activity. **Step 6: Update Package Information** Packages undergo several status changes as they move through the system. The [Update Package](/openapi/receiving/packages/updatepackage) API allows to: 1. Update package details such as status, location, sender, receiver, and confirmation methods. 2. Mark packages as DAMAGED, ARCHIVED, RECEIVED, or DELIVERED. 3. Record location changes, damage reports, or special handling requirements. 4. Attach images for proof of receipt. 5. Assign a package to a specific recipient within an organization. **Step 7: Archive a Package** 1. Once a package has reached its final recipient, it can be archived for record keeping using the [Archive Package](/openapi/receiving/packages/archivepackage) API. 2. The Archive Package API removes the package from active workflows while maintaining its record for future reference. **Retrieve Carrier List** 1. Get a list of carriers associated with specific locations using [Carrier List](/openapi/receiving/carrier/getcarrierlist) API. 2. This helps in knowing which carriers are responsible for incoming shipments at different facilities Version: 1.0.0 ## Servers ``` https://api-dev.sendpro360.pitneycloud.com/pitneytrack ``` ``` https://api-qa.sendpro360.pitneycloud.com/pitneytrack ``` Sandbox Server ``` https://api-sandbox.sendpro360.pitneybowes.com/pitneytrack ``` Production Server (uses live data) ``` https://api.sendpro360.pitneybowes.com/pitneytrack ``` ## Security ### bearerAuth Type: http Scheme: bearer ## Download OpenAPI description [Receiving APIs](https://docs.sendpro360.pitneycloud.com/_bundle/openapi/receiving.yaml) ## Decode APIs for decoding package tracking numbers from supported barcode formats. These APIs extract package-related details such as carrier information, receiver identifiers, and package type. ### Decode Tracking Number - [GET /api/v1/packages/tracking/decode](https://docs.sendpro360.pitneycloud.com/openapi/receiving/decode/decodetrackingnumber.md): This operation decodes a tracking number from a barcode, extracting package details like carrier information, receiver Id, and package type. It supports 2D barcodes. ## Packages APIs for managing package records throughout their lifecycle. These APIs support operations such as generating tracking numbers, creating package records, uploading package images, retrieving package details, searching packages, updating package information, archiving packages, and retrieving packages by tracking number. ### Generate Tracking Number - [POST /api/v1/trackingNumbers](https://docs.sendpro360.pitneycloud.com/openapi/receiving/packages/createtrackingnumber.md): This API generates a unique tracking number required to add a package.These numbers serve as identifiers for packages throughout their lifecycle. Use this API when a package does not already have a tracking number. ### Create Image - [POST /api/v1/packages/images](https://docs.sendpro360.pitneycloud.com/openapi/receiving/packages/createimage.md): This operation creates an image and provides details about the created image. The image data must be provided in Base64 format in the request body. ### Search Package - [GET /api/v1/packages](https://docs.sendpro360.pitneycloud.com/openapi/receiving/packages/searchpackage.md): This operation retrieves a list of packages based on the specified search criteria, such as tracking numbers, status, or associated metadata. ### Add Package - [POST /api/v1/packages](https://docs.sendpro360.pitneycloud.com/openapi/receiving/packages/createpackage.md): This API operation creates a new package in the system and records its associated activity. Each package requires a unique tracking number to be added successfully. If an attempt is made to add multiple packages using the same tracking number, the API will return an error. When to use Add Package API? - For packages with a barcode - Customers scan the barcode label on the package and decode the tracking number using the Decode Tracking Number API. - Use the Get Package by Tracking Number API to check if the package already exists in the system: - If the package is not found, use Add Package API to add the package in the system. - For packages without a barcode or tracking number, generate a unique tracking number using the Generate Tracking Number API and then add the package using Add Package API. ### Search Packages with Custom Header Mapping - [POST /api/v1/packages/search](https://docs.sendpro360.pitneycloud.com/openapi/receiving/packages/searchpackages.md): This operation returns package records based on the requested custom header mapping. The request body contains package field names as keys and custom header labels as values. These header labels can be used to display the returned package data with user-defined column names. ### Get Package - [GET /api/v1/packages/{packageId}](https://docs.sendpro360.pitneycloud.com/openapi/receiving/packages/getpackagepackageid.md): This operation retrive detailed information or activities of a specific package using its unique packageId. The packageId is generated when a package is added to the system ### Update Package - [PUT /api/v1/packages/{packageId}](https://docs.sendpro360.pitneycloud.com/openapi/receiving/packages/updatepackage.md): This operation updates the details of an existing package using its unique packageId. Updates include the latest activity performen on the package or current status of the package such as RECEIVED or DELIVERED as well as recording additional information like damage reports, location changes, or other relevant package events. ### Archive Package - [PATCH /api/v1/packages/{packageId}/archive](https://docs.sendpro360.pitneycloud.com/openapi/receiving/packages/archivepackage.md): This operation marks the specified package as archived by updating its archived status to true. Archiving a package indicates that its lifecycle is complete, and it is no longer actively tracked. While archived packages are removed from active workflows, their records remain accessible for future reference ### Get Package By Tracking - [GET /api/v1/packages/tracking/{trackingNumber}](https://docs.sendpro360.pitneycloud.com/openapi/receiving/packages/getpackagebytracking.md): This operation retrives a package using its unique tracking number. ## Carrier APIs for retrieving carrier information associated with one or more locations. These APIs help identify the carriers available for package processing and support location. ### Retrive Carrier List - [POST /api/v1/carriers](https://docs.sendpro360.pitneycloud.com/openapi/receiving/carrier/getcarrierlist.md): This operation retrieves a list of carriers associated with the specific location/s. ## Inbound sites APIs for managing inbound site records and their association with locations. Inbound sites represent physical or logical intake points where packages are received and processed. These APIs support operations such as Creating and managing inbound site hierarchy, retrieving inbound sites by filters (location, hierarchy, status), deleting inbound sites, and retrieving inbound sites mapped to specific locations. ### Add Inbound Site - [POST /api/v1/inboundsites](https://docs.sendpro360.pitneycloud.com/openapi/receiving/inbound-sites/addinboundsite.md): This operation used for generating Inbound Site Id. ### Get Inbound Site - [GET /api/v1/inboundsites](https://docs.sendpro360.pitneycloud.com/openapi/receiving/inbound-sites/getinboundsite.md): This operation is used to retrived the Inbound Sites. ### Update Inbound Site - [PUT /api/v1/inboundsites/{inboundSiteId}](https://docs.sendpro360.pitneycloud.com/openapi/receiving/inbound-sites/updateinboundsite.md): This operation used to update Inbound Site. ### Delete Inbound Site - [DELETE /api/v1/inboundsites/{inboundSiteId}](https://docs.sendpro360.pitneycloud.com/openapi/receiving/inbound-sites/deleteinboundsite.md): This operation is used to delete Inbound Site. ### Get against locationId - [POST /api/v1/location/inboundsites](https://docs.sendpro360.pitneycloud.com/openapi/receiving/inbound-sites/getlocationinboundsite.md): This operation is used to retrived Inbound Site against the location.