API reference › Matches

GET /matches

Retrieves the matches of all your tournaments 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/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 can not exceed 100. (see Pagination)

    Example: matches=0-99

Query Parameters

  • stage_ids
    array

    One or several stage ids to filter.

    Example: 618965765764577354,618931468547654563

  • stage_numbers
    array

    One or several stage numbers to filter.

    Example: 1,3

  • group_ids
    array

    One or several group ids to filter.

    Example: 618965314871946714,618932178746476544

  • group_numbers
    array

    One or several group numbers to filter.

    Example: 2,4

  • round_ids
    array

    One or several round ids to filter.

    Example: 618943519431786343,618965178941654763

  • round_numbers
    array

    One or several round numbers to filter.

    Example: 1,2

  • statuses
    array

    One or several match statuses to filter.

    Possible values: pending, running, completed

    Example: pending,running

  • is_scheduled
    boolean

    Whether to include scheduled matches.

    Possible values: 0, 1

  • scheduled_before
    string

    A datetime to include all matches scheduled before or at the datetime in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

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

  • scheduled_after
    string

    A datetime to include all matches scheduled after or at the datetime in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

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

  • played_before
    string

    A datetime to include all matches played before or at the datetime in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

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

  • played_after
    string

    A datetime to include all matches played after or at the datetime in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

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

  • disciplines
    array

    Only return matches for the tournaments with the discipline.

    Example: leagueoflegends,fifa19

  • tournament_ids
    array

    Only return matches for the given list of tournaments.

    Example: 618965416546776434,618975467354349191

  • participant_ids
    array

    One or several participant ids involved in the matches to filter.

    Example: 618965416546776434,618975467354349191

  • custom_user_identifiers
    array

    A list of external custom user identifiers.

    Example: acme:account:1234,acme:account:1235

  • match_ids
    array

    Only return matches for the given list of ids.

    Example: 2468971166855626795,436314459115419242

  • sort
    string

    A method to sort the filtered data. "structure" sorts using the stage, group, round and match numbers. "schedule" sorts using the scheduled date. "latest results" sorts using the date at which the matches were played (not scheduled).

    Possible values: structure, schedule, latest_results

    Default: structure

    Example: schedule

Request Body

This endpoint does not require a request body.

Response

[206] Matches retrieved

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",
        "id": "618954615761465416",
        "status": "pending",
        "stage_id": "618983668512789184",
        "group_id": "618985165765456465",
        "round_id": "618965146546456651",
        "number": 2,
        "type": "duel",
        "settings": {},
        "played_at": "2015-12-31T00:00:00+00:00",
        "report_closed": true,
        "opponents": [
            {
                "number": 1,
                "position": 1,
                "result": "win",
                "rank": 3,
                "forfeit": false,
                "score": 15,
                "participant": {
                    "id": "375143143408309123",
                    "name": "Northmen",
                    "custom_user_identifier": "acme:account:1234",
                    "custom_fields": {}
                }
            }
        ],
        "tournament_id": "378426939508809728"
    }
]
Structure (collection)
  • scheduled_datetime
    string|null

    The scheduled date of the match in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

    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, written by the organizer.

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

  • id
    string

    The id of the match.

    Example: "618954615761465416"

  • status
    string

    The status of the match.

    Possible values: pending, running, completed

  • 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|null

    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 match type.

    Possible values: duel, ffa, bye

  • settings
    object

    Settings that describe the various options related to the match.

    Example: {}

  • played_at
    string|null

    The date and time when the match was completed (a result was provided).

    Format: datetime

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

  • report_closed
    boolean

    Whether the match report is closed.

    Example: true

  • opponents
    array[object]

    List of the opponents involved in this match.

  • tournament_id
    string

    The id of the tournament that contains this match.

    Example: "378426939508809728"

GET /matches/{id}

Retrieves a match identified 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/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

  • id
    string

    The id of the requested custom field.

Query Parameters

This endpoint does not have any query parameters.

Request Body

This endpoint does not require a request body.

Response

[200] Match retrieved

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",
        "id": "618954615761465416",
        "status": "pending",
        "stage_id": "618983668512789184",
        "group_id": "618985165765456465",
        "round_id": "618965146546456651",
        "number": 2,
        "type": "duel",
        "settings": {},
        "played_at": "2015-12-31T00:00:00+00:00",
        "report_closed": true,
        "opponents": [
            {
                "number": 1,
                "position": 1,
                "result": "win",
                "rank": 3,
                "forfeit": false,
                "score": 15,
                "participant": {
                    "id": "375143143408309123",
                    "name": "Northmen",
                    "custom_user_identifier": "acme:account:1234",
                    "custom_fields": {}
                },
                "properties": {}
            }
        ],
        "report_status": "report",
        "tournament_id": "378426939508809728"
    }
]
Structure (collection)
  • scheduled_datetime
    string|null

    The scheduled date of the match in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

    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, written by the organizer.

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

  • id
    string

    The id of the match.

    Example: "618954615761465416"

  • status
    string

    The status of the match.

    Possible values: pending, running, completed

  • 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|null

    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 match type.

    Possible values: duel, ffa, bye

  • settings
    object

    Settings that describe the various options related to the match.

    Example: {}

  • played_at
    string|null

    The date and time when the match was completed (a result was provided).

    Format: datetime

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

  • report_closed
    boolean

    Whether the match report is closed.

    Example: true

  • opponents
    array[object]

    List of the opponents involved in this match.

  • report_status
    string|null

    the report status

    Possible values: report, dispute

  • tournament_id
    string

    The id of the tournament that contains this match.

    Example: "378426939508809728"

PATCH /matches/{id}

Updates information and detailed outcome of a match identified by the given id.

Resource URL

https://api.toornament.com/organizer/v2/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

  • id
    string

    The id of the requested custom field.

Query Parameters

This endpoint does not 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": {}
        }
    ]
}
Structure (object)
  • scheduled_datetime
    string|null

    Optional

    The scheduled date of the match in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

    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, written by the organizer.

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

  • opponents
    array[object]

    Optional

    List of the opponents involved in this match.

Response

[200] Success.

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",
    "id": "618954615761465416",
    "status": "pending",
    "stage_id": "618983668512789184",
    "group_id": "618985165765456465",
    "round_id": "618965146546456651",
    "number": 2,
    "type": "duel",
    "settings": {},
    "played_at": "2015-12-31T00:00:00+00:00",
    "report_closed": true,
    "opponents": [
        {
            "number": 1,
            "position": 1,
            "result": "win",
            "rank": 3,
            "forfeit": false,
            "score": 15,
            "participant": {
                "id": "375143143408309123",
                "name": "Northmen",
                "custom_user_identifier": "acme:account:1234",
                "custom_fields": {}
            },
            "properties": {}
        }
    ],
    "report_status": "report",
    "tournament_id": "378426939508809728"
}
Structure (object)
  • scheduled_datetime
    string|null

    The scheduled date of the match in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

    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, written by the organizer.

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

  • id
    string

    The id of the match.

    Example: "618954615761465416"

  • status
    string

    The status of the match.

    Possible values: pending, running, completed

  • 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|null

    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 match type.

    Possible values: duel, ffa, bye

  • settings
    object

    Settings that describe the various options related to the match.

    Example: {}

  • played_at
    string|null

    The date and time when the match was completed (a result was provided).

    Format: datetime

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

  • report_closed
    boolean

    Whether the match report is closed.

    Example: true

  • opponents
    array[object]

    List of the opponents involved in this match.

  • report_status
    string|null

    the report status

    Possible values: report, dispute

  • tournament_id
    string

    The id of the tournament that contains this match.

    Example: "378426939508809728"

LegacyGET /tournaments/{tournament_id}/matches

This endpoint is in legacy mode. Access will soon be deprecated. It is therefore advised to use another endpoint when possible.

Retrieve the matches from the tournament. If the match type is "ffa", only the first 4 opponents, ordered by position, are listed in each match.

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 can not exceed 100. (see Pagination)

    Example: matches=0-99

Path parameters

  • tournament_id
    string

    The id of the tournament you want to retrieve data about.

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.

    Possible values: pending, running, completed

    Example: pending,running

  • is_scheduled
    boolean

    Whether to include scheduled matches.

    Possible values: 0, 1

  • scheduled_before
    string

    A datetime to include all matches scheduled before or at the datetime in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

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

  • scheduled_after
    string

    A datetime to include all matches scheduled after or at the datetime in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

    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

  • custom_user_identifiers
    array

    A list of external custom user identifiers.

    Example: acme:account:1234,acme:account:1235

  • sort
    string

    A method to sort the filtered data. "structure" sorts using the stage, group, round and match numbers. "schedule" sorts using the scheduled date. "latest results" sorts using the date at which the matches were played (not scheduled).

    Possible values: structure, schedule, latest_results

    Default: structure

    Example: schedule

Request Body

This endpoint does not require a request body.

Response

[206] Matches retrieved

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",
        "id": "618954615761465416",
        "status": "pending",
        "stage_id": "618983668512789184",
        "group_id": "618985165765456465",
        "round_id": "618965146546456651",
        "number": 2,
        "type": "duel",
        "settings": {},
        "played_at": "2015-12-31T00:00:00+00:00",
        "report_closed": true,
        "opponents": [
            {
                "number": 1,
                "position": 1,
                "result": "win",
                "rank": 3,
                "forfeit": false,
                "score": 15,
                "participant": {
                    "id": "375143143408309123",
                    "name": "Northmen",
                    "custom_user_identifier": "acme:account:1234",
                    "custom_fields": {}
                }
            }
        ]
    }
]
Structure (collection)
  • scheduled_datetime
    string|null

    The scheduled date of the match in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

    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, written by the organizer.

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

  • id
    string

    The id of the match.

    Example: "618954615761465416"

  • status
    string

    The status of the match.

    Possible values: pending, running, completed

  • 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|null

    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 match type.

    Possible values: duel, ffa, bye

  • settings
    object

    Settings that describe the various options related to the match.

    Example: {}

  • played_at
    string|null

    The date and time when the match was completed (a result was provided).

    Format: datetime

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

  • report_closed
    boolean

    Whether the match report is closed.

    Example: true

  • opponents
    array[object]

    List of the opponents involved in this match.

LegacyGET /tournaments/{tournament_id}/matches/{id}

This endpoint is in legacy mode. Access will soon be deprecated. It is therefore advised to use another endpoint when possible.

Returns the match with the given id. A match is limited to 2 participants in “duel” type, and 100 participants in “ffa” type.

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 tournament you want to retrieve data about.

  • id
    string

    The id of the requested custom field.

Query Parameters

This endpoint does not have any query parameters.

Request Body

This endpoint does not require a request body.

Response

[200] Match retrieved

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",
        "id": "618954615761465416",
        "status": "pending",
        "stage_id": "618983668512789184",
        "group_id": "618985165765456465",
        "round_id": "618965146546456651",
        "number": 2,
        "type": "duel",
        "settings": {},
        "played_at": "2015-12-31T00:00:00+00:00",
        "report_closed": true,
        "opponents": [
            {
                "number": 1,
                "position": 1,
                "result": "win",
                "rank": 3,
                "forfeit": false,
                "score": 15,
                "participant": {
                    "id": "375143143408309123",
                    "name": "Northmen",
                    "custom_user_identifier": "acme:account:1234",
                    "custom_fields": {}
                },
                "properties": {}
            }
        ],
        "report_status": "report"
    }
]
Structure (collection)
  • scheduled_datetime
    string|null

    The scheduled date of the match in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

    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, written by the organizer.

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

  • id
    string

    The id of the match.

    Example: "618954615761465416"

  • status
    string

    The status of the match.

    Possible values: pending, running, completed

  • 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|null

    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 match type.

    Possible values: duel, ffa, bye

  • settings
    object

    Settings that describe the various options related to the match.

    Example: {}

  • played_at
    string|null

    The date and time when the match was completed (a result was provided).

    Format: datetime

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

  • report_closed
    boolean

    Whether the match report is closed.

    Example: true

  • opponents
    array[object]

    List of the opponents involved in this match.

  • report_status
    string|null

    the report status

    Possible values: report, dispute

LegacyPATCH /tournaments/{tournament_id}/matches/{id}

This endpoint is in legacy mode. Access will soon be deprecated. It is therefore advised to use another endpoint when possible.

Updates information and detailed outcome of a 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 tournament you want to retrieve data about.

  • id
    string

    The id of the requested custom field.

Query Parameters

This endpoint does not 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": {}
        }
    ]
}
Structure (object)
  • scheduled_datetime
    string|null

    Optional

    The scheduled date of the match in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

    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, written by the organizer.

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

  • opponents
    array[object]

    Optional

    List of the opponents involved in this match.

Response

[200] Success.

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",
    "id": "618954615761465416",
    "status": "pending",
    "stage_id": "618983668512789184",
    "group_id": "618985165765456465",
    "round_id": "618965146546456651",
    "number": 2,
    "type": "duel",
    "settings": {},
    "played_at": "2015-12-31T00:00:00+00:00",
    "report_closed": true,
    "opponents": [
        {
            "number": 1,
            "position": 1,
            "result": "win",
            "rank": 3,
            "forfeit": false,
            "score": 15,
            "participant": {
                "id": "375143143408309123",
                "name": "Northmen",
                "custom_user_identifier": "acme:account:1234",
                "custom_fields": {}
            },
            "properties": {}
        }
    ],
    "report_status": "report"
}
Structure (object)
  • scheduled_datetime
    string|null

    The scheduled date of the match in RFC 3339 format (combined date, time and utc offset).

    Format: datetime

    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, written by the organizer.

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

  • id
    string

    The id of the match.

    Example: "618954615761465416"

  • status
    string

    The status of the match.

    Possible values: pending, running, completed

  • 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|null

    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 match type.

    Possible values: duel, ffa, bye

  • settings
    object

    Settings that describe the various options related to the match.

    Example: {}

  • played_at
    string|null

    The date and time when the match was completed (a result was provided).

    Format: datetime

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

  • report_closed
    boolean

    Whether the match report is closed.

    Example: true

  • opponents
    array[object]

    List of the opponents involved in this match.

  • report_status
    string|null

    the report status

    Possible values: report, dispute