Getting started

Once you integrate with FedEx, you can start taking advantage of the value provided by FedEx APIs and webhooks. These instructions will guide you through the process of setting up an organization, creating projects, or getting started as a compatible user.


Step 1:

Browse APIs and webhooks

You can start by browsing our APIs and webhooks to determine your needs and identify the best solutions for your application.

  • Go to the API Catalog to start browsing.
  • Select an API or webhook to read an overview, explore the change log, and review key features..
Screenshot of ship api page
  • Review the documentation to learn more about request and response elements, examples in your programming language of choice, error codes, and more.
Screenshot of create shipment page
  • Check the Announcements page for planned service updates and learn what’s new.

Step 2:

Sign up or log in

Log in with your fedex.com user ID and password to begin integrating with FedEx APIs and webhooks.

If you do not have a user ID yet, you can sign up for free.


Step 3:

Create or join an organization.

Either create an organization, if one does not yet exist for your company, or join your company’s existing organization.

To create an organization:

If you create an organization, you will automatically be listed as the Admin of that organization.

  • An Admin can invite users to join their organization, assign them to roles(e.g. contributor or viewer) and projects, and can manage shipping accounts.
  • To learn more about these roles, explore our Organization Administration Guidelines.

To create your own organization, Click on Create Organization in the left-hand navigation.

Provide organization information

  • Provide your company name, website URL and create an organization name. Give your organization a name that other users will recognize. This name can be used to organize your company into more specific groups (e.g. department, division, region, location) or can be the same as your company name.
screenshot of Create your organization page

To join an organization:

You can join an already existing organization by completing the following steps:

  1. Ask the admin of your organization to send you an invite
  • If your company has already created an organization, ask the admin of the organization to invite you to join. You will have 24 hours to accept their invite. If you miss this window of time, you can always ask them to resend it.

  1. Accept the invite
  • To accept the invite, you will need to either log in with your existing user ID and password or, if your existing user ID is already associated with an organization, you will need to create a new one.

Step 4:

Add a shipping account.

  1. Complete account information
  • Enter your account number, an account nickname, and a billing address associated with the account. We will then validate the billing address to be sure it matches the account details in order to prevent fraudulent activities.
  • To view shipping accounts associated with your user ID, go to the Manage Organization page and the Shipping accounts tab. To create new shipping accounts, please contact your FedEx sales representative.
screenshot of Add Shipping Account page

  1. End User License Agreement
  • You must then accept the End User License Agreement (EULA)or send it to another individual within the end user company who can accept the agreement. You can view the status of the EULA on the Manage organization page, under the shipping account tab.

     

screenshot of Execute EULA page

Step 5: Add a billing account

An admin can add a billing account to their organization and assign it to projects. To begin, navigate to the Billing tab on the Manage Organization page. From there, you can open a new billing account on fedex.com and add the billing account to your organization on the FedEx developer Portal by completing the following steps:

1. Open a new billing account

  • First, open a new billing account at fedex.com. This step will redirect you from the FedEx Developer Portal to fedex.com.

2. Add billing account to your organization

  • Next, return to the Manage Organization page to add the account to your organization. You’ll need the account number and the address used to open the account for this step.
create billing account

3. Assign billing account to a project

  • Confirm the default billing account or add a new billing account to a project.

Step 6: Add users to your organization

An admin can invite users to their organization and assign them to roles and projects. To begin, click the Add Users button from the Users tab of the Manage Organization page. From there, you can add users by completing the following steps (those marked with an * are optional):

1. Enter users email addresses

  • Enter the email addresses of any users that you want to invite to join your organization. You can enter multiple email addresses by hitting a space, comma, semicolon, or enter key on your keyboard between addresses

2. Select user roles 

  • Choose a different user role if the default option of viewer doesn’t match that user’s needs.*

3. Assign users to a project

  • If you have already created projects, you can assign users to a project.*
Add shipping account

An admin will always have access to all projects, but a contributor or viewer must be assigned to a project (unless a contributor creates a project, in which case they will be automatically assigned to that project). 

 

Whether a user has accepted an invite yet or not, you can quickly update their projects or roles straight from the the Manage organization page, under the Users tab. 

  • Click on the caret beside the role or project, and a dropdown will appear with options. 
  • Select an option, then select the Apply button to save your selection.
Add shipping account 2

Step 1: 

Create a project to get credentials.

On the My projects page, go to the API tab.
 

An admin or contributor for your organization can create an API project by clicking on the Create a API Project button.

Before getting started, you will first need to let us know why you need to access FedEx APIs. A modal will appear and present you with dropdown options. You should select the option that best identifies your business needs for integrating with FedEx APIs.

If you identify as a shipper, you can begin to create your project. This is a three step process:

  1. Select APIs

Select the API(s) you want to include in your project. Based on the API(s) you select, you may need to make some additional selections.

If you select Track API, you will also need to:

  • Select an account number to associate with your production key.
  • Review the track API quotas, rate limits, and API certification details.
  • Choose whether or not you want to opt-in to emails that will notify you if you exceed your transaction quota.
create API project

  1. Configure project

Enter some project specifics, including name and shipping location.

  • Give your project an identifiable name that is unique to your organization
  • Select any countries you plan to ship within so that we can assign you a test shipping account. To test shipping packages domestically within a European country, you must have a separate test account for each country. You can always add/remove countries later.
  • To get notified about the latest API updates and any outage related information, you can set your notification preferences.
step2

  1. Confirm details

Review your project details, then accept the terms and conditions.

  • Read and accept the FedEx Developer Portal License Agreement and acknowledge that you do not intend to sell or distribute your application.
  • Once you click the "Create" button, you will see a confirmation screen. You can then view your test credentials within your new project.
step3

Step 2:

Integrate APIs & test your implementation

On the Project overview page, retrieve your test credentials — API key, secret key, and shipping
account(s) — from the Test key tab. Next, you can.

  • Request an OAuth access token, which must be used with each API transaction. The token is valid only for an hour, so you will need to programmatically code your application to refresh the token before the session expires. Refer to the API Authorization docs for more details
  • Click on any Docs for your APIs to read the business context for each API so you can best understand how to use it. You can also review example requests for the endpoint that matches your desired integration.
  • Implement your calls to these endpoints as described in the example requests, configuring them with your test credentials.
  • Verify that the API call responses you receive match those shown in the documentation.
  • Test your implementation within the FedEx test environment using your test credentials and the FedEx test URLs.
API project overview

Step 3:

Move your project to production

Click the Production key tab. You can now start to move your project to production by
completing the following steps.

 

Within the Configure project step:

  • You can rename your key as needed.
  • Review the account number that you selected in step 1 of the project creation flow. This is used to move your project to production. Once your project is live in production, you can add more accounts as needed.
production key tab

Within the Get project keys step:

  • Your production API key and production secret key will be displayed. Make sure to copy them to a secure place.
  • To keep your production secret key secure, we only display it once. If you lose it, you can generate a new one.
  • Click Next.
production key step2

You will now be brought back to the Project overview page. Here you can add more accounts associated with your project.

On the Project overview page:

  • Click on the 3 vertical dots (or kebab menu) to add more accounts associated with your project.
  • Next, click Edit.

This will bring you to the API key page where you can add any additional accounts you want to associate with your production key for this project.

API project overview after steps

Step 4:

Complete your certification

  1. Some APIs require shipping label certification for use in our production environment. Complete the certification process for any APIs in your project with this requirement.
API Certification
  1. After all APIs have been certified and enabled, update your API requests by replacing the test URIs, keys and shipping accounts with the production URIs, keys and shipping account.

  2. Retest your implementation in the production environment using sample data.

  3. Enjoy the benefits of your new integration!


Prerequisites to create a
webhook project


Step 1:

Learn about pricing

Customers are charged a monthly subscription fee for each webhook project, based on track number count. Learn more about pricing and subscription details on the Webhook Overview page.


Step 2:

Complete billing and shipping account set up

All webhook projects require your organization admin to complete the billing set up on the Manage Organization page. For account number-based subscriptions, your organization will also need to set up shipping accounts. See the Create Organization Getting Started Guide for step-by-step instructions on how to set up billing and shipping accounts.

step_2_img_1
step_2_img_2

Step 3:

Create a valid (call back) URL in your destination application/platform

Create a valid (call back) URL in your destination application/platform to receive authentication codes/messages and Shipping Visibility Webhook payload notifications from FedEx.

URL requirements:

•  Only HTTPS protocol is allowed
•  Your URL will be blocked if it meets any of the following conditions:
•  Includes RFC1918 IP space
•  Includes fedex.com or any of its subdomains
•  Includes IP addresses in the URL ( including localhost, 127.0.0.1)

Step 4:

Generate security token

This security token can be used as a secret key to authenticate and validate information transmitted between your organization and FedEx.

Security token requirements:

•   A minimum length of 25 characters and a maximum length of 100 characters
•   1 upper case character
•   1 lower case character
•   1 numeric character
Security token

Step 5:

Test webhook URL

Testing your URL is an optional step that you may find helpful.

Testing can help you get a better idea about whether the URL you created in step 1 is valid. It allows FedEx to identify your URL and build a connection with your URL to send data. Testing can also provide you with sample test data that can help you check and confirm whether you are able to process tracking data provided in your application. Testing does not, however, authenticate your URL.

Visit our webhook documentation to learn how to test your webhook URL.


Create a webhook project


Step 1:

Create a webhook project to receive configured payload notifications

On the  My Projects page, go to the Webhooks tab.

An admin for your organization, you can create a webhook project by clicking on the Create a Webhook project button.

You can begin to create your project by completing the following steps:

screenshot of create a webhook page

Identify your business needs

  • Select the option that best identifies why your business wants to integrate with FedEx webhooks.
img9

Select subscription type

  • Users can subscribe their events to account numbers or tracking numbers.
Subscription_type

Step 1 : Confirm billing account and select features

  • Confirm your billing account, or add a different billing account from your organization.
  • Features will vary for account number-based and tracking number-based subscriptions.
feature selection

Step 2 : Enter project details

  • Give your project an identifiable name.
  • Provide pre-generated destination (call back) URL and security token details, which are created during pre-setup authentication.
FIELD NAME
DESCRIPTION





Webhook project name

This is a non-empty, unique webhook project name
and should not be repeated in any other webhook
project.
• The webhook project name is auto-populated
  with a suggested name, which can be edited as
  needed.








Destination (call back) URL

This is the URL where you will receive the tracking
event data/payload.
• You should provide a working and valid
  destination (call back) URL.
• The destination (call back) URL provided must be
  in the standardized syntactical format (secure

 https URL, don’t include fedex.com or its sub
  domains in the URL).
• You can repeat the destination (call back) URL in

 multiple webhooks.








Security token

This is used as shared secret to authenticate and
validate the Shipment Visibility Webhook response.
• Token value must be a minimum length of

 25 characters and maximum of 100 characters.
• At least 1 uppercase, 1 lowercase, and 1 numeric

 character are required.
• You can repeat this security token in

 multiple webhooks.
• The security token will be used to create a hash-
  based

 message authentication Code (HMAC) signature

 for response validation.




Payload language (country)

Select the preferred language for your tracking data
translations from the drop-down list.






Tracking type

Select the type of response in which the tracking
data needs to be received.
• Detailed tracking response: response type

 consists of secured tracking data with entire
 
history of events
• Event-specific tracking response: response

 type consists of secured tracking data with only

 the most recent event information




Email address

Provide an email address to receive email
notifications when there are changes made to your
webhook project (e.g., created, edited, canceled).







Email language (country)

Select the preferred language in which you would
like to receive webhook email notifications from
FedEx.

These are the supported languages for email
notifications:
• English (United States)
• Spanish (United States)


create webhook step2

Step 3 : Choose shipping accounts*

*For account number-based subscriptions only

Choose from a list of eligible (U.S.-based) account numbers that you want to be associated with your project.

Confirm details and accept terms

   • Review your configured project details.
   • Read and accept the Developer Portal License Agreement, and acknowledge that you do not
      intend to distribute your application.
   • Once you click the Create button:
        1. If your create request was successfully validated and processed, you will be brought to a confirmation screen.
          •   If validation is unsuccessful or fails, there will be an error message.
        2. Your Shipment Visibility Webhook project will then have a system generated webhook ID and be shown to have an              “Active” status.

Assign tracking number API to your webhook project*

*For tracking number-based subscriptions only

  • After you have successfully created your webhook project, you will see an overview page where you can manage the project. On the Production keys tab, copy both the API key and secret key in a secure location.
  • Once click the Done button:
  • • You can regenerate the secret key at any time.
  • • See the API status for the assigned API and learn more in the links for Overview and Docs.
Project overview tab

Still have questions? We’ve got answers


Step 1: 

FedEx creates Compatible provider organization

  • FedEx will create an organization and then invite one team-member to join the organization. This user will be designated as the admin for your organization.
  • Upon completion of certification and integration, you will be able to distribute the solution to your customers with ease.

Step 2:

Accept invite.

  • In order to get access to the API integration artifacts and documentation, please accept the invite. To accept the invite, you will need to either log in with your FedEx User ID and password or create a new one if you don’t already have credentials.
Accept invite

Step 3:

Invite users to your organization.

  • As Admin, you are able to invite any team members that need access to the project or organization. For details on the different roles, view the Organization Administration Guide.
Manage org
  • If your organization has already been created, ask the Admin of the organization or FedEx to invite you to join. You will have 24 hours to accept their invite, but if you miss this window of time, you can ask them to resend it.

Step 4:

Select APIs you need for your solution.

  • Visit the API Catalog to determine the right APIs for your solution. Your FedEx Customer Technology Consultant (CTC) and Compatible Channel manager can help you select the right APIs for your solution as per your business needs.

API Catalog
  • Select an API to discover the overview, changelogs and key features.

Address validation API
  • View the API's documentation to uncover request and response elements, examples in your language of choice, error objects and more.

Address validation API-intro
  • Go back to Salesforce to fill out the Product Information Worksheet (PIW) and list out the APIs you would like to have added to your solution.


Step 5:

FedEx creates project(s).

Once the PIW has been approved, FedEx will create your project(s). Each version of each of your solutions will have a separate project within the FedEx Developer Portal. If a user is not an Admin of the organization, they would need to be invited to view each project. 

This is also when the FedEx Compatible team along with the FedEx CTC and certification teams will organize a technical demonstration for the APIs with your team. The FedEx team will discuss the new features and functionality available with the version of APIs you are adopting. The team will be able to address technical questions regarding APIs, API testing and all processes that need to be completed to start the process of ‘certification*’ for APIs.

* Certification – The process defined by the FedEx Compatible Program to satisfy Program Compliance requirements. Compatible Program Certification is required to ensure that all Compatible Providers implement, market and distribute FedEx technology to shippers (customers) as defined by FedEx technology & service standards.


Step 6:

Integrate APIs into your application and certify to the Compatible Program.

  1. You will now have access to your Test API Key and Test Secret Key to start running transactions. Retrieve them from the Test Key tab of the Project Overview page.
API project overview
  1. In order to create customer keys, you will need to use the Credential Registration API, which is a private API only found in the API section of each of your projects.
  2. Once you’ve created a few customer keys, go ahead and request an OAuth access token to be used with every API transaction. The session for the token is valid only for an hour, so you will need to programmatically code your application to refresh the token before the session expires. Refer to the API Authorization docs for more details. When viewing sample code, make sure “Reseller” is chosen from samples dropdown.
API Authorization
  1. Select docs for the APIs on your Test Keys page and read the business context to best understand how to use the selected API. Review example requests for the endpoint that match your desired integration.
  2. Implement your calls to these endpoints as described in the example requests, configuring them to use your test credentials.
  3. Verify that the received API call responses are matching those shown in the documentation.
  4. Completely test your implementation within the FedEx test environment using test credentials and the FedEx test URIs.
  5. After fully testing your solutions, certify each solution in Salesforce. FedEx will fully review everything submitted and update you once your certification is approved.

Step 7:

FedEx moves project(s) into production.

  • FedEx will then move your project(s) to production.
  • You will then be able to see your Production API Key under the Production Key tab of the Project Overview page.
API project overview tab2

Step 8:

Generate Production Secret Key.

  • Your Production Secret Key will need to be generated by clicking the Generate Secret key link under the Secret Key column.
  • You are now able to retest your implementation in the production environment using sample data.
  • Enjoy the benefits of your new integration!