Matches

GET /tournaments/{tournament_id}/matches

Authorized Access

Returns the matches of the given tournament using various filters. If the match type is "ffa", the opponents are limited by the first 4 ordered by their position.

Resource URL

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

HTTP headers

  • X-Api-Key
    string

    API key of your application (see Authentication)

  • Authorization
    string

    Access token with organizer:result scope (see Authorization)

  • Range
    string

    A range of requested items using the matches unit. The size of the range cannot exceed 100. (see Pagination)

    Example: matches=0-99

Path parameters

  • tournament_id
    string

    The id of the tournament for which matches must be retrieved

    Example: 378426939508809728

Query Parameters

  • stage_ids
    array

    One or several stage ids to filter

    Example: 618965765764577354,618931468547654563

  • group_ids
    array

    One or several group ids to filter

    Example: 618965314871946714,618932178746476544

  • round_ids
    array

    One or several round ids to filter

    Example: 618943519431786343,618965178941654763

  • statuses
    array

    One or several match statuses to filter

    Example: pending,running

  • is_scheduled
    boolean

    Whether to include or exclude scheduled matches

    Possible values: 0, 1

  • scheduled_before
    datetime

    A datetime to include all matches scheduled before or at the datetime

    Format: RFC 3339 (combined date, time and utc offset)

    Example: 2015-12-31T00:00:00+00:00

  • scheduled_after
    datetime

    A datetime to include all matches scheduled after or at the datetime

    Format: RFC 3339 (combined date, time and utc offset)

    Example: 2015-12-31T00:00:00+00:00

  • participant_ids
    array

    One or several participant ids involved in the matches to filter

    Example: 618965416546776434,618975467354349191

  • sort
    string

    A method to sort the filtered data. Structure sorting uses the stage, group, round and match numbers. Schedule sorting uses the scheduled date. Latest results sorting uses the date at which the matches were played (not scheduled).

    Possible values: structure, schedule, latest_results

Request Body

This endpoint doesn't require a request body.

Response

[206] Matches retrieved

Example
[
    {
        "id": "618954615761465416",
        "stage_id": "618983668512789184",
        "group_id": "618985165765456465",
        "round_id": "618965146546456651",
        "number": 2,
        "type": "duel",
        "status": "pending",
        "settings": {
            "match_format": "bo3"
        },
        "scheduled_datetime": "2015-12-31T00:00:00+00:00",
        "played_at": "2015-12-31T00:00:00+00:00",
        "public_note": "A note on\ntwo lines\n",
        "private_note": "A note on\ntwo lines\n",
        "opponents": [
            {
                "number": 1,
                "position": 1,
                "result": "win",
                "rank": 3,
                "forfeit": false,
                "score": 15,
                "participant": {
                    "id": "375143143408309123",
                    "name": "Jon Snow",
                    "custom_fields": {
                        "country": "GB",
                        "logo": {
                            "logo_small": "url_to_small_image",
                            "logo_medium": "url_to_medium_image",
                            "logo_large": "url_to_large_image"
                        }
                    }
                }
            }
        ]
    }
]
Structure (collection)
  • id
    string

    The id of the match and the match (they both share the same id).

    Example: "618954615761465416"

  • stage_id
    string

    The id of the stage that contains this match

    Example: "618983668512789184"

  • group_id
    string

    The id of the group that contains this match

    Example: "618985165765456465"

  • round_id
    string

    The id of the round that contains this match

    Example: "618965146546456651"

  • number
    integer

    The match number (a relative identifier within a round)

    Example: 2

  • type
    string

    The type of match

    Possible values: duel, ffa, bye

  • status
    string

    The status of the match

    Possible values: pending, running, completed

  • settings
    object

    Settings that describes how the match must be played

    Example: {"match_format":"bo3"}

  • scheduled_datetime
    datetime|null

    The scheduled date of the match

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • played_at
    datetime|null

    The timestamp on which the match was played (a result was provided)

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • public_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, only visible by organizer.

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

  • opponents
    array[object]

    List of the opponents involved in this match.

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

Authorized Access

Returns a match by the given id. If the match type is "ffa", a match returns a maximum of 100 opponents.

Resource URL

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

HTTP headers

  • X-Api-Key
    string

    API key of your application (see Authentication)

  • Authorization
    string

    Access token with organizer:result scope (see Authorization)

Path parameters

  • tournament_id
    string

    The id of the match's tournament.

    Example: 378426939508809728

  • id
    string

    The id of the match to retrieve.

    Example: 212738912376478976

Query Parameters

This endpoint doesn't have any query parameters.

Request Body

This endpoint doesn't require a request body.

Response

[200] Match retrieved

Example
{
    "id": "618954615761465416",
    "stage_id": "618983668512789184",
    "group_id": "618985165765456465",
    "round_id": "618965146546456651",
    "number": 2,
    "type": "duel",
    "status": "pending",
    "settings": {
        "match_format": "bo3"
    },
    "scheduled_datetime": "2015-12-31T00:00:00+00:00",
    "played_at": "2015-12-31T00:00:00+00:00",
    "public_note": "A note on\ntwo lines\n",
    "private_note": "A note on\ntwo lines\n",
    "opponents": [
        {
            "number": 1,
            "position": 1,
            "result": "win",
            "rank": 3,
            "forfeit": false,
            "score": 15,
            "participant": {
                "id": "375143143408309123",
                "name": "Jon Snow",
                "custom_fields": {
                    "country": "GB",
                    "logo": {
                        "logo_small": "url_to_small_image",
                        "logo_medium": "url_to_medium_image",
                        "logo_large": "url_to_large_image"
                    }
                }
            },
            "properties": {
                "bans": [
                    "druid",
                    "cra"
                ]
            }
        }
    ]
}
Structure (object)
  • id
    string

    The id of the match and the match (they both share the same id).

    Example: "618954615761465416"

  • stage_id
    string

    The id of the stage that contains this match

    Example: "618983668512789184"

  • group_id
    string

    The id of the group that contains this match

    Example: "618985165765456465"

  • round_id
    string

    The id of the round that contains this match

    Example: "618965146546456651"

  • number
    integer

    The match number (a relative identifier within a round)

    Example: 2

  • type
    string

    The type of match

    Possible values: duel, ffa, bye

  • status
    string

    The status of the match

    Possible values: pending, running, completed

  • settings
    object

    Settings that describes how the match must be played

    Example: {"match_format":"bo3"}

  • scheduled_datetime
    datetime|null

    The scheduled date of the match

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • played_at
    datetime|null

    The timestamp on which the match was played (a result was provided)

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • public_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, only visible by organizer.

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

  • opponents
    array[object]

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

Authorized Access

Update information and detailed outcome about one match.

Resource URL

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

HTTP headers

  • X-Api-Key
    string

    API key of your application (see Authentication)

  • Authorization
    string

    Access token with organizer:result scope (see Authorization)

Path parameters

  • tournament_id
    string

    The id of the desired tournament.

    Example: 378426939508809728

  • id
    string

    The id of the desired match.

    Example: 212738912376478976

Query Parameters

This endpoint doesn't have any query parameters.

Request Body

Update data

Example
{
    "scheduled_datetime": "2015-12-31T00:00:00+00:00",
    "public_note": "A note on\ntwo lines\n",
    "private_note": "A note on\ntwo lines\n",
    "opponents": [
        {
            "number": 1,
            "position": 1,
            "result": "win",
            "rank": 3,
            "forfeit": false,
            "score": 15,
            "properties": {
                "bans": [
                    "druid",
                    "cra"
                ]
            }
        }
    ]
}
Structure (object)
  • status
    string|null

    Optional

    The status of the match, set to NULL for an automatic update of the status.

    Possible values: pending, running, completed

  • scheduled_datetime
    datetime|null

    Optional

    The scheduled date of the match

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • public_note
    string|null

    Optional

    Public note of a match, written by the organizer.

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

  • private_note
    string|null

    Optional

    Private note of a match, only visible by organizer.

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

  • opponents
    array[object]

    Optional

    List of the opponents involved in this match.

Response

[200] Success

Example
{
    "id": "618954615761465416",
    "stage_id": "618983668512789184",
    "group_id": "618985165765456465",
    "round_id": "618965146546456651",
    "number": 2,
    "type": "duel",
    "status": "pending",
    "settings": {
        "match_format": "bo3"
    },
    "scheduled_datetime": "2015-12-31T00:00:00+00:00",
    "played_at": "2015-12-31T00:00:00+00:00",
    "public_note": "A note on\ntwo lines\n",
    "private_note": "A note on\ntwo lines\n",
    "opponents": [
        {
            "number": 1,
            "position": 1,
            "result": "win",
            "rank": 3,
            "forfeit": false,
            "score": 15,
            "participant": {
                "id": "375143143408309123",
                "name": "Jon Snow",
                "custom_fields": {
                    "country": "GB",
                    "logo": {
                        "logo_small": "url_to_small_image",
                        "logo_medium": "url_to_medium_image",
                        "logo_large": "url_to_large_image"
                    }
                }
            },
            "properties": {
                "bans": [
                    "druid",
                    "cra"
                ]
            }
        }
    ]
}
Structure (object)
  • id
    string

    The id of the match and the match (they both share the same id).

    Example: "618954615761465416"

  • stage_id
    string

    The id of the stage that contains this match

    Example: "618983668512789184"

  • group_id
    string

    The id of the group that contains this match

    Example: "618985165765456465"

  • round_id
    string

    The id of the round that contains this match

    Example: "618965146546456651"

  • number
    integer

    The match number (a relative identifier within a round)

    Example: 2

  • type
    string

    The type of match

    Possible values: duel, ffa, bye

  • status
    string

    The status of the match

    Possible values: pending, running, completed

  • settings
    object

    Settings that describes how the match must be played

    Example: {"match_format":"bo3"}

  • scheduled_datetime
    datetime|null

    The scheduled date of the match

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • played_at
    datetime|null

    The timestamp on which the match was played (a result was provided)

    Format: RFC 3339 (combined date, time and utc offset)

    Example: "2015-12-31T00:00:00+00:00"

  • public_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, only visible by organizer.

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

  • opponents
    array[object]