Postal Code Validation API
Introduction
FedEx Postal Code Validation API enables FedEx customers to validate postal codes and get the service commitments. It supports city, postal, country and Origin-Destination related lookups and the validations. It returns verified postal and location details in the reply.
Postal Code Validation API Details
The Postal Code Validation validates the postal codes for countries and cities and provides the cleaned postal code as a response. The correctly formatted postal codes are mandatory to process a shipment or create shipping labels.
This API uses the provided input information such as ship date, postal code, country code and other various information and checks for mismatch between state and city values. The City and State is set if a mismatch is found and if country is U.S. or CA. For examples: FDXE - FedEx Express®, FDXG - FedEx Ground® and FXSP - FedEx Ground® Economy (Formerly known as FedEx SmartPost®). The API validates the given input and provides location details and cleaned postal code.
FedEx supports services to both postal aware countries and non-postal aware countries.
Postal aware countries
Shipments to these countries should include the postal codes on the airway bills and other documentation to help reduce delays and maximize efficiency. FedEx Express customers should be encouraged to include valid postal codes in their addresses for recipients located in the below countries.
For more information on the Postal aware countries refer to Postal Aware Countries.
Non–Postal aware countries
As the name suggests, there are non-postal aware countries supported by FedEx that do not mandate postal codes in their shipments. State code or city name is enough when customer is shipping to a country which does not have a postal code. If validation error occurs for a country that does not use ZIP codes, try to force the address through by entering \"00000\" as a replacement postal code. Using this false postal code should not cause issues, as it does not exist.
The following are the benefits of using FedEx Postal Code Validation API:
- Reduces Shipping delays and increases efficiency.
- Increases number of on-time and complete deliveries.
- Improves FedEx service to urban areas, offering flexibility in cutoff times and pickup schedules.
How Postal Code Validation API works
The FedEx Postal Code Validation uses the below endpoint to validate the postal codes for cities, countries and origin-destination. The following section describes the key inputs and responses for the endpoint:
Validate Postal
This request is used to return postal details, cleaned postal code and location description based on input details. The key input information associated with this request are as follows:
- carrierCode
- countryCode
- stateOrProvinceCode
- postalCode
- shipDate
The successful result of this request are locationdetails and cleanedpostalcode for the provided input. The request would fail if the postalcode is not valid for example CountryCode, State/Province and ZIP/Postal code combination is not valid.
Clarification of Common Misconceptions
- It is not possible to cross-reference territory alignment to ZIP/postal alignment because these are distinctly separate alignment process outputs.
- Not all geographic locations in the world have postal or ZIP codes.
For more information on the Region Specific list, refer to Region Specific Service List.
Business Rules
- Combination of number, street name, etc. At least one line is required for a valid physical address; empty lines within the address are not allowed.
- 2-letter State or province code is required if recipient country is U.S. or Canada, or if EEI applies and country is Mexico {MX}.
- Descriptive data for a physical location, may be used as an actual physical address (place to which one could go), or as a container of \"address parts\" which should be handled as a unit (such as a city state-ZIP combination within the U.S.).
- Format and presence of postal code field will vary depending on country.
JSON API Collection
Postal Code Validation API (1.0.0)
Validate Postal
Use this endpoint to validate postal codes and service commitments. Supports city, postal, country and origin-destination related lookups and validations.
Note: FedEx APIs do not support Cross-Origin Resource Sharing (CORS) mechanism.
header Parameters
x-customer-transaction-id | string Example: 624deea6-b709-470c-8c39-4b5511281492 This element allows you to assign a unique identifier to your transaction. This element is also returned in the reply and helps you match the request to the reply. |
content-type required | string Example: application/json This is used to indicate the media type of the resource. The media type is a string sent along with the file indicating format of the file. |
x-locale | string Example: en_US This indicates the combination of language code and country code. Click here to see Locales |
authorization required | string Example: Bearer XXX This indicates the authorization token for the input request. |
Request Body schema: application/json
- FullSchema-ValidatePostal
- MinimumSamplePayload
carrierCode required | string Enum: "FDXE" "FDXG" "FXSP" "FDXC" "FXCC" Specify the four letter code of a FedEx operating company that meets your requirements
|
countryCode required | string The two-letter code used to identify a country. |
stateOrProvinceCode required | string This is the state or province code. Format and presence of this field will vary, depending on country. |
postalCode required | string Identification code of a region (usally small) for easier and accurate mail/package delivery. The format and presence of this field may vary depending on the country. |
shipDate required | string Specify the date on which the package is to be shipped. The specified date should not be the current date or any date, 10 days after the current date. The date format must be YYYY-MM-DD. |
routingCode | string Specify the routing code for the shipment. Routing code is the information that identifies the route the package or shipment may take. |
checkForMismatch | boolean This element checks for mismatch between State/Province Code and Postal Code.
For regions other than U.S and Canada regardless of the value of checkForMismatch the State/Province Code are checked with respect to the Postal Code and the response provides the respective State/Province Code and Postal Code. |
Responses
Success
Bad Request
Unauthorized
Forbidden
Not Found
Failure
Service Unavailable
Sandbox Server
Production Server
Request samples
- Payload
- C#
- JAVA
- JAVASCRIPT
- PHP
- PYTHON
- RUST
- SWIFT
- "carrierCode": "FDXG",
- "countryCode": "US",
- "stateOrProvinceCode": "US",
- "postalCode": "502267",
- "shipDate": "2019-10-04",
- "routingCode": "Memphis 38017 - HKA/NQA",
- "checkForMismatch": true
Response samples
- 200
- 400
- 401
- 403
- 404
- 500
- 503
- "transactionId": "624deea6-b709-470c-8c39-4b5511281492",
- "customerTransactionId": "AnyCo_order123456789",
- "output": {
- "countryCode": "US",
- "cityFirstInitials": "string",
- "stateOrProvinceCode": "US",
- "alerts": [
- {
- "code": "CITYNAME.POSTALCODE.REQUIRED",
- "alertType": "NOTE",
- "parameterList": [
- {
- "value": "string",
- "key": "string"
- "message": "We are unable to process this request. Please try again later or contact FedEx Customer Service."
- "locationDescriptions": [
- {
- "locationId": "MAAPD",
- "locationNumber": "6955",
- "serviceArea": "AA",
- "airportId": "BLR"
- "cleanedPostalCode": "94267"
Response