Core Concepts

Understanding these core concepts will help you build robust integrations with the Mobility API.

Multi-Provider Aggregation

The Mobility API aggregates offers from multiple mobility providers in real-time. When you search for mobility offers, the platform queries all configured providers simultaneously and waits for them to respond, consolidating the results into a single, uniformly structured response. A hard timeout of 20 seconds ensures the request completes even if individual providers are slow. This means you make one API call and receive offers from all providers — no need to integrate with each provider separately.

Because provider response times vary, search requests can take anywhere from 1 to 20 seconds. Plan your UI accordingly with loading indicators so users understand results are being gathered.

Organizations & Tenants

The platform uses a two-level hierarchy to manage access and data isolation. An Organization is your top-level account, typically representing your company. It contains members, settings, and provider configurations. Within each organization, you can create multiple Tenants — sub-units that represent customers, projects, or cost centers.

API keys are always scoped to a specific tenant. When you authenticate with an API key, the platform resolves both the tenant and the parent organization, then applies all relevant policies automatically. You never need to specify a tenant or organization ID in your requests.

This hierarchy provides granular access control: each tenant has its own API keys with independent rate limits, and booking data is fully isolated between tenants — even within the same organization. Costs are tracked per tenant, enabling customer- or project-level billing. Organizations can manage all their tenants from the Dashboard Portal.

Offer Lifecycle

Offers move through distinct stages in the booking process. Understanding these stages is essential for building a smooth user experience.

The flow begins with a Search that returns offers along with encrypted tokens. Each offer has a validity window of 15-30 minutes. Optionally, you can fetch Details for a specific offer to retrieve full specifications and terms — this also refreshes the token. Next, Prebook locks the price and creates a temporary reservation valid for 10-15 minutes, returning a booking token. Finally, Booking consumes the token and confirms the reservation.

Each stage returns an updated token that you must pass to the next stage. Always use the latest token from the most recent API response.

Token-Based Security

Offers include encrypted offerToken strings that are required for progressing through the booking flow. These tokens update with each API call, so you should always use the latest one. Tokens have an expiration time indicated by the usableUntil timestamp. They are encrypted and signed, making them safe to expose to end users in your frontend.

In practice, simply pass the token from one API response into the next request. The API handles validation internally and auto-corrects where possible if you use a slightly outdated token. When a token expires, you will receive an OFFER_EXPIRED error — at that point, start a new search rather than retrying with the same token.

Response Envelope Structure

Every API response uses a consistent envelope format for predictable parsing and error handling.

Success Response

{
  "success": true,
  "data": {
    // Endpoint-specific payload (offers, booking details, etc.)
  },
  "meta": {
    "requestId": "req_abc123-1731499800000",
    "timestamp": "2026-11-13T10:30:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "OFFER_EXPIRED",
    "message": "This offer has expired. Please search again.",
    "details": {
      // Optional additional error context
    }
  },
  "meta": {
    "requestId": "req_abc123-1731499800000",
    "timestamp": "2026-11-13T10:30:00Z"
  }
}

Response Fields

Always include requestId when contacting support — this helps us quickly identify and debug issues.

Data Formats

The API uses standardized formats for common data types to ensure consistency across all endpoints.

Prices

All monetary amounts use the smallest currency unit (cents for EUR/USD, pence for GBP):

{
  "amount": 14280,
  "currency": "EUR"
}

To display the amount, divide by 100 for EUR/USD/GBP currencies. For example, 14280 = 142.80 EUR, 9950 = 99.50 EUR, 125000 = 1,250.00 EUR.

Dates and Times

All timestamps use ISO 8601 format in UTC: YYYY-MM-DDTHH:mm:ssZ. Always send UTC times — the API handles timezone conversions automatically based on location context.

{
  "pickup": { "dateTime": "2026-12-01T10:00:00Z" },
  "dropoff": { "dateTime": "2026-12-05T18:30:00Z" }
}

Geographic Coordinates

Locations use decimal degrees (WGS84 standard) with latitude ranging from -90 to +90 and longitude from -180 to +180:

{
  "type": "coordinates",
  "latitude": 52.520008,
  "longitude": 13.404954
}

Language Codes

For localized content, use ISO 639-1 language codes: "en" for English or "de" for German. Supported languages vary by provider.

Resource Identifiers

All resource IDs use prefixes to indicate their type:

Include requestId in all support requests for faster issue resolution.

Operation Characteristics

Different API operations have different timing and retry characteristics that you should account for in your integration.

Set timeouts appropriate to each operation: 25 seconds for searches (due to multi-provider aggregation), 30 seconds for booking creation (provider confirmation can be slow), and 10-15 seconds for other operations like details and prebook. Offer tokens act as natural idempotency keys for booking creation — each token can only produce one successful booking, so retrying with the same token after a network error is safe. Some bookings may return a PENDING status when the provider confirms asynchronously; in those cases, poll the booking endpoint for the final status. When retrying after errors, use the same token for network and server errors, but obtain a fresh token if the offer has expired or become unavailable.