# Carrier facilities

This operation locates Post Offices and other facilities for a given carrier. You can use this operation, for example, to locate all USPS Post Offices near a given postal code.

Endpoint: POST /api/v1/carrier-facility
Version: 1.0.0
Security: bearerAuth

## Request fields (application/json):

  - `address` (object, required)
    Address details used as the reference point for the facility search or returned
as part of a carrier facility suggestion.

  - `address.addressLine1` (string)
    The primary street address line.
    Example: 24182 Kathy Ave

  - `address.addressLine2` (string)
    Additional address information such as building, floor, or nearby landmark.
    Example: near abc street

  - `address.addressLine3` (string)
    Optional third line for additional address details.
    Example: near xyz street

  - `address.company` (string)
    Company or organization name at the address.
    Example: Pitney Bowes Inc.

  - `address.email` (string)
    Email address associated with the contact at this address.
    Example: testuser@gmail.com

  - `address.phone` (string)
    Phone number associated with the contact at this address.
    Example: 6502530000

  - `address.cityTown` (string)
    City or town name.
    Example: Lake Forest

  - `address.stateProvince` (string)
    State or province code.
    Example: CA

  - `address.postalCode` (string, required)
    Postal or ZIP code.
    Example: 92630

  - `address.countryCode` (string, required)
    The two-letter ISO country code.
    Example: US

  - `carrier` (string, required)
    The carrier for which to locate facilities. This operation currently supports searching for USPS facilities.
    Example: USPS

  - `carrierFacilityOptions` (array)
    Filters the types of facilities returned. Each object in the array is a name-value pair that specifies a carrier facility option. Each object contains a `name` field (the option) and a `value` field (the option value). Both fields take strings.
    Example: [{"name":"FACILITY_TYPE","value":"POST_OFFICE"},{"name":"FACILITY_TYPE_SERVICE","value":"LABEL_BROKER_RETAIL"},{"name":"FACILITY_WITHIN_RADIUS","value":"10"},{"name":"NUMBER_OF_FACILITIES","value":"1"…

  - `carrierFacilityOptions.name` (string)
    The option name that controls a specific aspect of the facility search.
**Facility Options**
| Name | Description | Value |
|  --- | --- | --- |
| FACILITY_TYPE | The type of facility to return. By default, the API returns type `POST_OFFICE`. | POST_OFFICE |
| FACILITY_TYPE_SERVICE | A service the facility must offer. The API returns only facilities that provide this service. | LABEL_BROKER_RETAIL, LABEL_BROKER_SELF_SERVICE_KIOSK |
| FACILITY_WITHIN_RADIUS | Distance from the buyer in miles. | Default: 5, Max: 25 |
| NUMBER_OF_FACILITIES | Number of facilities to return. To return only the closest one, set this to 1. | Default: 5, Max: 50 |

  - `carrierFacilityOptions.value` (string)
    The value for the given option name.

## Response 200 fields (application/json):

  - `address` (object)
    Address details used as the reference point for the facility search or returned
as part of a carrier facility suggestion.

  - `address.addressLine1` (string)
    The primary street address line.
    Example: 24182 Kathy Ave

  - `address.addressLine2` (string)
    Additional address information such as building, floor, or nearby landmark.
    Example: near abc street

  - `address.addressLine3` (string)
    Optional third line for additional address details.
    Example: near xyz street

  - `address.company` (string)
    Company or organization name at the address.
    Example: Pitney Bowes Inc.

  - `address.email` (string)
    Email address associated with the contact at this address.
    Example: testuser@gmail.com

  - `address.phone` (string)
    Phone number associated with the contact at this address.
    Example: 6502530000

  - `address.cityTown` (string)
    City or town name.
    Example: Lake Forest

  - `address.stateProvince` (string)
    State or province code.
    Example: CA

  - `address.postalCode` (string, required)
    Postal or ZIP code.
    Example: 92630

  - `address.countryCode` (string, required)
    The two-letter ISO country code.
    Example: US

  - `carrier` (string)
    The carrier used for the facility lookup.
    Example: USPS

  - `carrierFacilityOptions` (array)
    Filters the types of facilities returned. Each object in the array is a name-value pair that specifies a carrier facility option. Each object contains a `name` field (the option) and a `value` field (the option value). Both fields take strings.

  - `carrierFacilityOptions.name` (string)
    The option name that controls a specific aspect of the facility search.
**Facility Options**
| Name | Description | Value |
|  --- | --- | --- |
| FACILITY_TYPE | The type of facility to return. By default, the API returns type `POST_OFFICE`. | POST_OFFICE |
| FACILITY_TYPE_SERVICE | A service the facility must offer. The API returns only facilities that provide this service. | LABEL_BROKER_RETAIL, LABEL_BROKER_SELF_SERVICE_KIOSK |
| FACILITY_WITHIN_RADIUS | Distance from the buyer in miles. | Default: 5, Max: 25 |
| NUMBER_OF_FACILITIES | Number of facilities to return. To return only the closest one, set this to 1. | Default: 5, Max: 50 |

  - `carrierFacilityOptions.value` (string)
    The value for the given option name.

  - `carrierFacilitySuggestions` (array)
    List of facilities that match the search criteria

  - `carrierFacilitySuggestions.carrierFacilityAttributes` (array)
    List of facility attributes that describe the services available at this location.
This array is populated only when:
- You did not specify a FACILITY_TYPE_SERVICE value in the request, and
- A FACILITY_TYPE_SERVICE value applies for the facility.

Each object in the array is a name–value pair describing a facility service.
Both `name` and `value` are strings.
Note: If you specified a FACILITY_TYPE_SERVICE value in the request,
this array does not populate in the response.

  - `carrierFacilitySuggestions.carrierFacilityAttributes.name` (string)
    Name of the facility attribute or service.
    Example: FACILITY_TYPE_SERVICE

  - `carrierFacilitySuggestions.carrierFacilityAttributes.value` (string)
    Value for the facility attribute or service.
    Example: LABEL_BROKER_RETAIL

  - `carrierFacilitySuggestions.facilityHours` (array)
    Days and hours of operation for the facility. Each object in the array defines
the hours for a specific day of the week.

  - `carrierFacilitySuggestions.facilityHours.day` (string)
    Day of the week for the facility's operating hours.
Possible values:
- SUNDAY
- MONDAY
- TUESDAY
- WEDNESDAY
- THURSDAY
- FRIDAY
- SATURDAY
    Example: MONDAY

  - `carrierFacilitySuggestions.facilityHours.facilityTimings` (array)
    A specific opening and closing time range for a facility on a given day.Returned as part of the `facilityTimings` array.

  - `carrierFacilitySuggestions.facilityHours.facilityTimings.opensAt` (string)
    The time the facility opens, using a 24-hour clock. The time is local to the facility.
Format: `HH:MM` or `HH:MM:SS`
    Example: 09:00:00

  - `carrierFacilitySuggestions.facilityHours.facilityTimings.closesAt` (string)
    The time the facility closes, using a 24-hour clock. The time is local to the facility.
Format: `HH:MM` or `HH:MM:SS`
    Example: 17:00:00

  - `carrierFacilitySuggestions.facilityParking` (string)
    The type of parking available at the facility.
Values include:
- NONE
- LOT
- STREET
    Example: LOT

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