# Create a return reservation

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.

Endpoint: POST /api/v1/lockerBanks/{lockerBankId}/lockers/asset/reserve
Version: 1.0.0
Security: bearerAuth

## Path parameters:

  - `lockerBankId` (string, required)
    The unique identifier of the locker bank where the return locker is reserved.
    Example: "AOne"

## Request fields (application/json):

  - `userId` (string, required)
    The identifier of the user performing the reservation action.
    Example: "user@gmail.com"

  - `size` (string, required)
    The size of the locker unit required for the return or asset drop-off.
    Example: "small"

  - `accessible` (boolean)
    Indicates whether an accessible locker unit is required.
    Example: true

  - `contactId` (string, required)
    The identifier of the contact or department that will receive the returned package or asset.
    Example: "684a6b7bbc85e1bce739xxxx"

  - `contactType` (string, required)
    The type of contact that will receive the returned package or asset.
    Enum: "recipient", "department"

  - `depositorContactId` (string, required)
    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` (string, required)
    The type of contact who will deposit the returned package or asset.
    Enum: same as `contactType` (2 values)

  - `trackingNumber` (string, required)
    The primary tracking number or identifier for the returned package or asset.
    Example: "TrackigID137"

  - `secondaryTrackingNumber` (string)
    The secondary tracking number or additional identifier for the returned package or asset.
    Example: "TRACK-1234"

  - `reservationExpiryTime` (string)
    The date and time when the reservation expires.
    Example: "2027-12-01T00:00:00Z"

## Response 200 fields (application/json):

  - `lockerBankId` (string)
    The unique identifier of the locker bank.
    Example: "AOne"

  - `lockerUnitId` (string)
    The locker unit reserved for the return or asset drop-off.
    Example: "2"

  - `size` (string)
    The size of the reserved locker unit.
    Example: "small"

  - `contactId` (string)
    The identifier of the contact or department that will receive the returned package or asset.
    Example: "684a6b7bbc85e1bce739xxxx"

  - `contactType` (string)
    The type of contact that will receive the returned package or asset.
    Enum: same as `contactType` (2 values)

  - `depositorContactId` (string)
    The identifier of the person or contact in the address book who will deposit the returned package or asset .
    Example: "684a6b7bbc85e1bxxxxxxxxx"

  - `depositorContactType` (string)
    The type of contact who will deposit the returned package or asset.
    Enum: same as `contactType` (2 values)

  - `depositorAccessCode` (string)
    The access code given to the depositor to open the locker and drop off the package or asset.
    Example: "NR8PBW"

  - `trackingNumber` (string)
    The primary tracking number or identifier for the returned package or asset.
    Example: "TrackigID137"

  - `reservationExpiryTime` (string)
    The date and time when the reservation expires.
    Example: "2027-12-01T00:00:00Z"

## Response 400 fields (application/json):

  - `errorCode` (string)
    Error code(s) that appear due to HTTP  400- Invalid or Bad Request, e.g., validation-error.
    Example: "validation_error"

  - `errorDescription` (string)
    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` (string)
    A unique identifier for the error, for example ILP10010, or ILP10030.
    Example: "already_exists"

  - `additionalInfo` (string)
    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` (array)
    Example: ["userId"]

## Response 401 fields (application/json):

  - `message` (string, required)
    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.
    Example: "The request could not be completed."

## Response 404 fields (application/json):

  - `errorCode` (string)
    Error code(s) that appear due HTTP 404 Page or File not found.
    Example: "not_found"

  - `errorDescription` (string)
    HTTP 404 Not Found response status code indicates that the server cannot find the requested resource.
    Example: "resource not found"

  - `additionalCode` (string)
    A unique identifier for the error, for example 0100025, 1110017, or 1090001.
    Example: "0100025"

  - `additionalInfo` (string)
    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.
    Example: "Resource not found"

  - `additionalParameters` (array)
    Example: ["userId"]

## Response 500 fields (application/json):

  - `message` (string, required)
    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.
    Example: "The request could not be completed."