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..
- Review the documentation to learn more about request and response elements, examples in your programming language of choice, error codes, and more.
- 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.
To join an organization:
You can join an already existing organization by completing the following steps:
- 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.
- 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.
- 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.
- 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.
Step 5:
Add users to your organization
An Admin can invite users to their organization and assign them to roles and projects. To begin, you can Add Users from the Manage Organization page by completing the following steps (those marked with an * are optional):
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
Select user roles
- Choose a different user role if the default option of Viewer doesn’t match that user’s needs.*
Assign users to a project
- If you have already created projects, you can assign users to a project.*
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 the invite yet or not, you can quickly update their projects or roles straight from 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.
Step 1:
Create a project to get credentials.
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:
- 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.
- 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.
- 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.
Step 2:
Integrate APIs & test your implementation
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.
Step 3:
Move your project to production
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.
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.
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.
Step 4:
Complete your certification
- 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.
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.
Retest your implementation in the production environment using sample data.
Enjoy the benefits of your new integration!
Prerequisites for creating a webhook project
- Provide a valid destination (call back) URL to receive tracking updates
- Generate security token
- Test webhook URL
- Set up validation process for destination (call back) URL
Create a webhook project
Prerequisites for creating a webhook project
Step 1:
Provide valid destination (call back) URL to receive tracking updates
Provide a valid destination (call back) URL to receive authentication codes/messages and tracking 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 2:
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
Step 3:
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.
Step 4:
Set up validation process for destination (call back) URL
Using the HMAC SHA256 hashing algorithm method, set up an authentication process to validate the information transmitted between your destination URL and FedEx.
Validation process for destination (call back) URL:
These next steps outline the actual validation process, which will take place at the end of the Create a webhook project process.
- In the final step of creating a webhook project, once you click on “Create,” FedEx generates a random challengeString, which is sent to you in the request body. You are, in turn, expected to return this challengeString to FedEx in the request body.
- Initialize message authentication code (MAC) using HMAC SHA256 algorithm/procedure to hash the request body and security token (or secret key) to form the hash signature, also known as the challengeStringResponse. You should have this algorithm in place already.
- Respond to FedEx with the challengeString and challengeStringResponse together in the response body, along with HTTP status code 200 (OK) or 202 (ACCEPTED).
- After the response body is received by FedEx, FedEx will now validate the challengeString and challengeStringResponse by comparing it with the challengeString and challengeStringResponse generated by FedEx, respectively.
If both the challengeString and HMAC signatures match, then the validation and workflow has been successful. Otherwise, the validation process will fail, and a respective error message will be displayed..
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.
As 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:
- Select tier and tier features
- Select either a basic or advanced webhook tier for your project, based on your project needs.
- You can always edit your tier choice later.
- Each tier comes with a monthly subscription fee.
- Select the features that you want to be configured with your project.
- You can also edit your features later.
- Configure project details
- Give your project an identifiable name
- Provide pre-generated destination URL and security token details, which are created during pre-setup authentication.
- Visit Webhooks documentation for details on the configuration fields.
- Choose shipping accounts
- Choose from a list of eligible U.S.-based shipping 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 Createbutton:
- 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.
- Your tracking webhook project will then have a system generated webhook ID and be shown to have an "Active" status.
- If your create request was successfully validated and processed, you will be brought to a confirmation screen.
- FedEx creates Compatible provider organization.
- Accept invite.
- Invite users to your organization.
- Select APIs you need for your solution.
- FedEx creates project(s).
- Integrate APIs into your application and certify to the Compatible Program.
- FedEx moves project(s) into production.
- Generate Production Secret Key.
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.
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.
- 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.
Select an API to discover the overview, changelogs and key features.
View the API's documentation to uncover request and response elements, examples in your language of choice, error objects and more.
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.
- 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.
- 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.
- 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.
- 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.
- Implement your calls to these endpoints as described in the example requests, configuring them to use your test credentials.
- Verify that the received API call responses are matching those shown in the documentation.
- Completely test your implementation within the FedEx test environment using test credentials and the FedEx test URIs.
- 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.
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!
