How the IR.21 API Works

This API is used to manage IR.21 roaming data that enables mobile network operators to identify and route traffic between networks during roaming scenarios.

Intended audience

This API is designed for mobile network operators and roaming hub providers who need to manage IR.21 reference data for roaming operations.

What is IR.21 data?

IR.21 data is standardized roaming reference information defined by the GSMA that contains network identifiers and routing information used when subscribers roam between mobile networks.

Data organisation

Datasets

IR.21 data is organized into datasets. A dataset is a collection of organisations that represents a specific version or snapshot of IR.21 data.

Key characteristics of datasets:

  • Each dataset contains multiple organisations
  • You can have multiple datasets (e.g., for testing, staging, production)
  • Only one dataset can be active per tenant at a time
  • Datasets can be copied, created, and deleted independently

Organisations

Within each dataset, organisations represent individual mobile network operators. Each organisation contains:

  • Basic information: Name, country, and 3-alpha country initials
  • TADIGs: One or more 5-character operator codes
  • Network identifiers: MCCMNCs associated with each TADIG
  • Routing information: Global title (GT) prefixes and realms for each TADIG

Relationships

The data follows this hierarchy:

Dataset
├── Organisation 1
│   ├── TADIG A
│   │   ├── MCCMNC 1, MCCMNC 2
│   │   ├── GT Prefix 1, GT Prefix 2
│   │   └── Realm 1, Realm 2
│   └── TADIG B
│       ├── MCCMNC 3
│       └── GT Prefix 3
└── Organisation 2
    └── TADIG C
        └── ...

Usage patterns

Managing datasets

  1. Create a new dataset for your IR.21 data
  2. Populate the dataset with organisations and their network information
  3. Set the dataset as active for a tenant to use it for roaming operations
  4. Copy datasets when you need to make changes while keeping a backup
  5. Delete datasets that are no longer needed

Managing organisations

Organisations can be created or updated individually within a dataset. Each organisation must specify:

  • A unique name and country
  • At least one TADIG code
  • Network identifiers (MCCMNCs) for routing
  • Optional GT prefixes and realms for specific routing scenarios

Data sources

The API supports importing data from:

  • Manual entry: Create organisations using the API directly using CreateOrUpdateOrganisation
  • GSMA RAEX IR.21 XML: Import from the official GSMA format using CreateOrUpdateOrganisationFromXml

Active dataset concept

Each tenant can have one active dataset at a time. The active dataset determines which IR.21 data the Cisco Mobility Services core uses for:

  • Roaming partner identification
  • Network routing decisions
  • Billing and settlement processes (CDRs)

When you switch active datasets, the change takes effect immediately for all roaming operations in the Cisco Mobility Services core.

Lookup by GT

In a RAEX IR.21 document, network nodes' global title number ranges in the Routing section consist of CC, NDC, SN Range Start, and SN Range Stop. In some cases, only CC and NDC are specified, in which case the concatenation of them is used as the GT prefix. In some other cases, SN Range Start and SN Range Stop are misinterpreted by IR.21 organisations as prefixes. Finally, there is a sizeable number of networks where the advertised SN range is longer or shorter than the actual GTs.

When resolving a TADIG from a GT, Cisco mobile network core takes all of the above into account in the following way:

  • GT prefixes (if any) are converted into GT ranges (start is padded with 0s and stop is padded with 9s up to GT length) and appended to the list of GT ranges;
  • An attempt is made to match the GT against the GT ranges from the above;
  • If the GT does not match any range, those GT ranges with the first three digits matching the GT are adjusted by either extending or truncating the range up to the length of the GT, and the match is attempted again.

In case multiple TADIGs match the same GT, the TADIG with the shortest (most specific) matching range is selected.