Matches

GET /tournaments/{tournament_id}/matches

Returns a collection of matches from one tournament. The collection may be filtered and sorted by optional query parameters. The tournament must be public to have access to its matches, meaning the tournament organizer has published it. The matches are returned by 100.

Update

A page parameter has been added to this endpoint with 100 items per page.

The timezone field will always return null now as the timezone used is now the tournament one.

Resource URL

https://api.toornament.com/v1/tournaments/{tournament_id}/matches

Path parameters

  • tournament_id
    string

    The id of the desired tournament.

Query Parameters

  • has_result
    boolean

    When set to '1', returns only matches with a result. When set to '0', returns only matches without a result.

    Allowed values: 1, 0

    Default: 0

  • stage_number
    integer

    Returns matches in the given stage number. If the stage does not exist, it'll return no matches.

  • group_number
    integer

    Returns matches in the given group number. If the group does not exist, it'll return no matches.

  • round_number
    integer

    Returns matches in the given round number. If the round does not exist, it'll return no matches.

  • sort
    string

    Sorts the collection in a particular order. 'structure' sorts the matches based on the stage, group and round numbers; 'schedule' sorts the matches based on the date from earlier to later; 'latest' sorts the matches based on the date from later to earlier.

    Allowed values: structure, schedule, latest

    Default: structure

  • participant_id
    string

    Returns matches that involves the given participant's id.

  • with_games
    boolean

    When set to '1', it will include a summary of each game of the match.

    Allowed values: 1, 0

    Default: 0

  • page
    integer

    New

    Page requested of the list.

    Default: 1

Request Body

This endpoint doesn't require a request body.

Response

[200] Success

Example
[
    {
        "id": "378426939508809728",
        "type": "duel",
        "discipline": "my_discipline",
        "status": "pending",
        "tournament_id": "5608fd12140ba061298b4569",
        "number": 1,
        "stage_number": 1,
        "group_number": 2,
        "round_number": 3,
        "date": "2015-09-06T00:10:00-0600",
        "timezone": null,
        "match_format": "bo3",
        "opponents": [
            {
                "number": 1,
                "participant": {
                    "id": "378426939508809728",
                    "name": "Evil Geniuses",
                    "country": "US"
                },
                "result": 1,
                "score": null,
                "forfeit": false
            }
        ]
    }
]
Structure (collection)
  • id
    string

    An unique identifier for this match.

    Example: "378426939508809728"

  • type
    string

    Type of match: "duel" means only two opponents are involved; "ffa" means more than two opponents are involved.

    Possible values: duel, ffa

  • discipline
    string

    The discipline unique identifier of the match.

    Example: "my_discipline"

  • status
    string

    Status of the match: "pending" implies it has not yet started; "running" means it has started but not yet ended; "completed" indicates the match is finished.

    Possible values: pending, running, completed

  • tournament_id
    string

    The tournament's unique identifier of this match.

    Example: "5608fd12140ba061298b4569"

  • number
    integer

    Number of this match.

    Example: 1

  • stage_number
    integer

    Stage number of this match.

    Example: 1

  • group_number
    integer

    Group number of this match.

    Example: 2

  • round_number
    integer

    Round number of this match.

    Example: 3

  • date
    string|null

    Date of this match, either expected or actual. This value is represented as an ISO 8601 date containing the date, the time and the time zone.

    Example: "2015-09-06T00:10:00-0600"

  • timezone
    string|null

    Update

    Time-zone of the match. This value is represented using the IANA tz database.

    Example: null

  • match_format
    string|null

    Defines how many games are required to decide which participant won, draw or lost the match

    Possible values: none, one, home_away, bo3, bo5, bo7, bo9, bo11

  • opponents
    array[object]

    List of the opponents involved in this match.

  • games
    array[object]

    Optional

    This property is added when the parameter "with_games" is enabled.

GET /tournaments/{tournament_id}/matches/{id}

Returns detailed information about one match.

Update

When set to 1, the "with_games" parameter will no longer return participants information. They can be found in the match opponent properties.

The timezone field will always return null now as the timezone used is now the tournament one.

Resource URL

https://api.toornament.com/v1/tournaments/{tournament_id}/matches/{id}

Path parameters

  • tournament_id
    string

    The id of the match's tournament.

  • id
    string

    The id of the requested match.

Query Parameters

  • with_games
    boolean

    Update

    When set to '1', it will include the games of the match.

    Allowed values: 1, 0

    Default: 0

Request Body

This endpoint doesn't require a request body.

Response

[200] Success

Example
{
    "id": "378426939508809728",
    "type": "duel",
    "discipline": "my_discipline",
    "status": "pending",
    "tournament_id": "5608fd12140ba061298b4569",
    "number": 1,
    "stage_number": 1,
    "group_number": 2,
    "round_number": 3,
    "date": "2015-09-06T00:10:00-0600",
    "timezone": null,
    "match_format": "bo3",
    "note": "A note on\ntwo lines\n",
    "opponents": [
        {
            "number": 1,
            "participant": {
                "id": "378426939508809728",
                "name": "Evil Geniuses",
                "country": "US"
            },
            "result": 1,
            "score": null,
            "forfeit": false
        }
    ],
    "streams": [
        {
            "id": "378426939508809728",
            "name": "DreamhackCS",
            "url": "http:\/\/www.twitch.tv\/dreamhackcs",
            "language": "en"
        }
    ],
    "vods": [
        {
            "name": "TSM vs. EnVyUs (DH)",
            "url": "https:\/\/www.youtube.com\/watch?v=SI5QgDJkaSU",
            "language": "en",
            "category": "replay"
        }
    ],
    "private_note": "A note on\ntwo lines\n"
}
Structure (object)
  • id
    string

    An unique identifier for this match.

    Example: "378426939508809728"

  • type
    string

    Type of match: "duel" means only two opponents are involved; "ffa" means more than two opponents are involved.

    Possible values: duel, ffa

  • discipline
    string

    The discipline unique identifier of the match.

    Example: "my_discipline"

  • status
    string

    Status of the match: "pending" implies it has not yet started; "running" means it has started but not yet ended; "completed" indicates the match is finished.

    Possible values: pending, running, completed

  • tournament_id
    string

    The tournament's unique identifier of this match.

    Example: "5608fd12140ba061298b4569"

  • number
    integer

    Number of this match.

    Example: 1

  • stage_number
    integer

    Stage number of this match.

    Example: 1

  • group_number
    integer

    Group number of this match.

    Example: 2

  • round_number
    integer

    Round number of this match.

    Example: 3

  • date
    string|null

    Date of this match, either expected or actual. This value is represented as an ISO 8601 date containing the date, the time and the time zone.

    Example: "2015-09-06T00:10:00-0600"

  • timezone
    string|null

    Update

    Time-zone of the match. This value is represented using the IANA tz database.

    Example: null

  • match_format
    string|null

    Defines how many games are required to decide which participant won, draw or lost the match

    Possible values: none, one, home_away, bo3, bo5, bo7, bo9, bo11

  • note
    string|null

    Public note of a match, written by the organizer.

    Example: "A note on\ntwo lines\n"

  • opponents
    array[object]

    List of the opponents involved in this match.

  • games
    array[object]

    Optional

    This property is added when the parameter "with_games" is enabled.

  • streams
    array[object]

    Optional

  • vods
    array[object]

    Optional

  • private_note
    string|null

    PrivateOptional

    Private note of a match, written by the organizer.

    Example: "A note on\ntwo lines\n"

PATCH /tournaments/{tournament_id}/matches/{id}

Authorized Access

If you need to make changes on your match data, you are able to do so by patching one or several fields of your match.

Warning! This endpoint can only be used with an Authorized Access.

Update

The timezone field will always return null now as the timezone used is now the tournament one.

Resource URL

https://api.toornament.com/v1/tournaments/{tournament_id}/matches/{id}

Path parameters

  • tournament_id
    string

    The id of the match's tournament.

  • id
    string

    The id of the requested match.

Query Parameters

This endpoint doesn't have any query parameters.

Request Body

Match data

Example
{
    "date": "2015-09-06T00:10:00-0600",
    "timezone": null,
    "match_format": "bo3",
    "note": "A note on\ntwo lines\n",
    "private_note": "A note on\ntwo lines\n",
    "streams": [
        "56742bc7cc3c17ee608b4567"
    ],
    "vods": [
        {
            "name": "TSM vs. EnVyUs (DH)",
            "url": "https:\/\/www.youtube.com\/watch?v=SI5QgDJkaSU",
            "language": "en",
            "category": "replay"
        }
    ]
}
Structure (object)
  • date
    string|null

    Date of this match, either expected or actual. This value is represented as an ISO 8601 date containing the date, the time and the time zone.

    Example: "2015-09-06T00:10:00-0600"

  • timezone
    string|null

    Update

    Time-zone of the match. This value is represented using the IANA tz database.

    Example: null

  • match_format
    string|null

    Defines how many games are required to decide which participant won, draw or lost the match

    Possible values: none, one, home_away, bo3, bo5, bo7, bo9, bo11

  • note
    string|null

    Public note of a match, written by the organizer.

    Example: "A note on\ntwo lines\n"

  • private_note
    string|null

    Private note of a match, written by the organizer.

    Example: "A note on\ntwo lines\n"

  • streams
    array[string]

    Optional

    Example: ["56742bc7cc3c17ee608b4567"]

  • vods
    array[object]

    Optional

Response

[200] Success

Example
{
    "id": "378426939508809728",
    "type": "duel",
    "discipline": "my_discipline",
    "status": "pending",
    "tournament_id": "5608fd12140ba061298b4569",
    "number": 1,
    "stage_number": 1,
    "group_number": 2,
    "round_number": 3,
    "date": "2015-09-06T00:10:00-0600",
    "timezone": null,
    "match_format": "bo3",
    "note": "A note on\ntwo lines\n",
    "private_note": "A note on\ntwo lines\n",
    "opponents": [
        {
            "number": 1,
            "participant": {
                "id": "378426939508809728",
                "name": "Evil Geniuses",
                "country": "US"
            },
            "result": 1,
            "score": null,
            "forfeit": false
        }
    ],
    "streams": [
        {
            "id": "378426939508809728",
            "name": "DreamhackCS",
            "url": "http:\/\/www.twitch.tv\/dreamhackcs",
            "language": "en"
        }
    ],
    "vods": [
        {
            "name": "TSM vs. EnVyUs (DH)",
            "url": "https:\/\/www.youtube.com\/watch?v=SI5QgDJkaSU",
            "language": "en",
            "category": "replay"
        }
    ]
}
Structure (object)
  • id
    string

    An unique identifier for this match.

    Example: "378426939508809728"

  • type
    string

    Type of match: "duel" means only two opponents are involved; "ffa" means more than two opponents are involved.

    Possible values: duel, ffa

  • discipline
    string

    The discipline unique identifier of the match.

    Example: "my_discipline"

  • status
    string

    Status of the match: "pending" implies it has not yet started; "running" means it has started but not yet ended; "completed" indicates the match is finished.

    Possible values: pending, running, completed

  • tournament_id
    string

    The tournament's unique identifier of this match.

    Example: "5608fd12140ba061298b4569"

  • number
    integer

    Number of this match.

    Example: 1

  • stage_number
    integer

    Stage number of this match.

    Example: 1

  • group_number
    integer

    Group number of this match.

    Example: 2

  • round_number
    integer

    Round number of this match.

    Example: 3

  • date
    string|null

    Date of this match, either expected or actual. This value is represented as an ISO 8601 date containing the date, the time and the time zone.

    Example: "2015-09-06T00:10:00-0600"

  • timezone
    string|null

    Update

    Time-zone of the match. This value is represented using the IANA tz database.

    Example: null

  • match_format
    string|null

    Defines how many games are required to decide which participant won, draw or lost the match

    Possible values: none, one, home_away, bo3, bo5, bo7, bo9, bo11

  • note
    string|null

    Public note of a match, written by the organizer.

    Example: "A note on\ntwo lines\n"

  • private_note
    string|null

    Private note of a match, written by the organizer.

    Example: "A note on\ntwo lines\n"

  • opponents
    array[object]

    List of the opponents involved in this match.

  • streams
    array[object]

    Optional

  • vods
    array[object]

    Optional

GET /tournaments/{tournament_id}/matches/{id}/result

Returns detailed result about one match.

Resource URL

https://api.toornament.com/v1/tournaments/{tournament_id}/matches/{id}/result

Path parameters

  • tournament_id
    string

    The id of the match's tournament.

  • id
    string

    The id of the requested match.

Query Parameters

This endpoint doesn't have any query parameters.

Request Body

This endpoint doesn't require a request body.

Response

[200] Success

Example
{
    "status": "pending",
    "opponents": [
        {
            "number": 1,
            "result": 1,
            "score": null,
            "forfeit": false
        }
    ]
}
Structure (object)
  • status
    string

    Status of the match: "pending" implies it has not yet started; "running" means it has started but not yet ended; "completed" indicates the match is finished.

    Possible values: pending, running, completed

  • opponents
    array[object]

    List of the opponents involved in this match.

PUT /tournaments/{tournament_id}/matches/{id}/result

Authorized Access

Update or create detailed result about one match.

Warning! This endpoint can only be used with an Authorized Access.

Resource URL

https://api.toornament.com/v1/tournaments/{tournament_id}/matches/{id}/result

Path parameters

  • tournament_id
    string

    The id of the match's tournament.

  • id
    string

    The id of the requested match.

Query Parameters

This endpoint doesn't have any query parameters.

Request Body

Update or create

Example
{
    "status": "pending",
    "opponents": [
        {
            "number": 1,
            "result": 1,
            "score": null,
            "forfeit": false
        }
    ]
}
Structure (object)
  • status
    string

    Status of the match: "pending" implies it has not yet started; "running" means it has started but not yet ended; "completed" indicates the match is finished.

    Possible values: pending, running, completed

  • opponents
    array[object]

    List of the opponents involved in this match.

Response

[200] Success

Example
{
    "status": "pending",
    "opponents": [
        {
            "number": 1,
            "result": 1,
            "score": null,
            "forfeit": false
        }
    ]
}
Structure (object)
  • status
    string

    Status of the match: "pending" implies it has not yet started; "running" means it has started but not yet ended; "completed" indicates the match is finished.

    Possible values: pending, running, completed

  • opponents
    array[object]

    List of the opponents involved in this match.

GET /disciplines/{discipline_id}/matches

Retrieve a collection of matches from a specific discipline, filtered and sorted by the given query parameters. It might be a list of matches from different tournaments, but only from public tournaments. The matches are returned by 20.

Update

The timezone field will always return null now as the timezone used is now the tournament one.

Resource URL

https://api.toornament.com/v1/disciplines/{discipline_id}/matches

Path parameters

  • discipline_id
    string

    The string id of the discipline

Query Parameters

  • featured
    boolean

    When set to "1", returns matches from featured tournaments in the collection. When set to "0", it returns matches from tournaments without featured. Featured tournaments are tagged by Toornament as major tournaments for a given discipline.

    Allowed values: 0, 1

  • has_result
    boolean

    When set to '1', returns only matches with a result. When set to '0', returns only matches without a result.

    Allowed values: 1, 0

  • sort
    string

    Sorts the collection in a particular order. 'date_asc' sort matches from oldest to newest and 'date_desc' sort matches from newest to oldest.

    Allowed values: date_asc, date_desc

    Default: date_asc

  • participant_id
    string

    Returns matches that involves the given participant's id.

  • tournament_ids
    string

    Returns matches from the filtered tournaments.

    Example: 5617bb3af3df95f2318b4567,5617bb3af3df95f231a16874

  • with_games
    boolean

    When set to '1', it will include a summary of each game of the match.

    Allowed values: 1, 0

    Default: 0

  • before_date
    date

    Filter all matches scheduled before this date.

  • after_date
    date

    Filter all matches scheduled after this date.

  • page
    integer

    Page requested of the list.

    Default: 1

Request Body

This endpoint doesn't require a request body.

Response

[200] Success

Example
[
    {
        "id": "378426939508809728",
        "type": "duel",
        "discipline": "my_discipline",
        "status": "pending",
        "tournament": {
            "id": "378426939508809728",
            "name": "My Weekly Tournament",
            "full_name": "My Weekly Tournament - Long title",
            "featured": false
        },
        "number": 1,
        "stage_number": 1,
        "group_number": 2,
        "round_number": 3,
        "date": "2015-09-06T00:10:00-0600",
        "timezone": null,
        "match_format": "bo3",
        "opponents": [
            {
                "number": 1,
                "participant": {
                    "id": "378426939508809728",
                    "name": "Evil Geniuses",
                    "country": "US"
                },
                "result": 1,
                "score": null,
                "forfeit": false
            }
        ]
    }
]
Structure (collection)
  • id
    string

    An unique identifier for this match.

    Example: "378426939508809728"

  • type
    string

    Type of match: "duel" means only two opponents are involved; "ffa" means more than two opponents are involved.

    Possible values: duel, ffa

  • discipline
    string

    The discipline unique identifier of the match.

    Example: "my_discipline"

  • status
    string

    Status of the match: "pending" implies it has not yet started; "running" means it has started but not yet ended; "completed" indicates the match is finished.

    Possible values: pending, running, completed

  • tournament
    object

  • number
    integer

    Number of this match.

    Example: 1

  • stage_number
    integer

    Stage number of this match.

    Example: 1

  • group_number
    integer

    Group number of this match.

    Example: 2

  • round_number
    integer

    Round number of this match.

    Example: 3

  • date
    string|null

    Date of this match, either expected or actual. This value is represented as an ISO 8601 date containing the date, the time and the time zone.

    Example: "2015-09-06T00:10:00-0600"

  • timezone
    string|null

    Update

    Time-zone of the match. This value is represented using the IANA tz database.

    Example: null

  • match_format
    string|null

    Defines how many games are required to decide which participant won, draw or lost the match

    Possible values: none, one, home_away, bo3, bo5, bo7, bo9, bo11

  • opponents
    array[object]

    List of the opponents involved in this match.

  • games
    array[object]

    Optional

    This property is added when the parameter "with_games" is enabled.