# 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](https://github.com/TOMP-WG).
- See the TOMP API specification:
  [transport-operator / MaaS-provider API 1.6.1](https://app.swaggerhub.com/apis-docs/TOMP-API-WG/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](#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](https://gbfs.org/). 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](https://github.com/entur/shared-mobility-to-ref) and
its [README](https://github.com/entur/shared-mobility-to-ref/blob/main/README.md).

## 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](/docs/open-services/mobility) 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](https://github.com/entur/shared-mobility-to-ref/blob/main/README.md)
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`

<details>
<summary>Example response</summary>

```json
[
  {
    "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
  }
]
```

</details>

### 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`

<details>
<summary>Example request</summary>

```json
{
  "from": {
    "coordinates": {
      "lng": 0.00,
      "lat": 0.00
    },
    "extraInfo": {
      "vehicleCode": "ABCD1234"
    }
  }
}
```

</details>

<details>
<summary>Example response</summary>

```json
{
  "validUntil": "2024-08-07T05:53:04.758",
  "options": [
    {
      "legs": [
        {
          "asset": {
            "id": "TST:Vehicle:ea110245-131d-3109-ba91-b5bd57701934",
            "stateOfCharge": 100,
            "overriddenProperties": {
              "meta": {
                "vehicleCode": "ABCD1234"
              }
            }
          }
        }
      ]
    }
  ]
}
```

</details>

### 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`

<details>
<summary>Example request</summary>

```json
{
  "from": {
    "coordinates": {
      "lng": 0.00,
      "lat": 0.00
    }
  },
  "useAssets": [
    "TST:Vehicle:ea110245-131d-3109-ba91-b5bd57701934"
  ],
  "customer": {
    "id": "1234"
  }
}
```

</details>

<details>
<summary>Example response</summary>

```json
{
  "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"
  }
}
```

</details>

### 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`

<details>
<summary>Example request — START_FINISHING</summary>

```json
{
  "event": "START_FINISHING",
  "time": "2025-01-17T14:02:11.066Z",
  "asset": "TST:Vehicle:ea110245-131d-3109-ba91-b5bd57701934"
}
```

</details>

<details>
<summary>Example response — START_FINISHING</summary>

```json
{
  "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" }
    ]
  }
}
```

</details>

<details>
<summary>Example request — FINISH</summary>

```json
{
  "event": "FINISH",
  "time": "2025-01-17T14:02:11.066Z",
  "url": "URL_TO_PARKING_IMAGE",
  "asset": "TST:Vehicle:ea110245-131d-3109-ba91-b5bd57701934"
}
```

</details>

<details>
<summary>Example response — FINISH</summary>

```json
{
  "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" }
    ]
  }
}
```

</details>

### Get a leg, a booking, or all bookings

**GET** `/legs/{id}`

<details>
<summary>Example response</summary>

```json
{
  "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" }
    ]
  }
}
```

</details>

**GET** `/bookings/{id}`

<details>
<summary>Example response</summary>

```json
{
  "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"
  }
}
```

</details>

**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](/guides/shared-mobility/client-guide#create-a-support-case).)

**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.

<details>
<summary>Example request</summary>

```json
{
  "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"
}
```

</details>

<details>
<summary>Example response</summary>

```json
{
  "status": "RECEIVED",
  "timeToResolution": 30
}
```

</details>

**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.

<details>
<summary>Example request</summary>

```text
GET /support/89ea38c3-af79-4892-bd21-8bb077b4609a/status
```

</details>

<details>
<summary>Example response</summary>

```json
[
  { "status": "RECEIVED", "timeToResolution": 30 },
  { "status": "IN_PROGRESS", "timeToResolution": 15 }
]
```

</details>

**Response body (`SupportStatus`):**

- `status` — the current status of the support case.
- `timeToResolution` — the estimated time to resolution, in minutes.
