# Pitney Locker APIs The Pitney Locker APIs help manage smart locker operations for package delivery, returns, and asset drop-off workflows. These APIs allow external organizations to automate secure, contactless locker operations by integrating with Pitney Bowes smart lockers. By integrating these APIs into your system, you can automate end-to-end locker workflows—from retrieving available locker banks and reserving locker units to remotely opening lockers, depositing packages, retrieving reservation details and releasing locker units after use . **Why Use Pitney Locker APIs** - Enable contactless, secure package deliveries - Automate locker assignment and release - Support forward delivery and return/drop-off workflows - Track which locker unit is assigned to which package - Simplify mailroom or internal delivery operations - Retrieve locker availability and locker status information **How Pitney Locker APIs Work** The Pitney Locker APIs are designed to manage smart locker workflows—from retrieving available locker banks and reserving locker units to depositing packages and freeing locker units after completion. The APIs support two primary workflows: - Forward delivery workflow (transactionType: deliver) - Return or asset drop-off workflow (transactionType: return) A user (typically a mailroom operator or system) can use these APIs to: 1. Look up locker banks 2. Check available locker unit sizes 3. Reserve locker units 4. Open locker units remotely 5. Deposit packages into locker units 6. Retrieve reservation details 7. Free locker units after use 8. Monitor locker unit operational status **Step-by-Step Workflow for Pitney Locker APIs** **Step 1: Retrieve Available Locker Banks** Use the [Get Locker Banks](/openapi/lockers/locker-bank/getlockerbanks) or [Get Locker Bank by Locker Bank ID](/openapi/lockers/locker-bank/getlockerbankdetails) APIs to retrieve the list of available locker banks at a facility. Filter by: - `locationId`: To get lockers for a specific location - `lockerBankId`: To retrieve a specific locker bank by ID. One location can have multiple banks. - Each locker bank has a unique `lockerBankId`, used in subsequent API calls. **Step 2: Get Locker Sizes for a Locker Bank** Use the [Get Locker Sizes API](/openapi/lockers/locker-bank/lockersizes) to retrieve the available locker unit sizes in a locker bank (e.g., small, medium, large) along with their availability status. - You need to pass the `lockerBankId` retrieved in Step 1 as a path parameter. **Step 3: Reserve a Locker Unit** Once you know a locker unit is available, use the [Reserve Locker Unit API](/openapi/lockers/locker-unit/createreservation) to create a reservation. This workflow is typically used for forward delivery operations and internally uses `transactionType: deliver` Required fields include: - `lockerBankId` (path parameter) - Package tracking number - Locker size preference (e.g., small) - Recipient identification (contact ID and type) - Reservation Expiry Time If a locker is successfully reserved, a **locker unit ID** will be returned in the response. **Return and Asset Drop-off Reservations** For return or asset drop-off workflows, use the Create Return Reservation API. This workflow uses `transactionType: return` In this workflow a depositor places a package or asset into a locker. The reservation details include the intended receiving contact (e.g., store or department) and the depositor contact (e.g., customer or recipient) who will drop off the package or asset. Once the reservation is created, the depositor can use the provided locker unit information to complete the return drop-off, and the receiving contact can retrieve the item from the locker for processing. The reservation can include: - Receiving contact information - Depositor contact information - Tracking details - Reservation expiry information **Step 4: Open a Locker Unit** Use the Open Locker Unit API to remotely unlock a locker unit before package deposit or return drop-off operations. This API is used by mailroom operators or authorized users to open the locker unit door for secure, contactless package handling. **Step 5: Add or Update Deposit Information** After reserving the locker unit, deposit the parcel inside the locker using [Add/Update Deposit API](/openapi/lockers/locker-unit/updatedeposit). Using the same API, user can update the deposit information for example userId of the user. This updates the locker reservation to reflect: - Parcel successfully deposited - Deposit timestamp - depositExpiryTime (Once expired, the parcel may be removed or handled according to facility policy.) - Parcel pickup code (Pickup Code will only be provided to the `contactType: recipient`. For `contactType: department` the recipients will pick the parcel by providing their `personalId`) You need to pass: - `lockerBankId` (path parameter) - `lockerUnitId` (path parameter) **Step 6: Retrieve Reservation Details** These APIs help external systems, operators, or recipients retrieve reservation details. - [Get Reservations by Contact](/openapi/lockers/locker-unit/getreservationlist): Retrieve all reservations linked to a specific recipient/contact. - [Get Reservation by Tracking Number](/openapi/lockers/locker-unit/getreservation): Retrieve reservation details using the package tracking number. **Step 7: Update Reservation** If reservation details need to be changed (e.g., expiry time, contact details, metadata), use the [Update Reservation API](/openapi/lockers/locker-unit/updatereservation). You need to pass: - `lockerBankId` (path parameter) - `lockerUnitId` (path parameter) **Step 7: Free the Reserved Locker Unit** Use the [Free Reserved Locker Unit API](/openapi/lockers/locker-unit/freereservation) to cancel the existing reservation. This makes the locker unit available for the next package. You need to pass: - `lockerBankId` (path parameter) - unit to be freed - `lockerUnitId` (path parameter) **Note:** Some Pitney Locker workflows require recipient, department, or depositor contact details. These contacts are managed through the Address Book APIs. For more information, see [Address Book APIs](/openapi/addressbook/contact/addcontact). Version: 1.0.0 ## Servers Sandbox Server ``` https://api-sandbox.sendpro360.pitneybowes.com/parcelpoint ``` Production Server (uses live data) ``` https://api.sendpro360.pitneybowes.com/parcelpoint ``` ## Security ### basicAuth Type: http Scheme: basic ### bearerAuth Type: http Scheme: bearer ## Download OpenAPI description - [Pitney Locker APIs](https://docs.shipping360.pitneybowes.com/_bundle/openapi/lockers.yaml) ## Locker Bank - [GET /api/v1/lockerBanks](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-bank/getlockerbanks.md): This API operation returns a list of all available locker banks where packages can be deposited for recipient pickup. - [GET /api/v1/lockerBanks/{lockerBankId}/lockers/sizes](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-bank/lockersizes.md): This API operation returns all available locker sizes in the specified locker bank to help select an appropriate size for reservations. - [GET /api/v1/lockerBanks/{lockerBankId}](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-bank/getlockerbankdetails.md): This API operation retrieves detailed information for the specified locker bank along with the list of locker units. ## Locker Unit - [POST /api/v1/lockerBanks/{lockerBankId}/lockers/reserve](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/createreservation.md): This API operation creates a reservation for a locker unit in the specified locker bank. **Locker selection rules** - Provide either `size` or `lockerUnitId`. - If `lockerUnitId` is provided, the syst - [POST /api/v1/lockerBanks/{lockerBankId}/lockers/asset/reserve](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/createreturnreservation.md): Creates a locker reservation for a return or asset drop-off. Use this endpoint when the depositor needs to place a package or asset into a locker for pickup by a courier, or operations team. The reser - [POST /api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/open](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/openlockerunit.md): Opens a specific locker unit remotely in the specified locker bank. Use this endpoint when an authorized user needs to unlock a locker unit for package deposit or return drop-off. **Note:** This API r - [POST /api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/free](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/freereservation.md): This API operation release a previously reserved locker unit or remove the reserved package based on the tracking number in the specified locker bank when the reservation needs to be released. Once th - [GET /api/v1/lockerBanks/{lockerBankId}/lockers/reserved/contact/{contactId}](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/getreservationlist.md): This API operation retrieves all active reservations for the specified contact within the given locker bank. Use this API to view all locker units currently reserved for a particular recipient or depa - [GET /api/v1/lockerBanks/{lockerBankId}/lockers/reserved/{trackingNumber}](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/getreservation.md): This API operation retrieves the reservation details for a specific parcel using its tracking number within the specified locker bank. - [PATCH /api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/deposit](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/updatedeposit.md): This API operation deposit a package into a locker unit in the specified locker bank - [PATCH /api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/reservation/update](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/updatereservation.md): This API operation updates the reservation information to add a package into an existing locker unit in the given locker bank. - [GET /api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/status](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/getlockerunitstatus.md): Retrieves the door status of a specific locker unit in the specified locker bank. Use this endpoint to check whether the locker unit door is open or closed after an open, deposit, pickup, return drop- - [POST /api/v1/lockerBanks/{lockerBankId}/lockers/pickup](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/recipientpickup.md): This API operation is used to pick up deposited packages from locker units within the specified locker bank. Use this endpoint when: - A recipient picks up a delivered package from a locker unit. - A - [POST /api/v1/lockerBanks/{lockerBankId}/lockers/admin/pickup](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/adminpickup.md): This API operation Allows authorized administrators to retrieve packages through the rear side of a locker unit without opening the locker door. Use this endpoint when: - Retrieve packages via the l - [PATCH /api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/hold](https://docs.shipping360.pitneybowes.com/openapi/lockers/locker-unit/holdlockerunit.md): Places a locker unit in an On Hold state and removes recipient pickup access. While a locker unit remains on hold, only authorized administrators can retrieve the package using the Admin Pickup API.