{ "openapi": "3.0.3", "info": { "title": "Pitney Locker APIs", "description": "\nThe 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.\n\nBy 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 . \n\n**Why Use Pitney Locker APIs**\n\n- Enable contactless, secure package deliveries\n\n- Automate locker assignment and release\n\n- Support forward delivery and return/drop-off workflows\n\n- Track which locker unit is assigned to which package\n\n- Simplify mailroom or internal delivery operations\n\n- Retrieve locker availability and locker status information\n\n\n**How Pitney Locker APIs Work**\n\nThe 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.\n\nThe APIs support two primary workflows:\n\n- Forward delivery workflow (transactionType: deliver)\n- Return or asset drop-off workflow (transactionType: return)\n\nA user (typically a mailroom operator or system) can use these APIs to:\n\n 1. Look up locker banks\n 2. Check available locker unit sizes\n 3. Reserve locker units\n 4. Open locker units remotely\n 5. Deposit packages into locker units\n 6. Retrieve reservation details\n 7. Free locker units after use\n 8. Monitor locker unit operational status\n\n\n**Step-by-Step Workflow for Pitney Locker APIs**\n\n**Step 1: Retrieve Available Locker Banks**\n\nUse 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.\nFilter by:\n\n- `locationId`: To get lockers for a specific location\n\n- `lockerBankId`: To retrieve a specific locker bank by ID. One location can have multiple banks.\n\n- Each locker bank has a unique `lockerBankId`, used in subsequent API calls.\n\n**Step 2: Get Locker Sizes for a Locker Bank**\n\nUse 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.\n\n- You need to pass the `lockerBankId` retrieved in Step 1 as a path parameter.\n\n**Step 3: Reserve a Locker Unit**\n\nOnce you know a locker unit is available, use the [Reserve Locker Unit API](/openapi/lockers/locker-unit/createreservation) to create a reservation.\nThis workflow is typically used for forward delivery operations and internally uses `transactionType: deliver`\n\nRequired fields include:\n\n- `lockerBankId` (path parameter)\n\n- Package tracking number\n\n- Locker size preference (e.g., small)\n\n- Recipient identification (contact ID and type)\n\n- Reservation Expiry Time \n\nIf a locker is successfully reserved, a **locker unit ID** will be returned in the response.\n\n**Return and Asset Drop-off Reservations**\n\nFor return or asset drop-off workflows, use the Create Return Reservation API.\n\nThis workflow uses `transactionType: return`\n\nIn 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.\n\nThe reservation can include:\n\n- Receiving contact information\n- Depositor contact information\n- Tracking details\n- Reservation expiry information\n\n**Step 4: Open a Locker Unit**\n\nUse 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.\n\n**Step 5: Add or Update Deposit Information**\n\nAfter 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.\n\nThis updates the locker reservation to reflect:\n\n- Parcel successfully deposited\n- Deposit timestamp\n- depositExpiryTime (Once expired, the parcel may be removed or handled according to facility policy.)\n- 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`)\n\nYou need to pass:\n\n- `lockerBankId` (path parameter)\n\n- `lockerUnitId` (path parameter)\n\n**Step 6: Retrieve Reservation Details** \n\nThese APIs help external systems, operators, or recipients retrieve reservation details.\n\n- [Get Reservations by Contact](/openapi/lockers/locker-unit/getreservationlist): Retrieve all reservations linked to a specific recipient/contact.\n- [Get Reservation by Tracking Number](/openapi/lockers/locker-unit/getreservation): Retrieve reservation details using the package tracking number.\n\n**Step 7: Update Reservation** \n\nIf reservation details need to be changed (e.g., expiry time, contact details, metadata), use the [Update Reservation API](/openapi/lockers/locker-unit/updatereservation).\n\nYou need to pass:\n\n- `lockerBankId` (path parameter)\n\n- `lockerUnitId` (path parameter)\n\n**Step 7: Free the Reserved Locker Unit**\n\nUse 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.\n\nYou need to pass:\n\n- `lockerBankId` (path parameter)\n\n- unit to be freed - `lockerUnitId` (path parameter)\n\n**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).\n", "version": "1.0.0" }, "servers": [ { "url": "https://api-dev.sendpro360.pitneycloud.com/parcelpoint" }, { "url": "https://api-qa.sendpro360.pitneycloud.com/parcelpoint" }, { "url": "https://api-sandbox.sendpro360.pitneybowes.com/parcelpoint", "description": "Sandbox Server" }, { "url": "https://api.sendpro360.pitneybowes.com/parcelpoint", "description": "Production Server (uses live data)" } ], "tags": [ { "name": "Locker Bank", "description": "APIs for retrieving and managing locker bank information. Locker banks represent physical installations of smart lockers at specific locations. These APIs support operations such as listing available locker banks, retrieving locker bank details, and fetching available locker unit sizes within a bank. The returned lockerBankId is required for all subsequent locker unit operations." }, { "name": "Locker Unit", "description": "APIs for managing locker unit reservations and parcel handling workflows within a locker bank. These APIs support operations such as reserving locker units, depositing parcels, retrieving reservation details, updating reservations, and freeing locker units. Together, these operations enable end-to-end management of locker-based delivery and pickup workflows." } ], "paths": { "/api/v1/lockerBanks": { "get": { "tags": [ "Locker Bank" ], "summary": "Get List of all Locker Banks", "description": "This API operation returns a list of all available locker banks where packages can be deposited for recipient pickup.", "operationId": "getLockerBanks", "parameters": [ { "name": "X-PB-Developer-Partner-ID", "in": "header", "description": "The Developer Partner ID is assigned by PB to uniquely identify a Developer's strategic business partners. If the developer is the sole business partner, this field isn't required.", "required": false, "schema": { "type": "string", "example": "PB123456" } }, { "name": "skip", "in": "query", "description": "The number of records to skip in the returned list. Default is 0.", "required": false, "schema": { "type": "integer", "example": "0" } }, { "name": "limit", "in": "query", "description": "The maximum number of locker banks to return in the response. Default is 100.", "required": false, "schema": { "type": "integer", "example": "100" } }, { "name": "locationId", "in": "query", "description": " Filters the locker banks by the specific location ID where the lockers are placed.", "required": false, "schema": { "type": "string", "example": "loc_auto_sa5cxxx" } }, { "name": "lockerBankId", "in": "query", "description": "Filters the locker banks by the specific locker bank ID.", "required": false, "schema": { "type": "string", "example": "AOne" } } ], "responses": { "200": { "description": "Successfully retrieved the list of locker banks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockerBankResponse" } } } }, "400": { "description": "Invalid or Bad Request", "$ref": "#/components/responses/BadRequestError" }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/sizes": { "get": { "tags": [ "Locker Bank" ], "summary": "List of Locker Sizes in a Locker Bank", "description": "This API operation returns all available locker sizes in the specified locker bank to help select an appropriate size for reservations.", "operationId": "lockerSizes", "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank whose locker sizes you want to retrieve. Use the value returned by the `Get list of all locker banks` API.", "required": true, "schema": { "type": "string", "example": "AOne" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved locker sizes for the locker bank.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockerSizesResponse" } } } }, "400": { "description": "Invalid or Bad Request", "$ref": "#/components/responses/BadRequestError" }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Locker bank not found" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/reserve": { "post": { "tags": [ "Locker Unit" ], "summary": "Creates a new Reservation for a Locker", "description": "This API operation creates a reservation for a locker unit in the specified locker bank.\n\n **Locker selection rules**\n- Provide either `size` or `lockerUnitId`.\n- If `lockerUnitId` is provided, the system reserves that exact locker.\n- If only `size` is provided, the system selects any available locker of that size.\n- If both are provided, `lockerUnitId` takes precedence and `size` is ignored.\n", "operationId": "createReservation", "parameters": [ { "name": "lockerBankId", "in": "path", "description": "This is the unique identifier of the locker bank.", "required": true, "schema": { "type": "string", "example": "AOne" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "Create a reservation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockerReservationRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockerReservationResponse" } } } }, "400": { "description": "Bad Request", "$ref": "#/components/responses/BadRequestError" }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Bad Request", "$ref": "#/components/responses/NotFoundError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/asset/reserve": { "post": { "tags": [ "Locker Unit" ], "summary": "Create a return reservation", "description": "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 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.", "operationId": "createReturnReservation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank where the return locker is reserved.", "required": true, "schema": { "type": "string", "example": "AOne" } } ], "requestBody": { "description": "Return reservation details, including the intended receiving contact and the depositor contact who will drop off the package or asset.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockerAssetReservationRequest" } } } }, "responses": { "200": { "description": "Return reservation created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockerAssetReservationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/open": { "post": { "tags": [ "Locker Unit" ], "summary": "Open a locker unit", "description": "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.\n**Note:** This API returns a success response only when the locker hardware is configured.\n", "operationId": "openLockerUnit", "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank where the locker unit is located.", "required": true, "schema": { "type": "string", "example": "AOne" } }, { "name": "lockerUnitId", "in": "path", "description": "The unique identifier of the locker unit to open.", "required": true, "schema": { "type": "string", "example": "2" } } ], "requestBody": { "description": "Open locker request details, including the user performing the action.", "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The request to open a locker unit remotely.", "required": [ "userId" ], "properties": { "userId": { "type": "string", "example": "user@gmail.com", "description": "The identifier of the person or system user in the address book performing the open locker action." } } } } } }, "responses": { "200": { "description": "Locker unit opened successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenLockerResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/free": { "post": { "tags": [ "Locker Unit" ], "summary": "Free a Reserved Locker Unit", "description": "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 the locker unit freed, the unit becomes available for new reservations.", "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank where the locker unit is located. Retrieve this value using the Get Locker Banks API.", "required": true, "schema": { "type": "string", "example": "AOne" } }, { "name": "lockerUnitId", "in": "path", "description": "The unique identifier of the locker unit to be freed within the specified locker bank.", "required": true, "schema": { "type": "string", "example": "2" } } ], "operationId": "freeReservation", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "Free a reserved locker number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeLockerUnitRequest" } } }, "required": true }, "responses": { "200": { "description": "The specified locker unit is freed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeLockerUnitResponse" } } } }, "400": { "description": "Bad Request", "$ref": "#/components/responses/BadRequestError" }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Locker bank not found", "$ref": "#/components/responses/NotFoundError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lockerBanks/{lockerBankId}": { "get": { "tags": [ "Locker Bank" ], "summary": "Get Locker Bank by Locker Bank ID", "description": "This API operation retrieves detailed information for the specified locker bank along with the list of locker units.", "operationId": "getLockerBankDetails", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lockerBankId", "in": "path", "description": "Filters the locker banks by the specific locker bank ID.", "required": true, "schema": { "type": "string", "example": "AOne" } } ], "responses": { "200": { "description": "Specified locker bank details has been retrived successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockerBankDetailsResponse" } } } }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Bad Request", "$ref": "#/components/responses/NotFoundError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/reserved/contact/{contactId}": { "get": { "tags": [ "Locker Unit" ], "summary": "Get Reservation List by Contact ID", "description": "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 department.", "operationId": "getReservationList", "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank from which reservation details must be retrieved.", "required": true, "schema": { "type": "string", "example": "AOne" } }, { "name": "contactId", "in": "path", "description": "The identifier of the contact (recipient or department) whose reservation details are requested.", "required": true, "schema": { "type": "string", "example": "684a6b7bbc85e1bce739xxxx" } } ], "responses": { "200": { "description": "All active reservations for the specified contact has been fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationListResponse" } } } }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Bad Request", "$ref": "#/components/responses/NotFoundError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/reserved/{trackingNumber}": { "get": { "tags": [ "Locker Unit" ], "summary": "Get Reservation by Tracking Number", "description": "This API operation retrieves the reservation details for a specific parcel using its tracking number within the specified locker bank. ", "operationId": "getReservation", "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank from which the reservation information must be retrieved.", "required": true, "schema": { "type": "string", "example": "AOne" } }, { "name": "trackingNumber", "in": "path", "description": "The tracking number of the parcel whose reservation details are being requested.", "required": true, "schema": { "type": "string", "example": "TrackigID137" } }, { "name": "isTrackNumUrlEncoded", "in": "query", "description": "Indicates whether the tracking number provided in the request is URL encoded.", "required": false, "schema": { "type": "boolean", "example": false } }, { "name": "includeAllParcels", "in": "query", "description": "When set to true, the response includes all tracking numbers currently assigned to the locker unit.", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Reservation details for the specified tracking number has been fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationResponse" } } } }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Bad Request", "$ref": "#/components/responses/NotFoundError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "basicAuth": [] } ] } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/deposit": { "patch": { "tags": [ "Locker Unit" ], "summary": "Deposit a package into a locker unit", "description": "This API operation deposit a package into a locker unit in the specified locker bank", "operationId": "updateDeposit", "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank where the locker unit is located.", "required": true, "schema": { "type": "string", "example": "AOne" } }, { "name": "lockerUnitId", "in": "path", "description": "The unique identifier of the locker unit within the specified locker bank.", "required": true, "schema": { "type": "string", "example": "2" } } ], "requestBody": { "description": "The details of the parcel deposit into a locker unit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageDepositRequest" } } }, "required": true }, "responses": { "200": { "description": "The package has been deposited into a locker unit in the specified locker bank.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageDepositResponse" } } } }, "400": { "description": "Bad Request", "$ref": "#/components/responses/BadRequestError" }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Bad Request", "$ref": "#/components/responses/NotFoundError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/reservation/update": { "patch": { "tags": [ "Locker Unit" ], "summary": "Update Reservation", "description": "This API operation updates the reservation information to add a package into an existing locker unit in the given locker bank.", "operationId": "updateReservation", "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank where the locker unit is located.", "required": true, "schema": { "type": "string", "example": "AOne" } }, { "name": "lockerUnitId", "in": "path", "description": "The unique identifier of the locker unit whose reservation details need to be updated.", "required": true, "schema": { "type": "string", "example": "2" } } ], "requestBody": { "description": "Update the reservation parcels for an existing locker unit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReservationRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReservationResponse" } } } }, "400": { "description": "Bad Request", "$ref": "#/components/responses/BadRequestError" }, "401": { "description": "Unauthorized Error", "$ref": "#/components/responses/UnauthorizedError" }, "404": { "description": "Bad Request", "$ref": "#/components/responses/NotFoundError" }, "500": { "description": "Internal Server Error", "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/status": { "get": { "tags": [ "Locker Unit" ], "summary": "Get locker unit status", "description": "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-off, or maintenance operation.
**Note:** This API returns a success response only when the locker hardware is configured.", "operationId": "getLockerUnitStatus", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank where the locker unit is located.", "required": true, "schema": { "type": "string", "example": "AOne" } }, { "name": "lockerUnitId", "in": "path", "description": "The unique identifier of the locker unit whose door status must be retrieved.", "required": true, "schema": { "type": "string", "example": "2" } } ], "responses": { "200": { "description": "Locker unit status retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockerDoorStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/pickup": { "post": { "tags": [ "Locker Unit" ], "summary": "Recipient Pickup", "description": "This API operation is used to pick up deposited packages from locker units within the specified locker bank.\n\nUse this endpoint when:\n- A recipient picks up a delivered package from a locker unit.\n- An authorized user performs a package retrieval operation.\n\nThe request can include one or more pickup requests. Each pickup request identifies the locker unit and package pickup code associated with the parcel pickup operation.\n", "operationId": "recipientPickup", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank where the package pickup operation is performed.", "required": true, "schema": { "type": "string", "example": "AOne" } } ], "requestBody": { "description": "Package pickup request details for one or more locker units.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickupPackageRequest" } } } }, "responses": { "200": { "description": "Package pickup completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickupPackageResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/admin/pickup": { "post": { "tags": [ "Locker Unit" ], "summary": "Admin Pickup", "description": "This API operation Allows authorized administrators to retrieve packages through the rear side of a \nlocker unit without opening the locker door.\n\nUse this endpoint when:\n- Retrieve packages via the locker's rear-loading compartment for authorized admin collection.\n- Remove expired or abandoned parcels without opening the front locker door.\n- Perform maintenance or bulk recovery when front-door access is unavailable.\n", "operationId": "adminPickup", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank where the package pickup operation is performed.", "required": true, "schema": { "type": "string", "example": "AOne" } } ], "requestBody": { "description": "Package pickup request details for one or more locker units.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickupPackageAdminRequest" } } } }, "responses": { "200": { "description": "Package pickup completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickupPackageAdminResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/lockerBanks/{lockerBankId}/lockers/{lockerUnitId}/hold": { "patch": { "tags": [ "Locker Unit" ], "summary": "Locker unit On Hold State", "description": "Places a locker unit in an On Hold state and removes recipient pickup access.\nWhile a locker unit remains on hold, only authorized administrators can retrieve the package using the Admin Pickup API.\n\nUse this endpoint when:\n- Temporarily prevent recipient pickups when a locker needs investigation or holds are required.\n- Let authorized administrators retrieve contents via Admin Pickup without restoring recipient access.\n- Suspend access for maintenance, compliance checks, or dispute resolution.\n", "operationId": "holdLockerUnit", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "lockerBankId", "in": "path", "description": "The unique identifier of the locker bank.", "required": true, "schema": { "type": "string", "example": "AOne" } }, { "name": "lockerUnitId", "in": "path", "description": "The unique identifier of the locker unit.", "required": true, "schema": { "type": "string", "example": "2" } } ], "requestBody": { "description": "Package pickup request details for one or more locker units.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockerUnitOnHoldRequest" } } } }, "responses": { "200": { "description": "Locker unit placed on hold successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockerUnitOnHoldResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "schemas": { "LockerReservationRequest": { "type": "object", "required": [ "userId", "contactId", "contactType", "trackingNumber" ], "properties": { "userId": { "type": "string", "description": "The identifier of the user performing the locker reservation action.", "example": "thirdpartyuser@gmail.com" }, "size": { "type": "string", "description": "Requested locker size for the reservation.Used only when `lockerUnitId` is not provided. If both `size` and `lockerUnitId` are provided, this value is ignored. valid values are- small, medium, large and mlarge.\n", "example": "small" }, "accessible": { "type": "boolean", "description": "Requests a locker that would be deemed handicapped accesible to recipients.", "example": true }, "lockerUnitId": { "type": "string", "description": "The locker unit number you wish to reserve.", "example": "2" }, "contactId": { "type": "string", "description": "The identifier of the recipient of the package for whom the locker reservation is created.", "example": "684a6b7bbc85e1bce739xxxx" }, "contactType": { "type": "string", "description": "The source type of the recipient identifier.", "example": "recipient", "enum": [ "recipient", "department" ] }, "trackingNumber": { "type": "string", "description": "The primary identifier of a package, usually a carrier's tracking number.", "example": "TrackigID137" }, "secondaryTrackingNumber": { "type": "string", "description": "A secondary identifier for a package, can be generated internally.", "example": "TRACK-1234" }, "reservationExpiryTime": { "type": "string", "description": "The timestamp when the reservation for the locker unit is scheduled to expire. Once reservation is expired, the locker unit becomes available for new reservations.", "example": "2027-12-01T00:00:00Z" } } }, "LockerReservationResponse": { "type": "object", "properties": { "lockerBankId": { "type": "string", "description": "The unique identifier of the locker bank where the reservation was created.", "example": "AOne" }, "lockerUnitId": { "type": "string", "description": "The locker unit number assigned for the reservation.", "example": "2" }, "size": { "type": "string", "description": "The size of the locker assigned for the reservation.", "example": "small" }, "contactId": { "type": "string", "description": "The identifier of the recipient of the package associated with the reservation.", "example": "684a6b7bbc85e1bce739xxxx" }, "contactType": { "type": "string", "description": "The source type of the recipient identifier.", "example": "recipient", "enum": [ "recipient", "department" ] }, "trackingNumber": { "type": "string", "description": "The primary identifier of a package, usually a carrier's tracking number.", "example": "TrackigID137" }, "secondaryTrackingNumber": { "type": "string", "description": "A secondary identifier for a package, can be generated internally.", "example": "TRACK-1234" }, "reservationExpiryTime": { "type": "string", "description": "The timestamp when the reservation for the locker unit is scheduled to expire. Once reservation is expired, the locker unit becomes available for new reservations.", "example": "2027-12-01T00:00:00Z" } } }, "LockerAssetReservationRequest": { "type": "object", "description": "The request to create a return or asset drop-off reservation.", "required": [ "userId", "size", "contactId", "contactType", "depositorContactId", "depositorContactType", "trackingNumber" ], "properties": { "userId": { "type": "string", "example": "user@gmail.com", "description": "The identifier of the user performing the reservation action." }, "size": { "type": "string", "description": "The size of the locker unit required for the return or asset drop-off.", "example": "small" }, "accessible": { "type": "boolean", "example": true, "description": "Indicates whether an accessible locker unit is required." }, "contactId": { "type": "string", "example": "684a6b7bbc85e1bce739xxxx", "description": "The identifier of the contact or department that will receive the returned package or asset." }, "contactType": { "type": "string", "description": "The type of contact that will receive the returned package or asset.", "enum": [ "recipient", "department" ] }, "depositorContactId": { "type": "string", "example": "684a6b7bbc85e1bxxxxxxxxx", "description": "The identifier of the person or contact in the address book who will deposit the returned package or asset into the locker." }, "depositorContactType": { "type": "string", "description": "The type of contact who will deposit the returned package or asset.", "enum": [ "recipient", "department" ] }, "trackingNumber": { "type": "string", "example": "TrackigID137", "description": "The primary tracking number or identifier for the returned package or asset." }, "secondaryTrackingNumber": { "type": "string", "example": "TRACK-1234", "description": "The secondary tracking number or additional identifier for the returned package or asset." }, "reservationExpiryTime": { "type": "string", "example": "2027-12-01T00:00:00Z", "format": "date-time", "description": "The date and time when the reservation expires." } } }, "LockerAssetReservationResponse": { "type": "object", "description": "The response returned after a locker unit is reserved for a return or asset drop-off.", "properties": { "lockerBankId": { "type": "string", "example": "AOne", "description": "The unique identifier of the locker bank." }, "lockerUnitId": { "type": "string", "example": "2", "description": "The locker unit reserved for the return or asset drop-off." }, "size": { "type": "string", "example": "small", "description": "The size of the reserved locker unit." }, "contactId": { "type": "string", "example": "684a6b7bbc85e1bce739xxxx", "description": "The identifier of the contact or department that will receive the returned package or asset." }, "contactType": { "type": "string", "description": "The type of contact that will receive the returned package or asset.", "enum": [ "recipient", "department" ] }, "depositorContactId": { "type": "string", "example": "684a6b7bbc85e1bxxxxxxxxx", "description": "The identifier of the person or contact in the address book who will deposit the returned package or asset ." }, "depositorContactType": { "type": "string", "description": "The type of contact who will deposit the returned package or asset.", "enum": [ "recipient", "department" ] }, "depositorAccessCode": { "type": "string", "example": "NR8PBW", "description": "The access code given to the depositor to open the locker and drop off the package or asset." }, "trackingNumber": { "type": "string", "example": "TrackigID137", "description": "The primary tracking number or identifier for the returned package or asset." }, "reservationExpiryTime": { "type": "string", "example": "2027-12-01T00:00:00Z", "format": "date-time", "description": "The date and time when the reservation expires." } } }, "OpenLockerResponse": { "type": "object", "description": "The response returned after the locker unit is opened.", "properties": { "lockerBankId": { "type": "string", "example": "AOne", "description": "The unique identifier of the locker bank." }, "lockerUnitId": { "type": "string", "example": "2", "description": "The unique identifier of the locker unit that was opened." }, "contactId": { "type": "string", "example": "684a6b7bbc85e1bce739xxxx", "description": "The identifier of the contact associated with the locker reservation, if available." }, "contactType": { "type": "string", "description": "The type of contact associated with the locker reservation.", "enum": [ "recipient", "department" ] }, "activityType": { "type": "string", "description": "The activity for which the locker unit was opened.", "enum": [ "deposit", "pickup", "maintenance" ] }, "parcelsReserved": { "type": "array", "description": "The list of parcels reserved in the locker unit, if any.", "items": { "$ref": "#/components/schemas/Parcel" } }, "parcelsDeposited": { "type": "array", "description": "The list of parcels deposited in the locker unit, if any.", "items": { "$ref": "#/components/schemas/Parcel" } } } }, "LockerDoorStatusResponse": { "type": "object", "description": "Response containing the current door status of the locker unit.", "properties": { "status": { "type": "string", "description": "The current door status of the specified locker unit. Expected values are 'open' or 'closed'.", "example": "closed" } } }, "FreeLockerUnitRequest": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "string", "description": "The identifier of the user performing the locker unit free action.", "example": "ThirdParty" }, "parcels": { "type": "array", "description": "The list of parcels associated with the locker being freed.", "items": { "type": "object", "properties": { "trackingNumber": { "type": "string", "description": "The primary tracking number of the parcel.", "example": "Dept03" }, "secondaryTrackingNumber": { "type": "string", "example": "TRACK-1234", "description": "An optional secondary identifier for the parcel." } } } } } }, "FreeLockerUnitResponse": { "type": "object", "properties": { "lockerBankId": { "type": "string", "description": "The unique identifier of the locker bank where the locker unit was freed.", "example": "AOne" }, "lockerUnitId": { "type": "string", "description": "The identifier of the locker unit that was freed.", "example": "2" }, "unitReserved": { "type": "boolean", "description": "Indicates whether the locker unit is reserved.", "example": true }, "contactId": { "type": "string", "description": "The identifier of the recipient associated with the locker reservation that was freed.", "example": "ThirdParty" }, "contactType": { "type": "string", "description": "The source type of the recipient identifier.", "example": "recipient", "enum": [ "recipient", "department" ] }, "parcelsReserved": { "type": "array", "description": "The list of parcels currently in reserved state for this locker unit. In case of no parcels in reserved state, no tracking number is returned.", "items": { "type": "object", "properties": { "trackingNumber": { "type": "string", "description": "The tracking number of the parcel that was reserved.", "example": "26112025_1" }, "secondaryTrackingNumber": { "type": "string", "description": "A secondary identifier for a package, can be generated internally.", "example": "TRACK-1234" } } } } } }, "LockerSizesResponse": { "description": "Response containing all sizes available in a particular locker bank.", "type": "object", "properties": { "supportedSize": { "type": "array", "description": "The list of supported locker sizes in the locker bank.", "items": { "$ref": "#/components/schemas/SupportedSize" } } } }, "SupportedSize": { "type": "object", "properties": { "size": { "type": "string", "description": "The name of the locker size as used in LockerReservationRequest.", "example": "small" }, "uom": { "type": "string", "description": "The unit of measurement for the dimensions of the locker size.", "example": "in" }, "dimension": { "type": "object", "description": "The dimensions of the locker size.", "$ref": "#/components/schemas/Dimension" }, "total": { "type": "integer", "description": "The total number of locker units for this size.", "example": 10 }, "available": { "type": "integer", "description": "The number of available locker units for this size.", "example": 6 }, "accessible": { "type": "integer", "description": "The total number of accessible locker units available for this size for individuals with disabilities.", "example": 2 } } }, "Dimension": { "type": "object", "properties": { "length": { "type": "integer", "description": "The length of the locker in the specified unit of measurement.", "example": 22.75 }, "width": { "type": "integer", "description": "The width of the locker in the specified unit of measurement.", "example": 16.5 }, "height": { "type": "integer", "description": "The height of the locker in the specified unit of measurement.", "example": 3.5 } } }, "LockerBankResponse": { "type": "array", "description": "The list of locker banks available.", "items": { "$ref": "#/components/schemas/LockerBank" } }, "ReservationListResponse": { "description": "A list of all locker unit reservations associated with the specified contact within the locker bank.", "type": "object", "properties": { "reservedUnits": { "type": "array", "description": "The list of reserved locker units for the contact.", "items": { "$ref": "#/components/schemas/ReservationResponse" } } } }, "PackageDepositRequest": { "type": "object", "required": [ "parcels" ], "properties": { "userId": { "type": "string", "description": "The identifier of the user performing the deposit action.", "example": "user@gmail.com" }, "parcels": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Parcel" }, { "type": "object", "properties": { "photo": { "$ref": "#/components/schemas/Photo" } } } ] } } } }, "PackageDepositResponse": { "type": "object", "properties": { "lockerBankId": { "type": "string", "description": "The unique identifier for the locker bank.", "example": "AOne" }, "lockerUnitId": { "type": "string", "description": "The unique identifier of the locker unit where the parcel was deposited.", "example": "7" }, "userId": { "type": "string", "description": "The identifier of the user who performed the deposit action.", "example": "user@gmail.com" }, "pickupCode": { "type": "string", "description": "The pickup code provided to the recipient for retrieving the deposited parcel.\nPickup Code will only be provided to the `contactType: recipient`. For `contactType: department` the contacts will pick the parcel by providing their `personalId`\n", "example": "NR8PBW" }, "depositTime": { "type": "string", "description": "The timestamp when the package was deposited in the locker unit.", "example": "2025-11-27T11:23:26Z" }, "depositExpiryTime": { "type": "string", "description": "The timestamp when the deposited parcel is scheduled to expire. Once expired, the parcel may be removed or handled according to facility policy and the locker unit becomes available for new reservations.", "example": "2025-11-28T11:23:26Z" }, "parcelsDeposited": { "type": "array", "description": "The list of parcels that were successfully deposited in the locker unit.", "items": { "$ref": "#/components/schemas/Parcel" } } } }, "UpdateReservationRequest": { "type": "object", "required": [ "parcels" ], "properties": { "userId": { "type": "string", "description": "The identifier of the user performing the reservation update.", "example": "user@gmail.com" }, "reservationExpiryTime": { "type": "string", "example": "2027-12-01T00:00:00Z", "description": "The expiry time for the reservation." }, "parcels": { "type": "array", "items": { "$ref": "#/components/schemas/Parcel" } } } }, "UpdateReservationResponse": { "type": "object", "properties": { "lockerBankId": { "type": "string", "description": "The unique identifier for the locker bank", "example": "AOne" }, "lockerUnitId": { "type": "string", "description": "The unique identifier of the locker unit whose reservation was updated.", "example": "7" }, "userId": { "type": "string", "description": "The identifier of the user who performed the reservation update.", "example": "user@gmail.com" }, "reservationExpiryTime": { "type": "string", "example": "2027-12-01T00:00:00Z", "description": "The expiry time for the reservation." }, "parcelsReserved": { "type": "array", "description": "The list of parcels reserved for this locker unit after the update.", "items": { "$ref": "#/components/schemas/Parcel" } } } }, "ReservationResponse": { "type": "object", "properties": { "lockerBankId": { "type": "string", "description": "The unique identifier for the locker bank.", "example": "AOne" }, "lockerUnitId": { "type": "string", "description": "The unique identifier of the reserved locker unit.", "example": "2" }, "size": { "type": "string", "description": "The size of the reserved locker unit.", "example": "small" }, "accessible": { "type": "boolean", "description": "Indicates whether the reserved locker unit is accessible for individuals with disabilities.", "example": true }, "unitInService": { "type": "boolean", "description": "Indicates whether the reserved locker unit is currently operational.", "example": true }, "unitReserved": { "type": "boolean", "description": "Indicates whether the locker unit is currently reserved for a parcel.", "example": true }, "unitOccupied": { "type": "boolean", "description": "Indicates whether one or more parcels have been deposited in the locker unit.", "example": true }, "parcelsReserved": { "type": "array", "description": "The parcels that have been reserved for this locker unit but are not yet deposited.", "items": { "$ref": "#/components/schemas/Parcel" } }, "parcelsDeposited": { "type": "array", "description": "The parcels that have already been deposited in the locker unit and are awaiting pickup", "items": { "$ref": "#/components/schemas/Parcel" } }, "contactId": { "type": "string", "description": "The identifier of the contact (recipient or department) associated with the reservation.", "example": "684a6b7bbc85e1bce739xxxx" }, "contactType": { "type": "string", "description": "This is an enumerated value that tells you where the contact code is coming from", "enum": [ "recipient", "department" ], "example": "recipient" }, "contactName": { "type": "string", "description": "The name of the contact associated with the reservation.", "example": "User Name" }, "reservationTime": { "type": "string", "description": "The timestamp indicating when the reservation was created.", "example": "2025-11-12T16:13:06Z" }, "reservationExpiryTime": { "type": "string", "description": "The timestamp when the reservation for the locker unit is scheduled to expire. Once reservation is expired, the locker unit becomes available for new reservations.", "example": "2025-12-19T09:59:00Z" }, "transactionType": { "type": "string", "description": " This indicates the nature of the transaction, such as whether it was a delivery or a return.", "example": "deliver" }, "depositorContactId": { "type": "string", "description": "The identifier of the person or contact in the address book who will deposit the returned package or asset into the locker.", "example": "684a6b7bbc85e1bxxxxxxxxx" }, "depositorContactType": { "type": "string", "description": "This is an enumerated value that tells you where the contact code is coming from.", "example": "recipient", "enum": [ "recipient", "department" ] }, "depositTime": { "type": "string", "description": "The timestamp when the parcel was deposited into the locker unit, returns only if the unit is occupied.", "example": "2025-11-17T14:28:37Z" }, "depositExpiryTime": { "type": "string", "description": "The timestamp when the deposited parcel is scheduled to expire.", "example": "2025-11-30T14:28:37Z" } } }, "LockerBank": { "type": "object", "properties": { "lockerBankId": { "type": "string", "description": "The identifier for the locker bank used by the APIs.", "example": "AOne" }, "bankName": { "type": "string", "description": "The display name of the locker bank for user reference.", "example": "Locker One" }, "locationId": { "type": "string", "description": "The identifier of the location where the locker bank is placed", "example": "loc_auto_sa5cxxx" }, "lastHeartbeatTime": { "type": "string", "example": "2025-11-27T11:23:26Z", "format": "date-time", "description": "The timestamp of the most recent heartbeat signal received from the locker bank. This value helps determine if the locker bank is online and communicating with the system.\n" }, "rearLoadingEnabled": { "type": "boolean", "example": true, "description": "Indicates whether the locker bank supports rear-side loading, allowing mailroom operators to place parcels into the lockers from the back of the unit.\n" }, "deliveryEnabled": { "type": "boolean", "example": true, "description": "Indicates whether the locker bank is currently active and available for delivery operations. If set to false, the locker bank is out of service.\n" }, "assetEnabled": { "type": "boolean", "example": true, "description": "Indicates whether the locker bank supports return functionality.\n" } } }, "LockerBankDetailsResponse": { "type": "object", "properties": { "lockerBankId": { "type": "string", "description": "The unique identifier for the specified locker bank.", "example": "AOne" }, "bankName": { "type": "string", "description": "The given name to the locker bank to help identify the locker bank by users.", "example": "Locker One" }, "locationId": { "type": "string", "description": "The identifier of the location where the locker bank is installed.", "example": "loc_auto_sa5cxxx" }, "lockerBankDescription": { "type": "string", "example": "Locker bank installed for parcel deliveries.", "description": "A descriptive text about the specified locker bank." }, "lastHeartbeatTime": { "type": "string", "example": "2025-11-27T11:23:26Z", "description": "The timestamp of the most recent heartbeat signal received from the locker bank, indicating its latest communication status." }, "rearLoadingEnabled": { "type": "boolean", "example": true, "description": "Indicates if the locker bank is have rear loading enabled." }, "deliveryEnabled": { "type": "boolean", "example": true, "description": "Indicates whether the locker bank is currently in service and available for operations." }, "assetEnabled": { "type": "boolean", "description": "Indicates whether asset support is enabled for the locker bank.", "example": true }, "lockerUnits": { "type": "array", "items": { "$ref": "#/components/schemas/LockerUnit" } } } }, "LockerUnit": { "type": "object", "description": "About the all locker units of the locker bank.", "properties": { "lockerUnitId": { "type": "string", "description": "The unique identifier for the locker unit.", "example": "1" }, "size": { "type": "string", "description": "The size of this locker unit.", "example": "small" }, "accessible": { "type": "boolean", "description": "Indicates if the locker unit is handicapped accesible to recipients.", "example": false }, "unitInService": { "type": "boolean", "description": "Indicates if the locker unit is currently operational.", "example": true }, "unitReserved": { "type": "boolean", "description": "Indicates if the locker unit is currently reserved.", "example": true }, "unitOccupied": { "type": "boolean", "description": "Indicates if the locker unit currently contains a deposited parcel.", "example": false }, "depositTime": { "type": "string", "description": "The timestamp of the parcel deposit, returns only for occupied locker units.", "example": "2025-11-17T14:28:37Z" }, "depositExpiryTime": { "type": "string", "description": "The timestamp when the deposited parcel is scheduled to expire. By default, a deposited parcel expires 2 days after the deposit date, excluding weekends. Once expired, the mailroom operator may remove the parcel or handle it according to facility policy.", "example": "2027-12-19T09:59:00Z" }, "reservationTime": { "type": "string", "description": "The timestamp when the locker unit reservation was made.", "example": "2025-11-26T10:34:30Z" }, "reservationExpiryTime": { "type": "string", "description": "The timestamp when the reservation for the locker unit is scheduled to expire. Once reservation is expired, the locker unit becomes available for new reservations.", "example": "2025-11-12T16:13:06Z" }, "transactionType": { "type": "string", "description": " This indicates the nature of the transaction, such as whether it was a delivery or a return.", "example": "deliver" }, "contactId": { "type": "string", "description": "The identifier of the recipient of the package for whom the locker reservation is created.", "example": "684a6b7bbc85e1bce739xxxx" }, "contactType": { "type": "string", "description": " Indicates the type of contact associated with the reservation.", "enum": [ "recipient", "department" ], "example": "recipient" }, "contactName": { "type": "string", "description": "The name of the contact associated with the reservation.", "example": "UserName" }, "depositorContactId": { "type": "string", "description": "The identifier of the person or contact in the address book who will deposit the returned package or asset into the locker.", "example": "684a6b7bbc85e1bxxxxxxxxx" }, "depositorContactType": { "type": "string", "description": "This is an enumerated value that tells you where the contact code is coming from. For the depositor of the package, this field indicates the type of contact information provided for the depositor, such as whether it is a recipient or a department.", "example": "recipient", "enum": [ "recipient", "department" ] }, "parcelsReserved": { "type": "array", "description": "The parcels that have been reserved for this locker unit but have not yet been deposited.", "items": { "$ref": "#/components/schemas/Parcel" } }, "parcelsDeposited": { "type": "array", "description": "A list of parcels that have already been deposited in the locker and are waiting to be picked up.", "items": { "$ref": "#/components/schemas/Parcel" } } } }, "Parcel": { "type": "object", "properties": { "trackingNumber": { "type": "string", "description": "The primary identifier of a package, usually a carrier's tracking number.", "example": "TRK123456789" }, "secondaryTrackingNumber": { "type": "string", "example": "ALT987654321", "description": "A secondary identifier for a package, can be generated internally." } } }, "Photo": { "type": "object", "properties": { "base64": { "type": "string", "description": "A base64 encoded string photo", "example": "iVBORw0KGgoAAAANSUhEUgAAAAUA..." }, "contentType": { "type": "string", "description": "The content type of the photo", "example": "image/png" } } }, "PackageActivity": { "type": "object", "description": "This object is sent via the platform callback whenever an event occurs to a package. Any properties that do not apply for the event will have NULL values", "properties": { "lockerBankId": { "type": "string", "example": "AOne", "description": "The locker bank unique identifier in Pitney Locker." }, "lockerUnitId": { "type": "string", "example": "2", "description": "The locker unit number" }, "activityCode": { "type": "string", "description": "The activity occuring to the package", "enum": [ "reservation", "cancelreservation", "deposit", "pickup", "stalemailpickup" ] }, "activityDate": { "type": "string", "example": "2025-11-27T11:23:26Z", "format": "date-time", "description": "The date and time when the event occurred." }, "userId": { "type": "string", "example": "user@gmail.com", "description": "The person who is performing the action" }, "photo": { "type": "string", "example": "iVBORw0KGgoAAAANSUhEUgAAAAUA...", "description": "The base64 encoded string taken by the locker bank of the person at the locker bank based upon configuration" }, "signature": { "type": "string", "example": "iVBORw0KGgoAAAANSUhEUgAAAAUA...", "description": "The signature of the recipient if configured to capture as base64 encoded string of bytes" }, "contactId": { "type": "string", "example": "684a6b7bbc85e1bce739xxxx", "description": "The identifier in the address book of the intended recipient of the package" }, "contactType": { "type": "string", "description": "This is an enumerated value that tells you where the recipient code is coming from", "enum": [ "recipient", "department" ] }, "trackingNumber": { "type": "string", "example": "TrackigID137", "description": "The primary identifier of a package, usually a carrier's tracking number" }, "secondaryTrackingNumber": { "type": "string", "example": "TRACK-1234", "description": "A secondary identifier for a package, can be generated internally" } } }, "PickupPackageRequest": { "type": "object", "required": [ "userId", "pickupRequests" ], "properties": { "userId": { "type": "string", "description": "The identifier of the user performing the package pickup operation.", "example": "user@gmail.com" }, "pickupRequests": { "type": "array", "description": "The list of package pickup requests.", "items": { "type": "object", "properties": { "pickupCode": { "type": "string", "description": "Pickup code associated with the deposited package.", "example": "NR8PBW" }, "lockerUnitId": { "type": "string", "description": "The unique identifier of the locker unit from which the package will be picked up.", "example": "7" }, "contactId": { "type": "string", "description": "The identifier of the recipient or department performing the pickup.", "example": "684a6b7bbc85e1bce739xxxx" }, "contactType": { "type": "string", "description": "The type of contact performing the pickup.", "example": "recipient", "enum": [ "recipient", "department" ] } } } } } }, "PickupPackageAdminRequest": { "type": "object", "required": [ "userId", "pickupRequests" ], "properties": { "userId": { "type": "string", "description": "Identifier of the administrator who performed the pickup action.", "example": "ADMIN001" }, "pickupRequests": { "type": "array", "description": "Collection of locker units are processed.", "items": { "type": "object", "properties": { "lockerUnitId": { "type": "string", "description": "Identifier of the locker unit containing the package.", "example": "1" } } } } } }, "PickupPackageAdminResponse": { "type": "object", "properties": { "userId": { "type": "string", "description": "Identifier of the administrator who performed the pickup action.", "example": "ADMIN001" }, "pickupRequests": { "type": "array", "description": "Collection of locker units are processed.", "items": { "type": "object", "properties": { "lockerUnitId": { "type": "string", "description": "Identifier of the locker unit containing the package.", "example": "1" } } } } } }, "PickupPackageResponse": { "type": "object", "properties": { "userId": { "type": "string", "description": "The identifier of the user performing the package pickup operation.", "example": "user@gmail.com" }, "pickupRequests": { "type": "array", "description": "The list of package pickup requests.", "items": { "type": "object", "properties": { "pickupCode": { "type": "string", "description": "Pickup code associated with the deposited package.", "example": "NR8PBW" }, "lockerUnitId": { "type": "string", "description": "The unique identifier of the locker unit from which the package will be picked up.", "example": "7" }, "contactId": { "type": "string", "description": "The identifier of the recipient or department performing the pickup.", "example": "684a6b7bbc85e1bce739xxxx" }, "contactType": { "type": "string", "description": "The type of contact performing the pickup.", "example": "recipient", "enum": [ "recipient", "department" ] } } } } } }, "LockerUnitOnHoldRequest": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "string", "description": "Identifier of the user perforrming the action.", "example": "ADMIN001" }, "Reason": { "type": "string", "description": "Reason for placing the locker unit on hold.", "example": "Order cancelled by recipient." } } }, "LockerUnitOnHoldResponse": { "type": "object", "description": "The response returned when account is On Hold for the locker unit.", "properties": { "userId": { "type": "string", "description": "Identifier of the user who performed the locker on hold action.", "example": "ADMIN001" }, "lockerBankId": { "type": "string", "description": "Unique identifier of the locker bank where the deposit was made.", "example": "LB001" }, "lockerUnitId": { "type": "string", "description": "Locker unit number where the package was deposited and is now on hold.", "example": "1" }, "parcelsReserved": { "type": "array", "description": "Identifier of multiple parcels.", "items": { "$ref": "#/components/schemas/Parcel" } }, "parcelsDeposited": { "type": "array", "description": "Identifier of multiple parcels.", "items": { "$ref": "#/components/schemas/Parcel" } } } }, "unauthorizedError": { "type": "object", "properties": { "message": { "type": "string", "example": "The request could not be completed.", "description": "This is HTTP 401 Unauthorized response status code, which indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource." } }, "required": [ "message" ] }, "serverError": { "type": "object", "properties": { "message": { "type": "string", "example": "The request could not be completed.", "description": "This is HTTP 500 Internal Server Error response status code, which indicates that the server encountered an unexpected condition that prevented it from fulfilling the request." } }, "required": [ "message" ] }, "invalidErrors": { "type": "array", "items": { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error code(s) that appear due to HTTP 400- Invalid or Bad Request, e.g., validation-error.", "example": "validation_error" }, "errorDescription": { "type": "string", "description": "HTTP 400 Bad Request response status code indicates that the server cannot process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).", "example": "userId - value missing." }, "additionalCode": { "type": "string", "description": "A unique identifier for the error, for example ILP10010, or ILP10030.", "example": "already_exists" }, "additionalInfo": { "type": "string", "description": "This is an additional information about the error. This error 'Invalid Request' might appear due to invalid data, or if the information is missing.", "example": "674eb7b67b34d787400fa453" }, "additionalParameters": { "type": "array", "items": { "type": "string", "example": "userId", "description": "The field(s) that might be incorrect in the request" } } } } }, "notFoundErrors": { "type": "array", "items": { "type": "object", "properties": { "errorCode": { "type": "string", "example": "not_found", "description": "Error code(s) that appear due HTTP 404 Page or File not found." }, "errorDescription": { "type": "string", "example": "resource not found", "description": "HTTP 404 Not Found response status code indicates that the server cannot find the requested resource." }, "additionalCode": { "type": "string", "example": "0100025", "description": "A unique identifier for the error, for example 0100025, 1110017, or 1090001." }, "additionalInfo": { "type": "string", "example": "Resource not found", "description": "The additional information about the error. This error 'Not Found' might appear due to `Shipment Not Found`, `No Shipments to close`, or `Original Transaction not found`." }, "additionalParameters": { "type": "array", "items": { "type": "string", "example": "userId", "description": "The field(s) that might be incorrect in the request." } } } } } }, "responses": { "UnauthorizedError": { "description": "The request could not be authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/unauthorizedError" } } } }, "InternalServerError": { "description": "The request could not be completed due to an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/serverError" } } } }, "BadRequestError": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invalidErrors" } } } }, "NotFoundError": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notFoundErrors" } } } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" }, "bearerAuth": { "type": "http", "scheme": "bearer" } } } }