Entur Developer
Shared mobility

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.

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:

  1. Interoperability — TOMP enables smooth communication between operators and public transport providers, which lowers technical barriers and simplifies integration.
  2. 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.
  3. Streamlined collaboration — the standard supports closer collaboration with public transport companies and alignment with local mobility strategies.
  4. Regulatory alignment — municipalities and transport authorities often favour operators who adhere to established standards such as TOMP when issuing permits.
  5. Better user experience — users can plan, book, and pay through unified systems, which reduces friction and increases satisfaction.
  6. Future-proofing — TOMP is actively maintained and updated for new technologies and use cases.
  7. 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 reaches START_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 a type of FIXED, FLEX, or MAX.
    • 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 inside asset.
    • 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 reads overriddenProperties.meta.vehicleCode from 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
JSONCode
[ { "baseUrl": "BASE_URL", "endpoints": [ { "path": "/operator/meta", "method": "GET", "status": "IMPLEMENTED" }, { "path": "/bookings/one-stop", "method": "POST", "status": "IMPLEMENTED" }, { "path": "/planning/offers", "method": "POST", "status": "IMPLEMENTED" }, { "path": "/legs/{id}/events", "method": "POST", "eventType": "PREPARE", "status": "IMPLEMENTED" }, { "path": "/legs/{id}/events", "method": "POST", "eventType": "SET_IN_USE", "status": "IMPLEMENTED" }, { "path": "/legs/{id}/events", "method": "POST", "eventType": "PAUSE", "status": "IMPLEMENTED" }, { "path": "/legs/{id}/events", "method": "POST", "eventType": "START_FINISHING", "status": "IMPLEMENTED" }, { "path": "/legs/{id}/events", "method": "POST", "eventType": "FINISH", "status": "IMPLEMENTED" }, { "path": "/legs/{id}/events", "method": "POST", "eventType": "CANCEL", "status": "IMPLEMENTED" }, { "path": "/bookings/{id}", "method": "GET", "status": "IMPLEMENTED" }, { "path": "/legs/{id}", "method": "GET", "status": "IMPLEMENTED" }, { "path": "/support", "method": "POST", "status": "IMPLEMENTED" }, { "path": "/support/{id}/status", "method": "GET", "status": "IMPLEMENTED" } ], "processIdentifiers": { "planning": [], "general": [], "operatorInformation": [], "booking": [], "tripExecution": [], "payment": [], "support": [] }, "scenarios": ["PAY_WHEN_FINISHED"], "version": "1.6.1", "steps": null } ]

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
JSONCode
{ "from": { "coordinates": { "lng": 0.00, "lat": 0.00 }, "extraInfo": { "vehicleCode": "ABCD1234" } } }
Example response
JSONCode
{ "validUntil": "2024-08-07T05:53:04.758", "options": [ { "legs": [ { "asset": { "id": "TST:Vehicle:ea110245-131d-3109-ba91-b5bd57701934", "stateOfCharge": 100, "overriddenProperties": { "meta": { "vehicleCode": "ABCD1234" } } } } ] } ] }

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
JSONCode
{ "from": { "coordinates": { "lng": 0.00, "lat": 0.00 } }, "useAssets": [ "TST:Vehicle:ea110245-131d-3109-ba91-b5bd57701934" ], "customer": { "id": "1234" } }
Example response
JSONCode
{ "departureTime": "2025-01-17T14:02:11.066Z", "legs": [ { "from": { "coordinates": { "lng": 0.00, "lat": 0.00 } }, "id": "18aaa569-5be8-46ea-ba0c-c02e1ba0a54e", "state": "IN_USE", "asset": { "overriddenProperties": { "meta": { "vehicleCode": "ABCD1234" } }, "stateOfCharge": 100, "maxRange": 28400, "id": "TST:Vehicle:ea110245-131d-3109-ba91-b5bd57701934", "isDisabled": false }, "pricing": { "estimated": false, "parts": [ { "amount": 10.0, "type": "FIXED", "currencyCode": "NOK" }, { "unitType": "MINUTE", "amount": 2.5, "units": 1, "type": "FLEX", "currencyCode": "NOK" }, { "amount": 0.9, "name": "Insurance fee", "type": "FIXED", "currencyCode": "NOK" } ] } } ], "from": { "coordinates": { "lng": 0.00, "lat": 0.00 } }, "id": "TST:Booking:ea110245-131d-3109-ba91-b5bd57701934", "state": "CONFIRMED", "customer": { "id": "1234" } }

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
JSONCode
{ "event": "START_FINISHING", "time": "2025-01-17T14:02:11.066Z", "asset": "TST:Vehicle:ea110245-131d-3109-ba91-b5bd57701934" }
Example response — START_FINISHING
JSONCode
{ "from": { "coordinates": { "lng": 0.00, "lat": 0.00 } }, "id": "18aaa569-5be8-46ea-ba0c-c02e1ba0a54e", "state": "FINISHING", "asset": { "overriddenProperties": { "meta": { "vehicleCode": "ABCD1234" } }, "stateOfCharge": 100, "maxRange": 28400, "id": "TST:Vehicle:ea110245-131d-3109-ba91-b5bd57701934", "isDisabled": false }, "pricing": { "estimated": false, "parts": [ { "amount": 10.0, "type": "FIXED", "currencyCode": "NOK" }, { "unitType": "MINUTE", "amount": 2.5, "units": 1, "type": "FLEX", "currencyCode": "NOK" }, { "amount": 0.9, "name": "Insurance fee", "type": "FIXED", "currencyCode": "NOK" } ] } }
Example request — FINISH
JSONCode
{ "event": "FINISH", "time": "2025-01-17T14:02:11.066Z", "url": "URL_TO_PARKING_IMAGE", "asset": "TST:Vehicle:ea110245-131d-3109-ba91-b5bd57701934" }
Example response — FINISH
JSONCode
{ "from": { "coordinates": { "lng": 0.00, "lat": 0.00 } }, "id": "18aaa569-5be8-46ea-ba0c-c02e1ba0a54e", "state": "FINISHED", "asset": { "overriddenProperties": { "meta": { "vehicleCode": "ABCD1234" } }, "stateOfCharge": 100, "maxRange": 28400, "id": "TST:Vehicle:ea110245-131d-3109-ba91-b5bd57701934", "isDisabled": false }, "pricing": { "estimated": false, "parts": [ { "amount": 10.0, "type": "FIXED", "currencyCode": "NOK" }, { "unitType": "MINUTE", "amount": 2.5, "units": 1, "type": "FLEX", "currencyCode": "NOK" }, { "amount": 0.9, "name": "Insurance fee", "type": "FIXED", "currencyCode": "NOK" } ] } }

Get a leg, a booking, or all bookings

GET /legs/{id}

Example response
JSONCode
{ "departureTime": "2025-01-17T14:02:11.066Z", "actualDepartureTime": "2025-01-17T14:02:11.082Z", "arrivalTime": "2025-01-17T14:04:20.926Z", "actualArrivalTime": "2025-01-17T14:04:20.926Z", "from": { "coordinates": { "lng": 10.745386, "lat": 59.908882 } }, "id": "18aaa569-5be8-46ea-ba0c-c02e1ba0a54e", "state": "FINISHED", "asset": { "overriddenProperties": { "meta": { "vehicleCode": "183112" } }, "stateOfCharge": 64, "maxRange": 28400, "id": "TST:Vehicle:ea183112-79db-3976-995b-1d46423c93ce", "isDisabled": false }, "pricing": { "estimated": false, "parts": [ { "amount": 10.0, "type": "FIXED", "currencyCode": "NOK" }, { "unitType": "MINUTE", "amount": 2.5, "units": 1, "type": "FLEX", "currencyCode": "NOK" }, { "amount": 0.9, "name": "Insurance fee", "type": "FIXED", "currencyCode": "NOK" } ] } }

GET /bookings/{id}

Example response
JSONCode
{ "departureTime": "2025-01-17T02:43:54.734Z", "arrivalTime": "2025-01-17T02:46:17.412Z", "legs": [ { "departureTime": "2025-01-17T02:43:54.734Z", "actualDepartureTime": "2025-01-17T02:45:32.162Z", "arrivalTime": "2025-01-17T02:46:17.412Z", "actualArrivalTime": "2025-01-17T02:46:17.412Z", "from": { "coordinates": { "lng": 119.98905, "lat": 31.813826 } }, "id": "18aaa569-5be8-46ea-ba0c-c02e1ba0a54e", "state": "FINISHED", "asset": { "overriddenProperties": { "meta": { "vehicleCode": "ABCD1234" } }, "stateOfCharge": 0, "maxRange": 0, "id": "TST:Vehicle:ea999992-8d9c-3570-be06-fb3cb1b958fa", "isDisabled": false }, "pricing": { "estimated": false, "parts": [ { "amount": 0.0, "type": "FIXED", "currencyCode": "NOK" }, { "unitType": "MINUTE", "amount": 1.0, "units": 1, "type": "FLEX", "currencyCode": "NOK" }, { "amount": 1.0, "name": "Insurance fee", "type": "FIXED", "currencyCode": "NOK" } ] } } ], "from": { "coordinates": { "lng": 10.793742, "lat": 59.917294 } }, "id": "18aaa569-5be8-46ea-ba0c-c02e1ba0a54e", "state": "FINISHED", "pricing": { "estimated": false, "parts": [ { "bankAccount": null, "amount": 2.0, "vatCountryCode": "NO", "vatRate": 26, "amountExVat": 1.59, "details": { "estimated": false, "parts": [ { "amount": 0.0, "type": "FIXED", "currencyCode": "NOK" }, { "unitType": "MINUTE", "amount": 1.0, "units": 1, "type": "FLEX", "currencyCode": "NOK" }, { "amount": 1.0, "name": "Insurance fee", "type": "FIXED", "currencyCode": "NOK" } ] }, "state": "TO_INVOICE", "category": "FARE", "currencyCode": "NOK" } ] }, "customer": { "id": "1234" } }

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 of BROKEN_DOWN, NOT_AT_LOCATION, MISSING_AFTER_PAUSE, NOT_CLEAN, NOT_AVAILABLE, UNABLE_TO_OPEN, UNABLE_TO_CLOSE, API_TECHNICAL, API_FUNCTIONAL, ACCIDENT, or OTHER.
  • 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
JSONCode
{ "supportType": "UNABLE_TO_OPEN", "contactInformationEndUser": { "email": "user@example.com", "phone": "+4799999999" }, "distributionChannel": "ENT:DistributionChannel:SharedMobility", "transportOperatorBookingId": "operator-booking-123", "assetId": "veh-001", "comment": "Unable to unlock the vehicle. App returns an error.", "place": { "name": "Oslo Central Station", "coordinates": { "longitude": 10.7532, "latitude": 59.9115 } }, "orderId": "ORD123456", "vehicleCode": "ABCD1234" }
Example response
JSONCode
{ "status": "RECEIVED", "timeToResolution": 30 }

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
GET /support/89ea38c3-af79-4892-bd21-8bb077b4609a/status
Example response
JSONCode
[ { "status": "RECEIVED", "timeToResolution": 30 }, { "status": "IN_PROGRESS", "timeToResolution": 15 } ]

Response body (SupportStatus):

  • status — the current status of the support case.
  • timeToResolution — the estimated time to resolution, in minutes.
Last modified on
Did you find what you were looking for?