The FuelCloud API is available by request only. Please follow the link below to apply for API access.
Request API Access Here!
Introduction
The FuelCloud Web API lets your own software read your FuelCloud transaction data and manage your assets, such as tanks, sites, vehicles, drivers and access groups, without logging in to the web portal. It is available to approved FuelCloud customers on request.
This guide explains what the API can do, how access and authentication work, and how to plan an integration. It does not list endpoints or request formats; those are in the FuelCloud developer documentation, which is shared with your team once API access is enabled.
Who this is for: account administrators deciding whether the API fits their needs, and developers on approved accounts who want the concepts before reading the technical reference.
One account per set of credentials. The API only returns data for the FuelCloud account whose credentials you use. A jobber using its own account's credentials sees the jobber account's data, not its customers' accounts. To work with a customer account's data, use credentials created in that customer account.
Getting access
API access is not turned on by default. It is enabled per company on request. FuelCloud reviews each request so we can support every integration and keep data quality high.
- Complete the API access request form (Request API Access Here!). It asks for the requester's name, your company, and a short description of how you plan to use the API.
- Allow up to 1 business day for FuelCloud to review the request and enable access.
- You will be contacted by email when your access has been granted.
Once access is enabled for your company, any web portal user with permission to Settings > API can create API credentials and access the developer documentation. If you need separate credentials for different systems or people, create additional web portal users with permission to access Settings > API.
The developer documentation link can be found under Settings > API and is for accounts with API access only. Please don't share it outside your organization.
Authentication
Every API call is authenticated with an access token that expires quickly and is renewed with a longer lasting refresh token. It works much like a web portal login, but for software. You create your first pair of tokens in the web portal under Settings > API.
| Token | What it does | Valid for |
|---|---|---|
| Access token | Sent with each API call to prove who you are | 30 minutes |
| Refresh token | Exchanged for a new access token when the old one expires | 90 days |
As long as your system refreshes within 90 days, it never needs to return to the web portal for new tokens.
Keeping your connection alive
- Each refresh returns a new access token and a new refresh token. Save both, and use the new refresh token for your next refresh. Treat the previous one as used.
- If your system goes more than 90 days without refreshing, the refresh token expires. Generate a new pair in the web portal under Settings > API.
- Store tokens like passwords: in a secrets manager or encrypted configuration, never in source code, email or shared documents.
About OAuth: FuelCloud does not currently offer OAuth delegated access, where an outside app is granted access through a "Sign in with…" flow. Credentials are tied to a web portal user in your own account.
What you can work with
The API covers the same core records you manage in the web portal. Most can be read and filtered; assets such as vehicles and drivers can also be created and updated.
| Area | What the API supports |
|---|---|
| Transactions | Read your transaction history with filters; record pump and fill transactions; read the questions asked at the pump |
| Tanks | Read tank lists and details; update alert levels (low, critical low, high, critical high) and inventory unit; adjust inventory and price |
| Sites | Read site lists and details |
| Vehicles | Read and filter vehicles; create and update vehicles, including allowed products, tank capacity, tax status and custom data fields |
| Drivers | Read and filter drivers; create and update drivers, including PIN, phone, status, schedule and custom data fields |
| Access groups | Create groups and add or remove tanks, drivers and vehicles |
| Reference data | Look up the product list and supported time zones |
The developer documentation linked in Settings > API lists the exact fields, filters and formats for each area.
Common uses
Customers most often use the API to keep FuelCloud in step with the other systems they run.
- Accounting and billing: pull transactions into an ERP, invoicing or fuel tax system on a schedule.
- Fleet and HR sync: create and update vehicles and drivers from your fleet management or HR system, so new hires and new trucks can fuel on day one.
- Inventory and pricing: update tank inventory and pricing from your own records, and pull tank levels into reporting.
- Access control: add or remove drivers and vehicles from access groups as assignments change.
- Reporting: combine FuelCloud transactions and site data with other sources in a BI or data warehouse tool.
Data is pulled, not pushed. Your system calls FuelCloud to check for new or changed data; FuelCloud does not send updates automatically. Webhooks (automatic notifications when something happens) are not available today, though we are evaluating them for the future.
Planning your integration
A few habits make an integration reliable and easy to support.
- Refresh before each call. Refresh your access token before every call. You won't need to track when it was issued and calls won't fail on an expired token.
- Run at least once every 90 days. Each refresh resets the 90 day clock so a scheduled job that runs regularly keeps your refresh token from expiring.
- Use filters when reading. Request only the date range or records you need instead of reading everything again each run.
- Use reference data for IDs. Look up product and time zone values through the API rather than storing fixed values in your code.
- Test changes carefully. Updates to tanks, prices, vehicles and drivers take effect in your live account immediately.
- Use a dedicated user. Create a web portal user for the integration so its credentials are not tied to one employee.
Support
FuelCloud Support can help with API access requests, credentials and questions about your account's data.
- Don't have access yet? Request API Access Here!
- Have access? Use the developer documentation link under Settings > API for endpoints, fields and examples.
- Lost your tokens or the refresh token expired? Generate a new pair in the web portal under Settings > API.
- Need help with an integration? FuelCloud support can answer questions about how the FuelCloud API works, such as access, authentication and the data available. FuelCloud support cannot write, review or troubleshoot an integration you or a partner built. For those questions, work with your own developer or integration partner. When you contact Support, include your company name, the user the integration runs as, and your question.
Comments
Please sign in to leave a comment.