# Create a pickup

Creates a pickup object. This request is for a carrier to come to a specified location to take a package for shipping.

Endpoint: POST /pickups
Version: 2018-02-08
Security: APIKeyHeader

## Header parameters:

  - `SHIPPO-API-VERSION` (string)
    Optional string used to pick a non-default API version to use. See our API version guide.
    Example: "2018-02-08"

## Request fields (application/json):

  - `carrier_account` (string, required)
    The object ID of your USPS or DHL Express carrier account. 
You can retrieve this from your Rate requests or our Carrier Accounts endpoint.
    Example: "adcfdddf8ec64b84ad22772bce3ea37a"

  - `location` (object, required)
    Location where the parcel(s) will be picked up.

  - `location.address` (object, required)
    The pickup address, which includes your name, company name, street address, city, state, zip code, 
country, phone number, and email address (strings). Special characters should not be included in 
any address element, especially name, company, and email.

  - `location.address.name` (string, required)
    required for purchase
First and Last Name of the addressee

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Either company or name required; No length validation (first 35 chars printed on label) |
    Example: "Shwan Ippotle"

  - `location.address.company` (string)
    Company Name

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 35 characters; Either company or name required |
    Example: "Shippo"

  - `location.address.street1` (string, required)
    required for purchase
First street line. Usually street number and street name (except for DHL Germany, see street_no).

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | At least one street line required; Max 35 characters per line |
    Example: "215 Clayton St."

  - `location.address.street2` (string)
    Second street line.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | At least one street line required; Max 35 characters per line |

  - `location.address.street3` (string)
    Third street line.
Only accepted for USPS international shipments, UPS domestic and UPS international shipments.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | At least one street line required; Max 35 characters per line |

  - `location.address.street_no` (string)
    Street number of the addressed building. 
This field can be included in street1 for all carriers except for DHL Germany.

  - `location.address.city` (string, required)
    required for purchase
Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates.
Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state
or a ZIP code (see below), if known, it will yield more accurate results.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Required; Max 35 characters |
    Example: "San Francisco"

  - `location.address.state` (string, required)
    required for purchase for some countries
State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some
countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers
only accept two or three character state abbreviations.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Required if country requires state; Max 2 characters for US, CA, PR |
    Example: "CA"

  - `location.address.zip` (string, required)
    required for purchase
Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more
accurate Rates.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 10 characters |
    Example: "94117"

  - `location.address.country` (string, required)
    ISO 3166-1 alpha-2 country codes and country names can be used. For most consistent results, we recommend using country codes like US or DE.
If using country names, please ensure they are spelled correctly and in English. Country names are converted to country codes.
Refer to this guide for a list of country codes.
Sending a country is always required.
    Example: "US"

  - `location.address.phone` (string)
    Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This
increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Required; Min 1, max 15 characters |
    Example: "+1 555 341 9393"

  - `location.address.email` (string)
    E-mail address of the contact person, RFC3696/5321-compliant.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 80 characters |
    Example: "shippotle@shippo.com"

  - `location.address.is_residential` (boolean)
    Example: true

  - `location.address.metadata` (string)
    A string of up to 100 characters that can be filled with any additional information you want 
to attach to the object.
    Example: "Customer ID 123456"

  - `location.address.validate` (boolean)
    Example: true

  - `location.building_location_type` (string, required)
    Where your parcels will be available for pickup. "Security Deck" and "Shipping Dock" are only 
supported for DHL Express.
    Enum: "Back Door", "Ring Bell", "Security Deck", "Shipping Dock", "Front Door", "Knock on Door", "In/At Mailbox", "Mail Room", "Office", "Other", "Reception", "Side Door"

  - `location.building_type` (string)
    The type of building where the pickup is located.
    Enum: "apartment", "building", "department", "floor", "room", "suite"

  - `location.instructions` (string)
    Pickup instructions for the courier. This is a mandatory field if the building_location_type is "Other".
    Example: "Behind screen door"

  - `metadata` (string)
    A string of up to 100 characters that can be filled with any additional information you 
want to attach to the object.

  - `requested_end_time` (string, required)
    The latest that you requested your parcels to be available for pickup. 
Expressed in the timezone specified in the response.

  - `requested_start_time` (string, required)
    The earliest that you requested your parcels to be ready for pickup. 
Expressed in the timezone specified in the response.

  - `transactions` (array, required)
    The transaction(s) object ID(s) for the parcel(s) that need to be picked up.
    Example: ["adcfdddf8ec64b84ad22772bce3ea37a"]

## Response 201 fields (application/json):

  - `carrier_account` (string, required)
    The object ID of your USPS or DHL Express carrier account. 
You can retrieve this from your Rate requests or our Carrier Accounts endpoint.
    Example: "adcfdddf8ec64b84ad22772bce3ea37a"

  - `location` (object, required)
    Location where the parcel(s) will be picked up.

  - `location.address` (object, required)
    The pickup address, which includes your name, company name, street address, city, state, zip code, 
country, phone number, and email address (strings). Special characters should not be included in 
any address element, especially name, company, and email.

  - `location.address.name` (string, required)
    required for purchase
First and Last Name of the addressee

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Either company or name required; No length validation (first 35 chars printed on label) |
    Example: "Shwan Ippotle"

  - `location.address.company` (string)
    Company Name

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 35 characters; Either company or name required |
    Example: "Shippo"

  - `location.address.street1` (string, required)
    required for purchase
First street line. Usually street number and street name (except for DHL Germany, see street_no).

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | At least one street line required; Max 35 characters per line |
    Example: "215 Clayton St."

  - `location.address.street2` (string)
    Second street line.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | At least one street line required; Max 35 characters per line |

  - `location.address.street3` (string)
    Third street line.
Only accepted for USPS international shipments, UPS domestic and UPS international shipments.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | At least one street line required; Max 35 characters per line |

  - `location.address.street_no` (string)
    Street number of the addressed building. 
This field can be included in street1 for all carriers except for DHL Germany.

  - `location.address.city` (string, required)
    required for purchase
Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates.
Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state
or a ZIP code (see below), if known, it will yield more accurate results.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Required; Max 35 characters |
    Example: "San Francisco"

  - `location.address.state` (string, required)
    required for purchase for some countries
State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some
countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers
only accept two or three character state abbreviations.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Required if country requires state; Max 2 characters for US, CA, PR |
    Example: "CA"

  - `location.address.zip` (string, required)
    required for purchase
Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more
accurate Rates.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 10 characters |
    Example: "94117"

  - `location.address.country` (string, required)
    ISO 3166-1 alpha-2 country codes and country names can be used. For most consistent results, we recommend using country codes like US or DE.
If using country names, please ensure they are spelled correctly and in English. Country names are converted to country codes.
Refer to this guide for a list of country codes.
Sending a country is always required.
    Example: "US"

  - `location.address.phone` (string)
    Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This
increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Required; Min 1, max 15 characters |
    Example: "+1 555 341 9393"

  - `location.address.email` (string)
    E-mail address of the contact person, RFC3696/5321-compliant.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 80 characters |
    Example: "shippotle@shippo.com"

  - `location.address.is_residential` (boolean)
    Example: true

  - `location.address.metadata` (string)
    A string of up to 100 characters that can be filled with any additional information you want 
to attach to the object.
    Example: "Customer ID 123456"

  - `location.address.validate` (boolean)
    Example: true

  - `location.building_location_type` (string, required)
    Where your parcels will be available for pickup. "Security Deck" and "Shipping Dock" are only 
supported for DHL Express.
    Enum: "Back Door", "Ring Bell", "Security Deck", "Shipping Dock", "Front Door", "Knock on Door", "In/At Mailbox", "Mail Room", "Office", "Other", "Reception", "Side Door"

  - `location.building_type` (string)
    The type of building where the pickup is located.
    Enum: "apartment", "building", "department", "floor", "room", "suite"

  - `location.instructions` (string)
    Pickup instructions for the courier. This is a mandatory field if the building_location_type is "Other".
    Example: "Behind screen door"

  - `metadata` (string)
    A string of up to 100 characters that can be filled with any additional information you 
want to attach to the object.

  - `requested_end_time` (string, required)
    The latest that you requested your parcels to be available for pickup. 
Expressed in the timezone specified in the response.

  - `requested_start_time` (string, required)
    The earliest that you requested your parcels to be ready for pickup. 
Expressed in the timezone specified in the response.

  - `transactions` (array, required)
    The transaction(s) object ID(s) for the parcel(s) that need to be picked up.
    Example: ["adcfdddf8ec64b84ad22772bce3ea37a"]

  - `object_created` (string)
    Date and time of Pickup creation.

  - `object_id` (string)
    Unique identifier of the given Pickup object.

  - `object_updated` (string)
    Date and time of last Pickup update.

  - `confirmed_start_time` (string)
    The earliest that your parcels will be ready for pickup, confirmed by the carrier. 
Expressed in the timezone specified in the response.
    Example: "2020-05-09T12:00:00Z"

  - `confirmed_end_time` (string)
    The latest that your parcels will be available for pickup, confirmed by the carrier. 
Expressed in the timezone specified in the response.
    Example: "2020-05-09T23:59:59.999Z"

  - `cancel_by_time` (string)
    The latest time to cancel a pickup. Expressed in the timezone specified in the response. 
To cancel a pickup, you will need to contact the carrier directly. 
The ability to cancel a pickup through Shippo may be released in future iterations.
    Example: "2020-05-09T08:00:00Z"

  - `status` (string)
    Indicates the status of the pickup.
    Enum: "PENDING", "CONFIRMED", "ERROR", "CANCELLED"

  - `confirmation_code` (string)
    Pickup's confirmation code returned by the carrier. 
To edit or cancel a pickup, you will need to contact USPS or DHL Express directly and provide your confirmation_code.
    Example: "WTC310058750"

  - `timezone` (string)
    The pickup time windows will be in the time zone specified here, not UTC.
    Example: "US/Pacific"

  - `messages` (array)
    An array containing strings of any messages generated during validation.
    Example: []

  - `is_test` (boolean)
    Indicates whether the object has been created in test mode.