---
id: sub-events
title: Additional Matches and Submatches Data Model
description: Description of additional matches and submatches such as halves, corners, cards, fouls, and other event lines.
version: v1
language: en
---

# Additional Matches and Submatches Data Model

## What Is an Additional Match?

An additional match, or submatch, is a separate line within the main sporting event. A
submatch has its own `game_id` and its own set of betting markets and odds.

Examples of submatches:

- first or second half;
- corners;
- first-half or second-half corners;
- yellow cards;
- fouls and offsides;
- shots and shots on target;
- player statistics;
- other additional match markets.

In this documentation, “additional match” and “submatch” refer to the same entity from
the `sub_games` array.

## Main Match and Submatch

The main match and its submatches are connected through `game_id` and `game_mid`.

| Field | Purpose |
|---|---|
| `game_id` | ID of the current object: the main match or selected submatch |
| `game_mid` | ID of the main match |
| `game_dop_name` | Submatch type name in its detailed response |

For a main match, `game_id` and `game_mid` usually match, while `game_dop_name` remains
empty:

```json
{
  "game_id": 746146992,
  "game_mid": 746146992,
  "game_dop_name": ""
}
```

A submatch has its own `game_id`, while `game_mid` points to the main match:

```json
{
  "game_id": 746147010,
  "game_mid": 746146992,
  "game_dop_name": "Corners"
}
```

In this example:

- `746147010` is the ID of the “Corners” submatch;
- `746146992` is the ID of the main match;
- request corner odds using the submatch's `game_id`, `746147010`.

Do not replace a submatch's `game_id` with `game_mid`; these fields serve different
purposes.

## Where to Retrieve the Submatch List

Retrieve the additional-match list only from `sub_games` in the detailed
[`event`](../api-reference/event.md) response for the main match.

```text
events
  ↓ main match game_id
main match event
  ↓ sub_games[].game_id
selected submatch event
  ↓ game_oc_list
complete list of its betting selections and odds
```

In the [`events`](../api-reference/events.md) match list, `sub_games` is not used and is
returned empty:

```json
{
  "sub_games": []
}
```

`topmatches?full=true` and `toplist?full=true` do not provide the submatch list either.

## `sub_games` Structure

`sub_games` is an array of links to available additional matches:

```json
{
  "sub_games": [
    {
      "game_id": 746147013,
      "game_num": 150080,
      "game_name": "2nd half"
    },
    {
      "game_id": 746147010,
      "game_num": 205978,
      "game_name": "Corners"
    },
    {
      "game_id": 746147314,
      "game_num": 178621,
      "game_name": "Yellow Cards"
    }
  ]
}
```

| Field | Type | Description |
|---|---|---|
| `game_id` | number or `null` | Submatch ID for a separate `event` request |
| `game_num` | number or `null` | Legacy service field; it is not used in client integrations and is planned for removal |
| `game_name` | string or `null` | Additional-match name in the requested language |

`game_name` is intended for display. Do not use the name text as a technical identifier,
because it depends on the selected language.

Use only `game_id` in the request. Do not generate a submatch ID yourself or use
`game_num` in its place.

## What `sub_games` Contains

A `sub_games` item contains only a submatch link and name. It does not contain:

- odds;
- betting markets;
- the full match object;
- separate statistics;
- a list of child submatches.

To retrieve betting selections and odds, make a separate `event` request using the
selected additional match's `game_id`.

## Requesting an Additional Match

The main Live match returned a link to the “Corners” submatch:

```json
{
  "game_id": 746147010,
  "game_num": 205978,
  "game_name": "Corners"
}
```

Request the submatch with the same `event` method:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/event/746147010/group/live/en' \
  --header 'Package: YOUR_API_KEY'
```

Shortened response fragment:

```json
{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "game_id": 746147010,
    "game_mid": 746146992,
    "game_dop_name": "Corners",
    "game_desk": "Half",
    "game_oc_counter": 175,
    "sub_games": []
  }
}
```

The submatch's full betting list is in `body.game_oc_list`. It uses the same `group`
structure as the main match's betting list.

Saved full response:
[“Corners” submatch, Live, Russian](../examples/json-responses/event.subgame-746147010.corners.group.live.ru.json).

## Live and Prematch

Additional matches may be returned in both Live and Prematch. Request a submatch using
the same sports line type from which its `game_id` was retrieved:

```text
sub_games from Live     → event/{gameId}/group/live/{lang}
sub_games from Prematch → event/{gameId}/group/line/{lang}
```

Prematch and Live versions of matches have different IDs. Do not carry a main match or
submatch `game_id` from `line` into `live`.

The contents of `sub_games` may also differ between Prematch and Live. Use only the
current list from the latest API response.

## Submatch Names and Types

In `sub_games`, the name is stored in `game_name`:

```json
{
  "game_name": "Corners"
}
```

After requesting the additional match, its type is returned in `game_dop_name`:

```json
{
  "game_dop_name": "Corners"
}
```

`game_desk` may additionally describe a playing segment, such as `Half`, `Set`, or
`Quarter`. It does not replace `game_id` and must not be used as a permanent submatch
type ID.

The available names depend on the sport and its available markets. Do not define a fixed
list that every match must contain.

## Submatch Odds

A submatch is a separate sports line object with its own:

- `game_id`;
- `game_oc_counter`;
- markets in `game_oc_list`;
- selections and odds;
- `oc_pointer` values.

The odds in `game_oc_list` apply only to the selected submatch. They do not include bets
from the main match or other additional matches.

For example, if you request the “Corners, 1st Half” submatch, the response contains odds
only for first-half corners:

- not for every event in the first half;
- not for all corners in the main match;
- not for the entire main match.

To retrieve odds for all corners in the match, separately open the “Corners” submatch.
To retrieve odds for the main match, request `event` using the main match's `game_id`.

Use the `group` format to display the complete list, and preserve the market, column,
and selection order created by the API.

For details about the betting structure, see
[Odds and Betting Market Data Model](odds.md).

## Statistics in a Submatch

`stat_list` in a submatch response applies to the entire main match. It does not contain
separate statistics for the selected additional match.

For example, when requesting “Corners, 1st Half” or “1st Half,” `stat_list` still
contains the main match's general statistics. Do not filter statistics based on
`game_dop_name`.

Detailed rules are documented in
[Live Match Statistics Data Model](live-statistics.md).

## When a Submatch Is Unavailable

The additional-match list may change. If an item is no longer present in the current
`sub_games`, do not continue displaying it as available.

When requesting an outdated `game_id`, the API may return:

```json
{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "message": "Game id finished"
  }
}
```

After this response, stop updating the old ID. The message does not explain the exact
reason why the additional match disappeared.

## Group Matches and `event_plan`

`event_plan` and `sub_games` are different structures.

| Field | What it describes |
|---|---|
| `sub_games` | Additional lines and markets for one main match |
| `event_plan` | Complete list of teams competing on the home and away sides of a group match |

`event_plan` is intended for group matches. In the main object of such an event, the
sides may have generic names such as “Home — Away.” `event_plan` expands these sides and
lists all actual teams participating in the group match.

Each array object pairs one home-side team with the corresponding away-side team. The
complete array contains all such pairs and therefore provides the full team list for
both sides.

For example, `sub_games` may contain a separate “Corners” or “1st Half” market, while
`event_plan` for a “Home — Away” group match contains pairs of specific teams:

```text
Home                            Away
Anzoategui          →           Trujillanos
Caracas             →           Carabobo
```

A populated `event_plan` can be retrieved only through a specific `event` request. In
an `events` list, the field is returned as `[]`.

### `event_plan` Object Fields

| Field | Type | Description |
|---|---|---|
| `opp_1_name` | string | Name of the team competing on the home side |
| `opp_2_name` | string | Name of the team competing on the away side |
| `opp_1_id` | number or `null` | Home-side team ID |
| `opp_2_id` | number or `null` | Away-side team ID |
| `opp_1_country_id` | number or `null` | Country ID of the home-side team |
| `opp_2_country_id` | number or `null` | Country ID of the away-side team |
| `opp_1_icon` | string | Icon file name for the home-side team |
| `opp_2_icon` | string | Icon file name for the away-side team |
| `opp_1_date` | number or `null` | Date associated with the home-side team as a Unix timestamp |
| `opp_2_date` | number or `null` | Date associated with the away-side team as a Unix timestamp |
| `game_start` | number or `null` | Start time of this pair's meeting as a Unix timestamp |

Shortened group-match composition example:

```json
{
  "event_plan": [
    {
      "opp_1_name": "Anzoategui",
      "opp_2_name": "Trujillanos",
      "opp_1_id": 6354451,
      "opp_2_id": 2792,
      "opp_1_country_id": 41,
      "opp_2_country_id": 41,
      "opp_1_icon": "b85e2e3631e4b873b1d74975e6dd4e93.png",
      "opp_2_icon": "2792.png",
      "game_start": 1787342400
    },
    {
      "opp_1_name": "Caracas",
      "opp_2_name": "Carabobo",
      "opp_1_id": 2776,
      "opp_2_id": 29081,
      "opp_1_country_id": 41,
      "opp_2_country_id": 41,
      "opp_1_icon": "6309ee8475d59f87fff70fd08858e36f.png",
      "opp_2_icon": "56b11c23ac71e2f6934a7e0feb46dd5e.png",
      "game_start": 1787353200
    }
  ]
}
```

`event_plan` items are not links to submatches: they do not contain a separate
`game_id` for an `event` request. Use them to display the complete composition of the
home and away sides and the schedule of pairs within the group match.

For a participant icon, remove the extension from `opp_1_icon` or `opp_2_icon` and
insert the remaining name into the URL:

```text
https://cdn.sportapi.net/opp/v1/color/{iconName}.webp
```

## Practical Integration Rules

1. Retrieve `sub_games` only from the main match's detailed `event` response.
2. Open a submatch using its own `game_id`.
3. Request an additional match in the same sports line type: `live` or `line`.
4. Do not use the legacy `game_num` field.
5. Do not expect odds directly inside `sub_games`.
6. Link a submatch to the main match through `game_mid`.
7. Do not interpret submatch statistics as separate statistics for its market.
8. Do not mix additional matches from `sub_games` with the group-match composition in
   `event_plan`.
9. Refresh the submatch list using the current API response.

## Verification Responses

- [Main Live match with 13 submatches](../examples/json-responses/event.game-746146992.group.live.ru.json)
- [Main Prematch match with 24 submatches](../examples/json-responses/event.game-730321837.group.line.ru.json)
- [Detailed “Corners” submatch response](../examples/json-responses/event.subgame-746147010.corners.group.live.ru.json)

These saved verification responses are in Russian because the available full submatch
snapshot was captured using `lang=ru`. The object structure and field names are
language-independent.

## Related Documents

- [Match Data Model](match.md)
- [Live Match Statistics Data Model](live-statistics.md)
- [Odds and Betting Market Data Model](odds.md)
- [`event` — Specific Match](../api-reference/event.md)
- [Field Reference](field-reference.md)
