# Schedule a pickup

Create a bill of lading and schedule a pickup with the carrier in one request. The BOL must be printed and given to the carrier at pickup.

Endpoint: POST /v-beta/ltl/pickups
Version: 1.1.202604070904
Security: api_key

## Request fields (application/json):

  - `carrier_id` (string, required)
    The carrier to use for this pickup
    Example: "aed2a8c0-7998-4fef-9a82-2cab5f527dc2"

  - `carrier` (object)
    Optional carrier instructions

  - `carrier.instructions` (string)
    Special instructions for the carrier
    Example: "Call 30 minutes before arrival"

  - `carrier.test` (boolean)
    Whether this is a test request

  - `options` (array)
    Accessorial services for the pickup

  - `options.code` (string)
    Example: "lftp"

  - `options.attributes` (object)

  - `shipment` (object, required)
    Shipment details

  - `shipment.service_code` (string, required)
    Service level code
    Example: "stnd"

  - `shipment.pickup_date` (string, required)
    Pickup date (YYYY-MM-DD)
    Example: "2021-10-01"

  - `shipment.pickup_window` (object)
    Pickup time window

  - `shipment.pickup_window.start_at` (string)
    Earliest pickup time (HH:MM:SS)
    Example: "08:00:00"

  - `shipment.pickup_window.end_at` (string)
    Latest pickup time (HH:MM:SS)
    Example: "12:00:00"

  - `shipment.pickup_window.closing_at` (string)
    Facility closing time (HH:MM:SS)
    Example: "17:00:00"

  - `shipment.packages` (array, required)

  - `shipment.ship_from` (object, required)
    Any residential or business mailing address, anywhere in the world.

> Note: Either name or company_name must be set. Both may be specified, if relevant.

  - `shipment.ship_from.name` (string, required)
    The name of a contact person at this address.  This field may be set instead of - or in addition to - the company_name field.
    Example: "John Doe"

  - `shipment.ship_from.phone` (string)
    The phone number of a contact person at this address.  The format of this phone number varies depending on the country.
    Example: "+1 204-253-9411 ext. 123"

  - `shipment.ship_from.email` (string,null)
    Email for the address owner.
    Example: "example@example.com"

  - `shipment.ship_from.company_name` (string,null)
    If this is a business address, then the company name should be specified here.
    Example: "The Home Depot"

  - `shipment.ship_from.address_line1` (string, required)
    The first line of the street address.  For some addresses, this may be the only line.  Other addresses may require 2 or 3 lines.
    Example: "1999 Bishop Grandin Blvd."

  - `shipment.ship_from.address_line2` (string,null)
    The second line of the street address.  For some addresses, this line may not be needed.
    Example: "Unit 408"

  - `shipment.ship_from.address_line3` (string,null)
    The third line of the street address.  For some addresses, this line may not be needed.
    Example: "Building #7"

  - `shipment.ship_from.city_locality` (string, required)
    The name of the city or locality
    Example: "Winnipeg"

  - `shipment.ship_from.state_province` (string, required)
    The state or province.  For some countries (including the U.S.) only abbreviations are allowed.  Other countries allow the full name or abbreviation.
    Example: "Manitoba"

  - `shipment.ship_from.postal_code` (string, required)
    postal code
    Example: "78756-3717"

  - `shipment.ship_from.country_code` (string)
    The two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)
    Example: "CA"

  - `shipment.ship_from.address_residential_indicator` (string)
    Indicates whether this is a residential address.
    Enum: "unknown", "yes", "no"

  - `shipment.ship_to` (object, required)
    Any residential or business mailing address, anywhere in the world.

> Note: Either name or company_name must be set. Both may be specified, if relevant.

  - `shipment.bill_to` (object, required)

  - `shipment.requested_by` (object, required)

## Response 200 fields (application/json):

  - `confirmation_number` (string)
    Carrier confirmation number
    Example: "CONF123456"

  - `pickup_id` (string)
    Unique pickup identifier
    Example: "se-pickup-123"

  - `quote_id` (string)
    Associated quote ID
    Example: "se-quote-456"

  - `pro_number` (string)
    PRO number assigned by carrier
    Example: "PRO789012"

  - `shipment_id` (string)
    ShipEngine shipment ID
    Example: "se-shipment-789"

  - `message` (string)
    Optional carrier message
    Example: "Pickup scheduled successfully"

  - `documents` (array)
    Generated documents (BOL)

  - `documents.type` (string)
    Example: "bill_of_lading"

  - `documents.format` (string)
    Example: "pdf"

  - `documents.image` (string)
    Base64-encoded document
    Example: "JVBERi0xLjQKJeLjz9M..."

  - `warnings` (array)
    Any carrier warnings

  - `warnings.external_code` (string)
    Example: "W001"

  - `warnings.message` (string)
    Example: "Residential delivery may require additional fees"

## Response 400 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, required)
    The source of the error, as indicated by the name this informs us if the API call failed because of the
carrier, the order source, or the ShipEngine API itself.
    Enum: "carrier", "order_source", "shipengine"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "auto_fund_not_supported", "batch_cannot_be_modified", "carrier_conflict", "carrier_disconnected", "carrier_not_connected", "carrier_not_supported", "confirmation_not_supported", "default_warehouse_cannot_be_deleted", "field_conflict", "field_value_required", "forbidden", "identifier_conflict", "identifiers_must_match", "insufficient_funds", "invalid_address", "invalid_billing_plan", "invalid_field_value", "invalid_identifier", "invalid_status", "invalid_string_length", "label_images_not_supported", "meter_failure", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "settings_not_supported", "subscription_inactive", "terms_not_accepted", "tracking_not_supported", "trial_expired", "unauthorized", "unknown", "unspecified", "verification_failure", "warehouse_conflict", "webhook_event_type_conflict", "customs_items_required", "incompatible_paired_labels", "invalid_charge_event", "invalid_object", "no_rates_returned", "file_not_found", "shipping_rule_not_found", "service_not_determined", "no_rates_returned", "funding_source_registration_in_progress", "insurance_failure", "funding_source_missing_configuration", "funding_source_error"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.carrier_id` (string)
    A string that uniquely identifies the carrier that generated the error.
    Example: "se-28529731"

  - `errors.carrier_code` (string)
    The name of the shipping carrier that generated the error, such as fedex, dhl_express, stamps_com, etc.
    Example: "dhl_express"

  - `errors.field_name` (string)
    The name of the field that caused the error
    Example: "shipment.ship_to.phone_number"

## Response 404 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, required)
    The source of the error, as indicated by the name this informs us if the API call failed because of the
carrier, the order source, or the ShipEngine API itself.
    Enum: "carrier", "order_source", "shipengine"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "auto_fund_not_supported", "batch_cannot_be_modified", "carrier_conflict", "carrier_disconnected", "carrier_not_connected", "carrier_not_supported", "confirmation_not_supported", "default_warehouse_cannot_be_deleted", "field_conflict", "field_value_required", "forbidden", "identifier_conflict", "identifiers_must_match", "insufficient_funds", "invalid_address", "invalid_billing_plan", "invalid_field_value", "invalid_identifier", "invalid_status", "invalid_string_length", "label_images_not_supported", "meter_failure", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "settings_not_supported", "subscription_inactive", "terms_not_accepted", "tracking_not_supported", "trial_expired", "unauthorized", "unknown", "unspecified", "verification_failure", "warehouse_conflict", "webhook_event_type_conflict", "customs_items_required", "incompatible_paired_labels", "invalid_charge_event", "invalid_object", "no_rates_returned", "file_not_found", "shipping_rule_not_found", "service_not_determined", "no_rates_returned", "funding_source_registration_in_progress", "insurance_failure", "funding_source_missing_configuration", "funding_source_error"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.carrier_id` (string)
    A string that uniquely identifies the carrier that generated the error.
    Example: "se-28529731"

  - `errors.carrier_code` (string)
    The name of the shipping carrier that generated the error, such as fedex, dhl_express, stamps_com, etc.
    Example: "dhl_express"

  - `errors.field_name` (string)
    The name of the field that caused the error
    Example: "shipment.ship_to.phone_number"

## Response 500 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, required)
    The source of the error, as indicated by the name this informs us if the API call failed because of the
carrier, the order source, or the ShipEngine API itself.
    Enum: "carrier", "order_source", "shipengine"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "auto_fund_not_supported", "batch_cannot_be_modified", "carrier_conflict", "carrier_disconnected", "carrier_not_connected", "carrier_not_supported", "confirmation_not_supported", "default_warehouse_cannot_be_deleted", "field_conflict", "field_value_required", "forbidden", "identifier_conflict", "identifiers_must_match", "insufficient_funds", "invalid_address", "invalid_billing_plan", "invalid_field_value", "invalid_identifier", "invalid_status", "invalid_string_length", "label_images_not_supported", "meter_failure", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "settings_not_supported", "subscription_inactive", "terms_not_accepted", "tracking_not_supported", "trial_expired", "unauthorized", "unknown", "unspecified", "verification_failure", "warehouse_conflict", "webhook_event_type_conflict", "customs_items_required", "incompatible_paired_labels", "invalid_charge_event", "invalid_object", "no_rates_returned", "file_not_found", "shipping_rule_not_found", "service_not_determined", "no_rates_returned", "funding_source_registration_in_progress", "insurance_failure", "funding_source_missing_configuration", "funding_source_error"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.carrier_id` (string)
    A string that uniquely identifies the carrier that generated the error.
    Example: "se-28529731"

  - `errors.carrier_code` (string)
    The name of the shipping carrier that generated the error, such as fedex, dhl_express, stamps_com, etc.
    Example: "dhl_express"

  - `errors.field_name` (string)
    The name of the field that caused the error
    Example: "shipment.ship_to.phone_number"