Copy page

OMSA

Search offers

This guide gets you from zero to your first OMSA offer.

You will:

• Model who is travelling.
• Send your first search-offers process request.
• Understand the basics of an OMSA OfferCollection response.

Before you begin

To use this guide, you need to:

• Be an authorised Entur partner.
• Have OAuth2 client credentials (client_id and client_secret).
• Have header values for Entur-Distribution-Channel and Entur-POS.
• Use the OMSA dev base URL https://api.dev.entur.io/omsa/v1.

1. Specify who is travelling

When searching for offers, OMSA supports two traveller models:

• individual_traveller: an identifiable traveller (with specific attributes such as age, name, and possibly other personal details).
• user_profile: an anonymous traveller profile with a count.

You can use one of them, or both in the same request.

Both models require an id that you supply. It can be any string up to 200 characters, so you can reuse IDs from your own system.

OMSA keeps these IDs throughout the purchase. You refer to them as travellerId when you update or remove a traveller in a draft package.

Code
{
  "travellers": [
    {
      "type": "individual_traveller",
      "id": "9f7f69ec-d68c-4751-8ec4-fd059f820cb8",
      "age": 30
    }
  ],
  "profiles": [
    {
      "type": "user_profile",
      "id": "1c9b2b5a-f291-404b-8235-50641ef2b733",
      "ageGroup": "ADULT",
      "count": 1
    }
  ]
}

2. Search for your first offer

Use the search-offers process to send your first request.

Using place references

OMSA supports several place models in specification, most commonly:

• Fare zones (ORG:FareZone:*)
• Stop places (NSR:StopPlace:*)
• GPS coordinates (GPS:lat,long[,alt])

Searching with zones or stop places is a common way to search for simple single-product offers, typically to let the user purchase a single ticket in a specific zone or set of zones.

Code
{
  "inputs": {
    "type": "search_offer",
    "specification": {
      "from": {
        "placeId": "ORG:FareZone:1"
      },
      "to": {
        "placeId": "ORG:FareZone:3"
      },
      "startTime": "2026-07-17T14:46:00.000Z"
    },
    "travellers": [
      {
        "id": "9f7f69ec-d68c-4751-8ec4-fd059f820cb8",
        "type": "individual_traveller",
        "fullName": "Ola Nordmann",
        "age": 30
      }
    ]
  }
}

Using trip patterns from Journey Planner

You can also use a TripPattern from the Entur Journey Planner to search for offers, which is often the preferred way to search for offers.

Code
{
  "inputs": {
    "type": "search_offer",
    "travellers": [
      {
        "id": "9f7f69ec-d68c-4751-8ec4-fd059f820cb8",
        "type": "individual_traveller",
        "age": 30
      }
    ],
    "pattern": [
      {
        "serviceJourney": "KOL:ServiceJourney:3010_250903083240427_1014",
        "date": "2026-07-17",
        "from": {
          "placeId": "NSR:StopPlace:61355",
          "name": "Haugesund bussterminal"
        },
        "to": {
          "placeId": "NSR:StopPlace:28230",
          "name": "Austre Karmøyveg"
        }
      }
    ]
  }
}

3. Understand the response

Confirm that:

• The request returns HTTP 200.
• The response contains at least one offer.
• Returned offers match expected place IDs and traveller inputs.

Example response

Code
{
  "type": "OfferCollection",
  "offers": [
    {
      "id": "a3509357-b5c2-4c7d-910a-11e638d48f4b",
      "type": "offer",
      "properties": {
        "legs": [
          {
            "id": "a3509357-b5c2-4c7d-910a-11e638d48f4b",
            "type": "leg",
            "sequenceNumber": 1,
            "traveller": "9f7f69ec-d68c-4751-8ec4-fd059f820cb8",
            "state": "NOT_STARTED",
            "price": {
              "amount": 354.0,
              "currencyCode": "NOK"
            },
            "products": [
              "ORG:PreassignedFareProduct:4e913d65"
            ]
          }
        ],
        "products": [
          {
            "type": "product",
            "productId": {
              "productId": "ORG:PreassignedFareProduct:4e913d65",
              "name": "Operator X 7-day ticket"
            },
            "productName": "Operator X 7-day ticket"
          }
        ],
        "price": {
          "amount": 354.0,
          "currencyCode": "NOK"
        }
      }
    }
  ]
}

OMSA returns offers with Leg objects, even for simple Zone-Zone or StopPlace-StopPlace searches. In these cases, the leg represents a single traveller on a single product. To see which traveller belongs to which product, check the legs.

Troubleshooting tips

• If you receive an empty offers array, check that your specification parameters (place IDs, time range) align with available data in the dev environment.
• Use the OMSA API spec and error messages to debug issues. Common errors include invalid place IDs, duplicate traveller IDs, or missing required fields and headers.
• For authentication issues, ensure your OAuth2 token is valid and has the necessary scopes for OMSA access and the distribution channel and POS you are using.
• If you encounter unexpected errors or need further assistance, contact Entur support with details of your request and response for help. Include the X-Correlation-ID from your response headers to help us trace the problematic requests.

Next steps

• Make your first purchase from one of the offers in the response.
• Apply discounts for eligible travellers with entitlements, e.g. students, employees etc. (link coming soon).
• More search-offers requests, e.g. with a TripPattern from the Entur Journey Planner or a group of travellers (link coming soon).