# Schedule Pickup

Pickups endpoint allows you to schedule pickups with USPS, DHL Express, UPS and FedEx carriers for eligible shipments.
The pickup schedule scope is determined by what you provide in the request:
- **If pickupSummary is provided:** a pickup is scheduled for the packages described in the summary.
- **If shipmentIds are provided:** a pickup is scheduled for the specified shipments.
- **If both pickupSummary and shipmentIds are provided:** a pickup is scheduled for all shipments including by both inputs.
- **If neither is provided:** a pickup is scheduled for all shipments created on the given carrier account by that time of the day.
- **carrierAccountId handling:** `carrierAccountId` is required to schedule a pickup. Either provide `carrierAccountId` in the request payload, or provide `X-PB-LocationId` with a location that has only one carrier account configured for the selected carrier.

> Note: The sender's first name and last name are required for USPS. For example: `"name": "John Doe"`

Endpoint: POST /api/v1/pickups
Version: 1.0.0
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer

## Header parameters:

  - `X-PB-Developer-Partner-Id` (string)
    This is the Developer Partner ID. When the developer is the only partner, this field is not required.

  - `X-PB-LocationId` (string)
    The X-PB-LocationId header identifies the enterprise, division, or partner location under which a shipment is processed and billed.
If this header is not provided, the system automatically uses the enterprise-level location that was created during developer account onboarding. This default location is then used for shipment processing, carrier selection, and billing.

**Selection Rules**

------------------------
- If `X-PB-LocationId` is provided and the location has **one carrier with one account**:
  - `carrier` is optional
  - `carrierAccountId` is optional
  - The available carrier account is selected and the manifest is created.

- If `X-PB-LocationId` is not provided and the default location has **one carrier with one account**:
  - `carrier` is optional
  - `carrierAccountId` is optional
  - The available carrier account is selected and the manifest is created.
------------------------
- If `X-PB-LocationId` is provided and the location has **one carrier with multiple accounts**:
  - `carrier` is optional
  - `carrierAccountId` is required
  - The specified `carrierAccountId` is selected and the manifest is created.

- If `X-PB-LocationId` is not provided and the default location has **one carrier with multiple accounts**:
  - `carrier` is optional
  - `carrierAccountId` is required
  - The specified `carrierAccountId` is selected and the manifest is created.
---------------------------
- If `X-PB-LocationId` is provided and the location has **multiple carriers with one account each**:
  - `carrier` is required
  - `carrierAccountId` is optional
  - The specified `carrier` and its associated account are selected and the manifest is created.

- If `X-PB-LocationId` is not provided and the default location has **multiple carriers with one account each**:
  - `carrier` is required
  - `carrierAccountId` is optional
  - The specified `carrier` and its associated account are selected and the manifest is created.
----------------------------
- If `X-PB-LocationId` is provided and the location has **multiple carriers with multiple accounts**:
  - `carrier` is optional
  - `carrierAccountId` is required
  - The specified `carrierAccountId` is selected and the manifest is created.

- If `X-PB-LocationId` is not provided and the default location has **multiple carriers with multiple accounts**:
  - `carrier` is optional
  - `carrierAccountId` is required
  - The specified `carrierAccountId` is selected and the manifest is created.
-----------------------------

## Request fields (application/json):

  - `packageLocation` (string, required)
    The location where the parcel will be available for pickup at the specified pickup address.
    Enum: "Front", "Back", "Reception", "Loading Dock"

  - `carrierAccountId` (string)
    The unique identifier of the carrier account being used to process the pickup.
    Example: X4pqLKjQ5XX

  - `pickupAddress` (object, required)

  - `pickupAddress.name` (string, required)
    The name of the person or entity at the pickup address.
    Example: John Doe

  - `pickupAddress.addressLine1` (string, required)
    First line of the address where the pickup will occur.
    Example: 27 Waterview Dr

  - `pickupAddress.cityTown` (string)
    The city or town where the pickup address is located.
    Example: Shelton

  - `pickupAddress.stateProvince` (string)
    The state or province of the pickup address. For a US or Canadian address, it is the 2-letter state or province code.
    Example: CT

  - `pickupAddress.postalCode` (string, required)
    The postal or ZIP code for the pickup address. For US addresses, use either the 5-digit or 9-digit ZIP Code in one of the following formats: '12345' or '12345-6789'. If you use a different format, such as 12345- or 123451234, will receive an error.
    Example: 06484-4301

  - `pickupAddress.countryCode` (string, required)
    The two-letter country code for the pickup address.
    Example: US

  - `pickupAddress.phone` (string, required)
    The contact phone number for the pickup location.
    Example: 1234567890

  - `pickupAddress.company` (string)
    The name of the company at the pickup address, if the recipient address is not residential.
    Example: PB

  - `pickupAddress.email` (string)
    The email address associated with the pickup location.
    Example: ankita.chaurasia@pb.com

  - `pickupSummary` (array)
    An array of the pickup details, including the number of packages, total weight, and carrier service information and package details.

  - `pickupSummary.serviceId` (string)
    The abbreviated name of the carrier-specific service.
    Example: NDA

  - `pickupSummary.packageCount` (number)
    The total number of packages being picked up.
    Example: 2

  - `pickupSummary.totalWeight` (number)
    The total weight of all packages to be picked up, measured in units supported by the carrier in the origin country. The value is a decimal with up to 2 decimal places.
    Example: 15

  - `pickupSummary.weightUnit` (string)
    The unit of measurement for the total package weight.
    Example: OZ

  - `pickupSummary.currencyCode` (string)
    The currency code (e.g., 'USD') for the cost of the pickup service, if applicable.
    Example: USD

  - `pickupSummary.totalCustomsDeclaredValue` (number)
    Total customs declared value

  - `pickupSummary.packageDetails` (array)
    Details of each package being picked up, including package dimensions and weight.

  - `pickupSummary.packageDetails.width` (number)
    The width of the package in the unit specified by dimUnit.
    Example: 1

  - `pickupSummary.packageDetails.height` (number)
    The height of the package in the unit specified by dimUnit.
    Example: 15

  - `pickupSummary.packageDetails.length` (number)
    The length of the package in the unit specified by dimUnit.
    Example: 10

  - `pickupSummary.packageDetails.dimUnit` (string)
    The unit of measurement for the package dimensions.
    Example: IN

  - `pickupSummary.packageDetails.weightUnit` (string)
    The unit of measurement for the package weight.
    Example: OZ

  - `pickupSummary.packageDetails.weight` (number)
    The weight of the package in the unit specified by weightUnit.
    Example: 1

  - `additionalnotes` (string)
    Additional instructions or notes for the carrier regarding the pickup.
    Example: Call before pickup

  - `reference` (string)
    An optional Reference related to the pickup.
    Example: zscsdc

  - `shipmentIds` (array)
    List of shipment IDs for which pickup needs to be scheduled.

  - `pickupOptions` (object, required)

  - `pickupOptions.pickupStartDateTime` (string)
    The start date and time for the pickup in ISO 8601 format. This indicates when the pickup window begins.
    Example: 2024-10-10T17:03:05Z

  - `pickupOptions.pickupEndDateTime` (string)
    The end date and time for the pickup in ISO 8601 format. This indicates when the pickup window closes.
    Example: 2024-10-10T17:05:05Z

  - `pickupOptions.overweight` (integer)
    The number of overweight packages in the pickup. This represents the number of packages that exceed the carrier's weight limit.
    Example: 2

  - `pickupOptions.carrierType` (string)
    The type of carrier used for the pickup.
    Enum: "EXPRESS", "GROUND"

  - `pickupSummary` (array)
    An array of the pickup details, including the number of packages, total weight, and carrier service information.

  - `additionalnotes` (string)
    Additional instructions or notes for the carrier regarding the pickup.  Value is required when packageLocation is set to other.
    Example: absdhda

  - `shipmentIds` (array)
    A comma-separated list of shipment IDs associated with the pickup request.
    Example: ["USPS12345","USPS567890"]

  - `pickupOptions` (object, required)
    Pickup window options

  - `packageLocation` (string, required)
    The location where the shipment will be available for pickup at the specified pickup address.
    Enum: "NONE", "Front Door", "Back Door", "Side Door", "Shipping", "Receiving", "Mail Room", "Garage", "Office", "Reception", "In/At Mailbox", "Warehouse", "Basement", "Between Doors", "Counter", "Desk", "Front Desk", "Front Porch", "Gate House", "Kiosk", "Lab", "Loading Dock", "Lobby", "Mailbox", "Outside Door", "Parts Department", "Pharmacy", "Pro Shop", "Security", "Service Counter", "Switchboard", "Vault"

  - `pickupOptions` (object, required)
    Pickup window and freight-specific pickup details.

  - `pickupOptions.pickupStartDateTime` (string, required)
    The start date and time for the pickup in ISO 8601 format.
    Example: 2026-05-07T14:04:05Z

  - `pickupOptions.pickupEndDateTime` (string, required)
    The end date and time for the pickup in ISO 8601 format.
    Example: 2026-05-07T16:30:00Z

  - `shipmentIds` (array)
    An array of shipment identifiers associated with the pickup request.
    Example: ["CPC2202644757662548"]

  - `additionalNotes` (string, required)
    Additional instructions or notes for the carrier regarding the pickup.
    Example: notes

  - `shipmentIds` (array, required)
    The list of shipment IDs included in the pickup request.
    Example: ["794797605985"]

## Response 200:

  - `200` (unknown)
    The Pickup has been created successfully.

## Response 200 fields (application/json):

  - `packageLocation` (string)
    The location where the parcel will be available for pickup at the specified pickup address.
    Enum: "Front", "Back", "Reception", "Loading Dock"

  - `pickupConfirmationNumber` (string)
    The confirmation number generated when the pickup request is successfully processed.
    Example: CAME241011000909

  - `pickupId` (string)
    A unique identifier for the scheduled pickup.
    Example: DHLEXP10111728640015873

  - `carrier` (string)
    The carrier being used for the pickup.
    Example: dhlexp

  - `carrierAccountId` (string)
    The unique identifier of the carrier account being used to process the pickup.
    Example: j4pqLKjQ5dn

  - `pickupAddress` (object)

  - `pickupAddress.name` (string)
    The name of the person or entity at the pickup address.
    Example: Test

  - `pickupAddress.addressLine1` (string)
    First line of the address where the pickup will occur.
    Example: 27 Waterview Dr

  - `pickupAddress.cityTown` (string)
    The city or town where the pickup address is located.
    Example: Shelton

  - `pickupAddress.stateProvince` (string)
    The state or province of the pickup address. For a US or Canadian address, it is the 2-letter state or province code.
    Example: CT

  - `pickupAddress.postalCode` (string)
    The postal or ZIP code for the pickup address. For US addresses, use either the 5-digit or 9-digit ZIP Code in one of the following formats: '12345' or '12345-6789'. If you use a different format, such as 12345- or 123451234, will receive an error.
    Example: 06484-4301

  - `pickupAddress.countryCode` (string)
    The two-letter country code for the pickup address.
    Example: US

  - `pickupAddress.phone` (string)
    The contact phone number for the pickup location.
    Example: 1234567890

  - `pickupAddress.company` (string)
    The name of the company at the pickup address, if the recipient address is not residential.
    Example: PB

  - `pickupAddress.email` (string)
    The email address associated with the pickup location.
    Example: ankita.chaurasia@pb.com

  - `pickupAddress.residential` (boolean)
    Indicates whether the pickup address is a residential location. Set to 'false' for commercial addresses.
    Example: false

  - `pickupSummary` (array)
    An array of the pickup details, including the number of packages, total weight, and carrier service information.

  - `pickupSummary.serviceId` (string)
    The abbreviated name of the carrier-specific service.
    Example: NDA

  - `pickupSummary.packageCount` (number)
    The total number of packages being picked up.
    Example: 2

  - `pickupSummary.totalWeight` (number)
    The total weight of all packages to be picked up, measured in units supported by the carrier in the origin country. The value is a decimal with up to 2 decimal places.
    Example: 15

  - `pickupSummary.weightUnit` (string)
    The unit of measurement for the total package weight.
    Example: OZ

  - `pickupSummary.currencyCode` (string)
    The currency code (e.g., 'USD') for the cost of the pickup service, if applicable.
    Example: USD

  - `additionalNotes` (string)
    Additional instructions or notes for the carrier regarding the pickup.
    Example: absdhda

  - `pickupDateTime` (string)
    The sdate and time of the pickup window.
    Example: 2024-10-10T17:05:05Z

  - `pickupTotalWeight` (number)
    The total weight of all packages being picked up.
    Example: 16

  - `pickupTotalWeightUnit` (string)
    The unit of measurement for the total package weight.
    Example: OZ

  - `reference` (string)
    An optional Reference related to the pickup.
    Example: zscsdc

  - `pickupOptions` (object)

  - `pickupOptions.pickupStartDateTime` (string)
    The start date and time for the pickup in ISO 8601 format. This indicates when the pickup window begins.
    Example: 2024-10-10T17:03:05Z

  - `pickupOptions.pickupEndDateTime` (string)
    The end date and time for the pickup in ISO 8601 format. This indicates when the pickup window closes.
    Example: 2024-10-10T17:05:05Z

  - `pickupOptions.overweight` (integer)
    The number of overweight packages in the pickup. This represents the number of packages that exceed the carrier's weight limit.
    Example: 2

  - `pickupOptions.carrierType` (integer)
    The type of carrier is being used for pickup.
    Example: EXPRESS

  - `shipmentIds` (array)
    A comma-separated list of shipment IDs.
    Example: ["USPS12345","USPS567890"]

  - `pickupDateTime` (string)
    The date and time of the pickup.
    Example: 10/12/2024

  - `additionalnotes` (string)
    Additional instructions or notes for the carrier regarding the pickup.  Value is required when packageLocation is set to other.
    Example: Call before pickup

  - `shipmentIds` (array)
    An array of shipment identifiers associated with the pickup request.
    Example: ["PUROLATOR2202644757566914"]

  - `pickupDateTime` (string)
    The date and time of the pickup in ISO 8601 format.
    Example: 2026-05-07T14:04:05Z

  - `pickupRate` (object)
    The pickup rate details returned for the scheduled pickup.

  - `pickupRate.baseCharge` (number)
    The base pickup charge applied by the carrier.
    Example: 1.7

  - `pickupRate.pickupTaxes` (array)
    An array of taxes applied to the pickup charge.

  - `pickupRate.pickupTaxes.name` (string)
    The name of the tax applied to the pickup.
    Example: GST

  - `pickupRate.pickupTaxes.taxAmount` (number)
    The tax amount applied for the specified tax type.
    Example: 0.13

  - `pickupRate.totalCarrierCharge` (number)
    The total pickup charge including all applicable taxes.
    Example: 2.53

## Response 400:

  - `400` (unknown)
    Invalid request.

## 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)
    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: string

  - `additionalCode` (string)
    A unique identifier for the error, for example 1101055, 0100008, or 1021126.

  - `additionalInfo` (string)
    This is an additional information about the error. This error 'Invalid Request' might appear due to invalid dimension, weight, or serviceID, or if the information is missing.

  - `additionalParameters` (array)

## Response 401:

  - `401` (unknown)
    The request could not be authorized.

## 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.

## Response 500:

  - `500` (unknown)
    The request could not be completed due to an internal error.

## 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.