API Testing

Environments

Fuel Finder APIs run in live and sandbox environments. Live provides access to real data and production services. Sandbox mirrors live API versions and lets developers test integrations safely.

Live

The live environment runs all production APIs listed in the developer documentation.

• Public data for information recipients (readonly)
• Price submission for motor fuel traders (write operations)

Sandbox

The sandbox environment runs all APIs, including a test data generator. The sandbox is for testing OAuth 2.0 (client credentials) and price submission flows without affecting real data.

When you submit a price update, the sandbox returns status updates to the transaction record.

Sandbox environment URLs

Substitute live URLs with sandbox URLs when testing:

• API base URL: https://api-sandbox.fuelfinder.service.gov.uk
• Identity (OAuth) URL: https://identity-sandbox.fuelfinder.service.gov.uk

Use sandbox client credentials (client ID and secret) when calling the sandbox identity service.

Testing public data APIs (information recipients)

Public data APIs are readonly and allow information recipients to access trusted open data (current prices by fuel type, forecourt details, amenities, timestamped updates). These endpoints support GET requests with Bearer tokens obtained via OAuth 2.0 client credentials.

Because they are readonly, you can test public data APIs against live or sandbox.

Testing price submission APIs (motor fuel traders)

Price submission APIs allow creation and update of data (for example submitting new prices). These endpoints use the HTTP POST method and require a Bearer access token from OAuth 2.0 (client credentials).

Testing write operations must be done in the sandbox only.

How developers can test price submission APIs in the sandbox

• Register your Motor Fuel Trader (MFT) organisation and the associated Petrol Fuelling Stations (PFS) using the Fuel Finder Portal (FF service staging URL).
• Use the forecourt IDs of the registered PFSs to create your price submission transactions.
• Obtain an access token from the sandbox identity service using your client ID and client secret (OAuth 2.0 client credentials).
• Submit a price update for one or more PFSs using the access token and the forecourt ID(s).
• Poll the transaction for mock status updates and handle accepted or rejected outcomes.