Make your products available for sale with TOMP
This guide is for transport operators who want to make their products available for sale through the Entur Sales Platform. Every operator who wants to sell through our platform must support the TOMP API standard.
TOMP: a European API standard
TOMP stands for Transport Operator to Mobility-as-a-Service Provider.
What is the TOMP standard
TOMP is a European API standard that enables integration and communication between transport operators and Mobility-as-a-Service (MaaS) providers. It supports functions such as booking, payment, and real-time data sharing, and helps create a unified, user-friendly mobility experience across Europe by connecting transport services within a single application.
- Read more about the TOMP working group: TOMP-WG.
- See the TOMP API specification: transport-operator / MaaS-provider API 1.6.1.
Supported versions
Entur supports TOMP 1.6.1, 1.6.0, and 1.5.0. Implement 1.6.1 for
new integrations; 1.5.0 is still accepted as a legacy fallback. Entur chooses the
version per call from what you advertise in your /operator/meta response (see
Get metadata) — it always uses the highest version you
advertise, so an operator on 1.6.1 is never called over 1.5.0.
Why we chose this standard
As a public transport company, we want to use standards and avoid one-to-one integrations between services. TOMP is well established, with more than 40 users across several European countries, and it is based on GBFS. Because almost all data from shared mobility operators is GBFS-based, the standard is easier to implement — you do not need to convert between data models.
Why integrating with TOMP is a smart business move
Integrating with the Shared Mobility API, built on the proven TOMP standard, opens the door to new customers and strengthens your collaboration with public transport providers in key municipalities and cities. Joining a MaaS platform increases your exposure by putting you in a larger marketplace.
By aligning with the standard, your service becomes part of a cohesive mobility offering, which makes it easier for residents and visitors to discover and use it. Municipalities increasingly favour operators who integrate with shared mobility frameworks, as it improves accessibility, reliability, and the user experience for their citizens.
The benefits in short:
- Interoperability — TOMP enables smooth communication between operators and public transport providers, which lowers technical barriers and simplifies integration.
- Access to a growing network — your service joins a unified ecosystem that connects operators, public transport authorities, and end users, increasing visibility and access to new customer groups.
- Streamlined collaboration — the standard supports closer collaboration with public transport companies and alignment with local mobility strategies.
- Regulatory alignment — municipalities and transport authorities often favour operators who adhere to established standards such as TOMP when issuing permits.
- Better user experience — users can plan, book, and pay through unified systems, which reduces friction and increases satisfaction.
- Future-proofing — TOMP is actively maintained and updated for new technologies and use cases.
- Sustainability — integrating positions your service within a sustainable mobility ecosystem, which many municipalities prioritise.
Reference application
Team Delingsmobilitet maintains an open-source reference application — a Kotlin Spring Boot service with the controllers, data classes, services, and test data you need. Its README explains which endpoints you, as a transport operator, need to implement. Because the TOMP standard supports all kinds of mobility but we currently support micro-mobility only, the number of required endpoints and the response data are kept to a minimum.
See shared-mobility-to-ref and its README.
Real-time data
All shared mobility operators in Norway are required by law to deliver real-time data to Entur. Our team and our clients use the Mobility API to receive information about available assets, system information, vehicle types, pricing plans, system regions, and geofencing zones. This makes many TOMP endpoints redundant, which makes the standard easier to implement.
Implementation
The reference application shows how to implement the TOMP API standard. See the README in shared-mobility-to-ref for how to implement each required endpoint.
Data model
- Booking — general information about the booking.
id— unique identifier (UUID) for the booking.state— the state of the booking.departureTime— when the booking was created.arrivalTime— when the booking ended.from— where the trip started (coordinates).to— where the trip ended (coordinates); not required.pricing— the total of all legs. Set it after each leg reachesSTART_FINISHING(ready for a picture of the asset).customer— information about the customer, usually only an id.legs— information about each part of the trip. A booking with one asset usually has one leg.
- Leg (
legs[])id— unique identifier (UUID) for the leg.state— the current state of the leg.departureTime— when the leg was created.actualDepartureTime— when the leg actually started (state = IN_USE).arrivalTime/actualArrivalTime— when the leg ended.from— where the trip started (coordinates).to— where the trip ended (coordinates); not required.pricing— the pricing plan for the leg. Does not include the current price of the trip. Each part has atypeofFIXED,FLEX, orMAX.assetType.id— reference to an asset type. Required by TOMP; we use a static fallback because we do not use it. Note this sits on the leg, not insideasset.asset— information about the asset (vehicle).
- Asset (
legs[].asset)id— unique identifier (UUID) for the asset. Should match the GBFS dynamic id.stateOfCharge— the current battery level of the asset.maxRange— the current range of the asset in metres.overriddenProperties.meta— a free-form map of extra properties. Entur readsoverriddenProperties.meta.vehicleCodefrom it for your internal vehicle code.
The endpoints you need to implement to support the TOMP standard are described below, with examples.
Get metadata
This endpoint returns metadata about the running implementation, including which
endpoints are implemented and which versions of the TOMP standard are supported.
The response is an array, so you can advertise more than one version block, each
with its own baseUrl. Entur polls it regularly and routes each call to the
highest version you advertise.
GET /operator/meta
Example response
Code
Get a vehicle from a QR code
This endpoint returns the vehicleId / assetId for a QR code. The QR code is a
unique identifier for the vehicle.
POST /planning/offers
Example request
Code
Example response
Code
Create a booking
This endpoint creates a booking for a trip. The booking is created with a list of
legs that includes information about the assets. Pricing on the booking is not
required until every leg reaches START_FINISHING. The pricing on each leg
represents the pricing plan, and the pricing on the booking represents the total
price for the trip.
POST /bookings/one-stop
Example request
Code
Example response
Code
Change the state of a leg
This endpoint changes the state of a leg. Entur sends the events PREPARE,
SET_IN_USE, PAUSE, START_FINISHING, FINISH, and CANCEL. A resume after a
pause is sent as SET_IN_USE, not a separate event. If the vehicle cannot be
paused, you do not need to support PAUSE — set the leg state to IN_USE when you
create the booking. When a leg reaches START_FINISHING, set the
actualArrivalTime.
POST /legs/{id}/events
Example request — START_FINISHING
Code
Example response — START_FINISHING
Code
Example request — FINISH
Code
Example response — FINISH
Code
Get a leg, a booking, or all bookings
GET /legs/{id}
Example response
Code
GET /bookings/{id}
Example response
Code
GET /bookings
Returns an array of the same booking objects.
Create a support case
Entur calls this endpoint on your side to open a support case related to a booking or asset — typically when an end user has a problem during a trip, such as a vehicle that will not open or close, a vehicle that is unavailable, or an accident. (The client-facing side of this flow is covered in the Sell products in your client.)
POST /support
Request body (SupportRequest):
supportType(required) — the type of support issue. One ofBROKEN_DOWN,NOT_AT_LOCATION,MISSING_AFTER_PAUSE,NOT_CLEAN,NOT_AVAILABLE,UNABLE_TO_OPEN,UNABLE_TO_CLOSE,API_TECHNICAL,API_FUNCTIONAL,ACCIDENT, orOTHER.contactInformationEndUser(required) — contact details for the end user.distributionChannel(required) — the distribution channel the case came from.transportOperatorBookingId(optional) — your booking identifier.assetId(optional) — the asset involved.comment(optional) — free-text description of the issue.place(optional) — where the issue occurred.orderId(optional) — the Entur order identifier.vehicleCode(optional) — your internal vehicle reference.
Example request
Code
Example response
Code
Responses:
200 OK— support case created.400 application/problem+json— invalid request or missing required information.
Get support status for a booking
Entur calls this endpoint to retrieve the status of the support cases for a booking.
GET /support/{id}/status
Path parameters:
id(required) — the booking identifier.
Example request
Code
Example response
Code
Response body (SupportStatus):
status— the current status of the support case.timeToResolution— the estimated time to resolution, in minutes.