FedEx Multi-Factor Authentication

Overview

In 2024, the global average data breach cost rose to $4.88 million—a 10% increase over 2023 and the highest total ever. To enhance security and align with new carrier requirements, EasyPost and FedEx are updating the FedEx integration to initiate FedEx’s Multi-Factor Authentication (MFA) flow. This change improves data protection and enables incremental access to FedEx’s new REST API, which requires MFA. 

Important Dates

What is Multi-Factor Authentication? 

Multi-factor authentication (MFA) is a security process requiring multiple forms of verification to access an account or system.

Benefits

• Increased security: Reduces the risk of unauthorized account access, even if passwords are compromised.
• Protection against phishing: Adds a layer of protection from attacks attempting to capture login credentials.
• Compliance requirements: Meets industry and organizational standards for securing sensitive data.

EasyPost FedEx Wallet Account

No action is required.

EasyPost FedEx International Connect Account

No action is required.

EasyPost Dashboard Process

Accounts integrated using BYOCA must complete authentication using one of four FedEx PIN validation methods. This includes but is not limited to customers with a FedEx Smart Post, now FedEx Ground Economy account.

Account Authentication

To update your FedEx accounts using the EasyPost Dashboard:

1. Log in to EasyPost and navigate to Account Settings.
2. Select the Carriers tab.
3. Locate the FedEx account and select Update.
   
    
4. Follow the FedEx authorization page prompts and choose a PIN validation type (Email, SMS, Call, or Invoice Number). Note: Access to email, phone number (for call or SMS), or an invoice number is required for authentication.
5. Scroll to the bottom of the End User License Agreement to Accept the Terms.
   
    
6. Enter FedEx account information.
   
    
7. Enter the received PIN into the field associated with the selected PIN validation method (Email, SMS, Call, or Invoice) to complete verification.
   
    
8. A success message will confirm that the carrier account was successfully updated.
   

MFA API Workflow

EasyPost also provides APIs for programmatically updating existing carrier accounts and creating new carrier accounts that have been Multi-Factor Authenticated and are enabled for the FedEx REST APIs.

REST Enablement and MFA Flow Options

Due to the multi-step nature of the Multi-Factor Authentication (MFA) process, multiple API calls are required. The specific calls vary depending on the selected validation flow. 

All validation flows require, at minimum, completion of the address validation step. The following information must be provided during this step:

• FedEx 9-digit account number 
• Shipping address associated with the FedEx 9-digit account number 
• EasyPost carrier account ID (required when updating an existing EasyPost carrier account).

After the address validation API call is completed, the process continues through one of the following validation flows:

• Pre-validation via FedEx Support (single API call required)
• PIN validation via SMS, phone call, or email (three API calls required)
  • The phone number or email address used for authentication must be associated with the FedEx account profile, not the fedex.com login credentials.
• Invoice validation (two API calls required)

The flowchart below outlines the steps for each validation path.

Pre-validation via FedEx Customer Support

Prerequisites and Required Information

• FedEx 9-digit account number
• Shipping address associated with the FedEx 9-digit account number
• EasyPost carrier account ID for the account being updated

When to use pre-validation via FedEx Support

This flow is used when standard MFA validation is difficult or not possible, such as: 

• Issues receiving email, SMS, or phone call verification codes 
• Invoice details are unavailable
• Should be attempted  prior to bypass flow

Pre-validation Process

This flow requires contacting FedEx at 877-339-2774. When prompted, state “FedEx API” (or press 4) to be routed appropriately. Inform the FedEx representative that the REST MFA pre-validation step must be completed over the phone.

Complete account validation over the phone with a FedEx representative. Request a ticket number for reference. The ticket number can assist EasyPost and FedEx if issues occur during the MFA process after pre-validation.

Once pre-validation is completed through the phone, the address validation step must be completed with EasyPost within seven (7) days. If the address validation step is not completed within this timeframe, pre-validation expires, and the standard MFA flow must be completed. If there are any issues with this process, please work with an EasyPost account representative to escalate so that EasyPost can assist with FedEx support. 

Required EasyPost API Call

This flow requires one EasyPost API call:

• Address Validation

Upon successful completion of the address validation call, the existing FedEx carrier account is updated with REST-enabled MFA credentials.

SMS, Phone Call, or Email Two-Factor Flow

Prerequisites and Required Information

• FedEx 9-digit account number
• Shipping address associated with the FedEx 9-digit account number
• EasyPost carrier account ID for the account being updated
• Real-time access to the phone or email address associated with the FedEx account

Required EasyPost API Calls

• Address Validation
• PIN Generation
• PIN Validation

Upon successful completion of the PIN validation call, the existing FedEx carrier account is updated with REST-enabled MFA credentials.

Invoice Validation Flow

Prerequisites and Required Information

• FedEx 9-digit account number
• Shipping address associated with the FedEx 9-digit account number
• EasyPost carrier account ID for the account being updated
• A FedEx invoice issued within the last 90 days for the account

Required EasyPost API Calls

• Address Validation
• Invoice Validation

Upon successful completion of the invoice validation call, the existing FedEx carrier account is updated with REST-enabled MFA credentials.

Creating or Updating EasyPost FedEx Carrier Accounts

Creating a New EasyPost FedEx Carrier Account

To create a new EasyPost FedEx carrier account, include the following easypost_details object:

{
  [...]
  "easypost_details": {
    "action": "create",
    "type": "FedexAccount",
  }
}

Supports creation of both FedexAccount (FedEx Ground, FedEx Express) and FedexSmartpostAccount (FedEx Ground Economy / SmartPost).  For FedexSmartpostAccount, the hub_id is required (see required values below).

Required Values

• action must be set to create
• type must be either FedexAccount or FedexSmartpostAccount 
• hub_id must be specified if creating a FedexSmartpostAccount
• carrier_account_id must be omitted or set to null

Updating an Existing EasyPost FedEx Carrier Account

To update an existing EasyPost FedEx carrier account, include the following easypost_details object:

{
  [...]
  "easypost_details": {
    "action": "update",
    "type": "FedexAccount",
    "carrier_account_id": "ca_123456778"
  }
}

Supports updating existing FedexAccount (FedEx Ground, FedEx Express) and FedexSmartpostAccount (FedEx Ground Economy / SmartPost) carrier accounts.  When updating a FedexSmartpostAccount, the existing hub_id value must also be specified  (see required values below).

Optional but Recommended Values

• action should be set to update or omitted
• type should be either FedexAccount or FedexSmartpostAccount, or omitted
• hub_id must be specified if creating a FedexSmartpostAccount and must match the hub_id value already configured on the carrier account
• carrier_account_id must be a valid EasyPost carrier account ID in the format ca_abcdef123456

API Calls

All MFA flows require one or more of the following API calls. Each flow begins with the Address Validation request.

Refer to REST Enablement and MFA Flow Options for details on each flow and its requirements.

Address Validation

This call must be completed first for all MFA flows. For the pre-validation flow, this is the only required API call.

The address provided must be the shipping address associated with the FedEx 9-digit account number.

Request

## Address Validation - API Step 1
curl -X POST https://api.easypost.com/v2/fedex_registrations/FEDEX_ACCOUNT_NUMBER/address \
-u {YOUR_API_KEY_HERE}: \
-H 'Content-Type: application/json' \
-d '{
  "address_validation": {
    "name": "Account Name",
    "street1": "1234 My Address",
    "city": "MyCity",
    "state": "ST",
    "postal_code": "12345",
    "country_code": "US"
  },
  "easypost_details": {
    "action": "update",
    "type": "FedexAccount",
    "carrier_account_id": "ca_123456778"
  }
}'

Response - Multi-Factor Authentication Required

{"email_address":null,"options":["SMS","CALL","INVOICE"],"phone_number":"***-***-9721"}

This response indicates that additional validation is required. Proceed to either the 

PIN Validation flow or Invoice Validation flow.

Response - Multi-Factor Authentication Complete

If Pre-Validation via FedEx Support was completed, carrier account details are returned:

{"id":"ca_123456778","object":"CarrierAccount","type":"FedexAccount","credentials":{"account_number":"778646013","mfa_key":"561f523a-XXXXX"}

The presence of both the carrier account ID (ca_123456778) and mfa_key confirms that the account is REST-enabled and MFA has been successfully completed.

PIN Generation

This call is available after successful completion of the Address Validation request. Available authentication options depend on account configuration and may include SMS, phone call, or email.

Request

## Pin Generation - API Step 2
curl -X POST 
https://api.easypost.com/v2/fedex_registrations/FEDEX_ACCOUNT_NUMBER/pin \
-u {YOUR_API_KEY_HERE}: \
-H 'Content-Type: application/json' \
-d '{
  "pin_method": {
    "option": "CALL"   # can be EMAIL as well
  },
  "easypost_details": {
    "action": "update",
    "type": "FedexAccount",
    "carrier_account_id": "ca_12345",
  }
}'

Response

{"message":"sent secured Pin"}

After this request is completed, the authentication code is delivered to the selected phone number or email address. Proceed to PIN Validation after the code is received.

PIN Validation 

Submit the authentication code received during the PIN Generation step.

Request

## Pin Validation - API Step 3 / Final
curl -X POST https://api.easypost.com/v2/fedex_registrations/FEDEX_ACCOUNT_NUMBER/pin/validate \
-u {YOUR_API_KEY_HERE}: \
-H 'Content-Type: application/json' \
-d '{
  "pin_validation": {
    "pin_code": "{RECEIVED_PIN}",
    "name": "{NAME OF ACCOUNT}"
  },
  "easypost_details": {
    "action": "update",
    "type": "FedexAccount",
    "carrier_account_id": "ca_12345",
  }
}'

Response

{"id":"ca_123456778","object":"CarrierAccount","type":"FedexAccount","credentials":{"account_number":"778646013","mfa_key":"561f523a-XXXXX"}

The presence of both the carrier account ID (ca_123456778) and mfa_key confirms that the account is REST-enabled and MFA has been successfully updated.

Invoice Validation 

After completing the Address Validation step, submit invoice details from a FedEx invoice issued within the last 90 days.

Request

## Invoice Validation - API Step 2 / Final
curl -X POST https://api.easypost.com/v2/fedex_registrations/FEDEX_ACCOUNT_NUMBER/invoice \

-u {YOUR_API_KEY_HERE}: \
-H 'Content-Type: application/json' \
-d '{
  "invoice_validation": {
    "name": "{NAME}",
    "invoice_number": "{INVOICE_NUMBER}",
    "invoice_date": "{DATE}",
    "invoice_amount": "{AMOUNT}",
    "invoice_currency": "{CURRENCY}"
  },
  "easypost_details": {
    "action": "update",
    "type": "FedexAccount",
    "carrier_account_id": "ca_12345",
  }
}'

Response

{"id":"ca_123456778","object":"CarrierAccount","type":"FedexAccount","credentials":{"account_number":"778646013","mfa_key":"561f523a-XXXXX"}

The presence of both the carrier account ID (ca_123456778) and mfa_key confirms that the account is REST-enabled and MFA has been successfully completed.

Troubleshooting

Endpoint Issues

If issues occur with the MFA endpoints, consider creating or updating the EasyPost FedEx account using the EasyPost Dashboard. For further assistance, contact support@easypost.com.

Verifying Account Number and Contact Information

Account information such as email and phone number can be reviewed at fedex.com. 

1. Log into fedex.com using the credentials associated with the attempted EasyPost authorization.
2. Navigate to Accounts > My profile.
   
    
3. Select Review to confirm contact details.
   
    
4. Confirm account information.
   
   Note: The address displayed under profile settings is not used for MFA validation. The required address is the shipping address associated with the FedEx account. See below for how to obtain the Shipping Address associated with the account.
    
5. Click Account Management to review the Account Number.
   
    
6. For the Address Verification step, visit the Shipping Administration page:
   https://www.fedex.com/apps/shipadmin/?wpro=true#!accounttable
7. Select the account being updated:
   
    
8. Review the Shipping Address:
   

MFA Bypass Flow for Customers with Multiple FedEx Accounts

The FedEx MFA bypass flow reduces repeated authentication prompts for customers managing multiple FedEx accounts. 

This process is recommended for customers with more than 20 FedEx accounts. Account holders should attempt pre-validation through FedEx support before requesting the bypass flow through EasyPost.

Enabling the Bypass Flow

To enable the bypass flow, contact EasyPost Support and include an Excel spreadsheet listing the FedEx 9-digit account numbers that require the bypass flow. 

Requirements

• A file containing valid 9-digit FedEx Account Number(s)
• Completion of Address Validation within seven (7) days after bypass approval. If the 7-day window is missed, bypass approval must be re-requested.
• Address verification must be completed for each individual FedEx account

FedEx SmartPost REST Migration Error

Some customers may encounter the following error during REST MFA validation or usage:

SYSTEM.UNEXPECTED.ERROR: GENERAL FAILURE {FAILURE_CAUSE}. Please update and try again

This issue must be handled on a per-account basis. Resolution requires API request/response transcripts and direct contact with FedEx to determine the root cause. 

FedEx requires validation using account-specific details. As a result, issues of this type cannot be escalated on behalf of the account holder.

In some cases, this error may be caused by limitations or configuration issues within the FedEx account (e.g., unavailable Ground Economy identifiers associated with REST credentials).

FAQs

Q: When will FedEx start deprecating SOAP APIs? 

A: FedEx will begin deprecation on May 1, 2026. 

Q: How long does it take for the PIN validation to be sent once I select an authentication method? 

A: Most PINs are delivered within two minutes. 

Q: How long is the PIN valid? 

A: PINs remain valid for 10 minutes. 

Q: Will EasyPost FedEx account generation still be available through the EasyPost API with FedEx MFA?

A: Yes. However, the legacy APIs generating SOAP credentials are being deprecated. You are encouraged to update to the FedEx Multi-Factor APIs for EasyPost FedEx account generation.

Q: Will EasyPost Dashboard FedEx account generation still be available with FedEx MFA?

A: Yes. 

Q: How will this change adding new FedEx accounts through the API? 

A: A new endpoint is available to authenticate after you create accounts through the API.

Q: How will I authenticate existing accounts through the API? 

A: Use the endpoint above to authenticate your existing FedEx accounts through the API. 

Q: How will I authenticate existing accounts through the EasyPost dashboard? 

A: Follow the documented steps above to authenticate your existing FedEx accounts. 

Q: How often do I need to authenticate my FedEx accounts through the FedEx MFA process?

A: This process only needs to be completed once per EasyPost FedEx carrier account. The credentials do not expire, and the FedEx MFA process does not need to be repeated in the future.

Q: What address should I use to validate my accounts? 

A: Use the shipping address associated with your FedEx 9-digit account.  This is available by viewing the account details for the account you are updating here:

https://www.fedex.com/apps/shipadmin/?wpro=true#!accounttable

Q: What phone number should I use to validate my accounts? 

A: Use the phone number associated with your FedEx account. 

Q: How long do I have to complete the subsequent calls (pin/invoice validation) until the address verification token expires?

A: You will have 30 minutes. 

Q: When can I attempt to update my account again after receiving the following error message:  

"code": "UNPROCESSABLE_ENTITY", 

"message": "PIN.MAXRETRY.EXCEEDED: Max retry exceeded for PIN Generation."

A: You will need to wait 24 hours before attempting verification again. This is a limit enforced by FedEx.

Q:  Is there anything else I need to consider for the FedEx REST migration? 

A: No,  if you have previously provided Easypost with a signature and letterhead, we will automatically migrate your previously provided images to the FedEx REST APIs.  If you wish to update these images, you will need to contact EasyPost support. Process is below: 

1. Reach out to Easypost support, stating that you ship internationally with FedEx, and you need to upload a new signature and letterhead for REST migration. 
2. Easypost support will then create a ticket and upload your signature and letterhead to support your international shipments. 
3. Easypost support will follow up confirming when this step is completed. 

Q: Will I still be able to create new accounts with FedEx SOAP? 

A: No, as of March 15th, SOAP account creation will be disabled as FedEx starts to prepare for REST migration and SOAP sunsetting efforts. 

Q: What happens if I follow the programmatic/API flows on a single carrier account multiple times?

A: You can call the EasyPost Multi-Factor Authentication APIs multiple times on the same carrier account.  If the carrier account has already been updated, you will still be able to complete the process again.  There is no benefit in doing so; it will simply generate a new set of internal EasyPost FedEx credentials for your account.