# 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 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.shipping360.pitneybowes.com/_bundle/openapi/receiving.yaml) ## Decode - [GET /api/v1/packages/tracking/decode](https://docs.shipping360.pitneybowes.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 - [POST /api/v1/trackingNumbers](https://docs.shipping360.pitneybowes.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 t - [POST /api/v1/packages/images](https://docs.shipping360.pitneybowes.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. - [GET /api/v1/packages](https://docs.shipping360.pitneybowes.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. - [POST /api/v1/packages](https://docs.shipping360.pitneybowes.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 multip - [POST /api/v1/packages/search](https://docs.shipping360.pitneybowes.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 b - [GET /api/v1/packages/{packageId}](https://docs.shipping360.pitneybowes.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 - [PUT /api/v1/packages/{packageId}](https://docs.shipping360.pitneybowes.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` o - [PATCH /api/v1/packages/{packageId}/archive](https://docs.shipping360.pitneybowes.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. Wh - [GET /api/v1/packages/tracking/{trackingNumber}](https://docs.shipping360.pitneybowes.com/openapi/receiving/packages/getpackagebytracking.md): This operation retrives a package using its unique tracking number. ## Carrier - [POST /api/v1/carriers](https://docs.shipping360.pitneybowes.com/openapi/receiving/carrier/getcarrierlist.md): This operation retrieves a list of carriers associated with the specific location/s. ## Inbound sites - [POST /api/v1/inboundsites](https://docs.shipping360.pitneybowes.com/openapi/receiving/inbound-sites/addinboundsite.md): This operation used for generating Inbound Site Id. - [GET /api/v1/inboundsites](https://docs.shipping360.pitneybowes.com/openapi/receiving/inbound-sites/getinboundsite.md): This operation is used to retrived the Inbound Sites. - [PUT /api/v1/inboundsites/{inboundSiteId}](https://docs.shipping360.pitneybowes.com/openapi/receiving/inbound-sites/updateinboundsite.md): This operation used to update Inbound Site. - [DELETE /api/v1/inboundsites/{inboundSiteId}](https://docs.shipping360.pitneybowes.com/openapi/receiving/inbound-sites/deleteinboundsite.md): This operation is used to delete Inbound Site. - [POST /api/v1/location/inboundsites](https://docs.shipping360.pitneybowes.com/openapi/receiving/inbound-sites/getlocationinboundsite.md): This operation is used to retrived Inbound Site against the location.