# Search Package

This operation retrieves a list of packages based on the specified search criteria, such as tracking numbers, status, or associated metadata.

Endpoint: GET /api/v1/packages
Version: 1.0.0
Security: bearerAuth

## Query parameters:

  - `startDate` (string)
    Filter package created or updated on or after this date.

  - `endDate` (string)
    Filter assets created or updated on or before this date.

  - `page` (integer)
    The page number of the results to retrieve. Pagination starts from 1.

  - `size` (integer)
    The number of assets to retrieve per page.

  - `search` (string, required)
    Search criteria for asset fields such as tracking number. Use `fieldName:fieldValue` format.

  - `searchPosition` (string)
    Specify the position of the search match in the field. Values can include `starts` or `ends`.

  - `status` (string)
    Filter assets by status.

  - `location` (string)
    Filter packages by location ID. Use the unique identifier of the location.

  - `sort` (string)
    Specify the sorting order of the results. Format: `fieldName,DIRECTION`. DIRECTION can be `ASC` or `DESC`.

  - `secondTierSearchSelected` (boolean)
    Include secondary search criteria for the assets. Defaults to false.

  - `includeEmptyPackageLocation` (boolean)
    Add assets without a specified package location in the results. Defaults to true.

## Header parameters:

  - `Content-Type` (string)

## Response 200 fields (application/json):

  - `packages` (array)
    List of packages associated with the request.

  - `packages.packageId` (string)
    Unique identifier for the package.
    Example: X0vYqQp3obMPEM2DAlPwz

  - `packages.insertTimestamp` (string)
    The timestamp when the package was added.
    Example: 2025-02-13T07:12:28.302Z

  - `packages.updateTimestamp` (string)
    The timestamp when the package was last updated.
    Example: 2025-02-13T07:12:28.302Z

  - `packages.trackingNumber` (string)
    Tracking number assigned to the package.
    Example: XYZ123456

  - `packages.carrier` (object)

  - `packages.carrier.carrierId` (string)
    The unique identifier of the carrier being used.
    Example: FedEx

  - `packages.carrier.name` (string)
    Name of the carrier used.
    Example: FedEx

  - `packages.assetType` (string)
    Type of the asset (e.g., PACKAGE or POUCH)
    Example: PACKAGE

  - `packages.damaged` (boolean)
    If the package is marked damaged.
    Example: false

  - `packages.sender` (object)

  - `packages.sender.personalId` (string)
    The unique personal identifier of the contact.
    Example: jy32

  - `packages.sender.contactId` (string)
    The unique contact ID.
    Example: 5f508e6baa797f3c3d092307

  - `packages.sender.name` (string)
    The name of the contact.
    Example: contact_name

  - `packages.sender.company` (string)
    The company name associated with the contact.
    Example: company_name

  - `packages.sender.phone` (string)
    The phone number of the contact.
    Example: 1234567890

  - `packages.sender.email` (string)
    Email address of the contact.
    Example: user@email.com

  - `packages.sender.additionalEmailIds` (array)
    Additional email addresses associated with the contact.

  - `packages.sender.location` (object)

  - `packages.sender.location.inboundSiteId` (string)
    Unique identifier of the inbound site where the package is currently located.
    Example: zy0a23Bo4Gn0

  - `packages.sender.location.name` (string)
    Name of the current location of the package.
    Example: Site 1CD1001RMF

  - `packages.sender.location.parent` (string)
    The parent location, indicating the immediate hierarchical parent.
    Example: Site

  - `packages.sender.location.type` (string)
    Type of the current location (e.g., site, building, floor, mailstop).
    Example: site

  - `packages.sender.location.locationHierarchy` (string)
    Hierarchy path of the current location of the package in standard format, e.g., Site > Building > Floor > Mailstop.
    Example: Noida, Office of CG| Noida,Bldg| Noida,Floor| Noida,MS

  - `packages.sender.location.ancestorlist` (array)
    A list of ancestors in the location hierarchy, providing a traceable path to the current location.For example, [Site, Building, Floor].
    Example: ["k5OrZWe0ly6dg1v","gKP4RNbMzrPO","XbyR9zpPDneY"]

  - `packages.sender.location.topTier` (object)
    Details of the top-tier location in the hierarchy.

  - `packages.sender.location.topTier.inboundSiteId` (string)
    The unique Inbound Site ID of the top-tier location.
    Example: EMPTY_SITE

  - `packages.sender.location.topTier.name` (string)
    The name of the top-tier location.
    Example: EMPTY_SITE

  - `packages.comment` (string)
    User comments on the package.
    Example: User comments

  - `packages.currentLocation` (object)
    Current location details of the package.

  - `packages.currentLocation.inboundSiteId` (string)
    Unique identifier of the inbound site where the package is currently located.
    Example: zy0a23Bo4Gn0

  - `packages.currentLocation.name` (string)
    Name of the current location of the package.
    Example: Noida, Office of CG

  - `packages.currentLocation.type` (string)
    Type of the current location (e.g., site, building, floor, mailstop).
    Example: site

  - `packages.currentLocation.locationHierarchy` (string)
    Hierarchy path of the current location of the package  e.g., Site > Building > Floor > Mailstop
    Example: Noida, Office of CG

  - `packages.currentStatus` (string)
    Current status of the package.
    Example: RECEIVED

  - `packages.confirmationType` (string)
    The type of confirmation captured during the delivery of the package. 
Indicates proof of delivery, such as PHONE.
    Example: PHONE

  - `packages.additionalConfirmationType` (string)
    An additional type of confirmation captured during the delivery.
Like `confirmationType`, it can include values like SIGNATURE.

  - `packages.timezone` (integer)
    The timezone offset of the package in minutes.
    Example: -330

  - `packages.customFields` (array)
    List of custom fields associated with the package.Custom fields are additional package fields that can be added to display on PitneyTrack workflow pages.These fields can be defined from the 'My Settings' page in platform settings.

  - `packages.customFields.name` (string)
    Name of the custom field as defined by the user in the 'My Settings' page of platform settings.
    Example: End User

  - `packages.customFields.status` (string)
    Status of the custom field. Supported values are:
- ACTIVE: The custom field is currently in use.
- INACTIVE: The custom field is not in use.
    Example: ACTIVE

  - `packages.customFields.customFieldId` (string)
    Unique identifier for the custom field.
    Example: o1axRY2NKxq

  - `packages.customFields.value` (string)
    Value associated with the custom field, as set by the user.
    Example: end user

  - `totalCount` (integer)
    Total count of packages returned in the response.
    Example: 1

## Response 400 fields (application/json):

  - `errors` (array)
    List of errors.

  - `errors.errorCode` (string)
    This error can be validation_error or internal_error or not_found or already_exists
    Example: validation_error

  - `errors.errorDescription` (string)
    The 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: Asset not found.

  - `errors.additionalCode` (string)
    A unique identifier for the error
    Example: 020005

  - `errors.additionalInfo` (string)
    additional information of the error.
    Example: additional information

  - `errors.additionalParameters` (string)
    The field(s) that might be incorrect in the request.
    Example: additional parameters

  - `errors.correlationID` (string)
    Example: correlationId

## Response 401 fields (application/json):

  - `message` (string, required)
    This is HTTP 401 Unauthorized response status code, that indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.