Matches (JD2017)

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

• custom_user_identifier

  string

  An external user identifier, use the format that suits you best

  Example: acme:account:1234

• 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",
        "report_closed": true,
        "opponents": [
            {
                "number": 1,
                "position": 1,
                "result": "win",
                "rank": 3,
                "forfeit": false,
                "score": 15,
                "participant": {
                    "id": "375143143408309123",
                    "name": "Jon Snow",
                    "custom_user_identifier": "acme:account:1234",
                    "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"

• report_closed

  boolean

  Wathever if the match report is closed

  Example: true

• opponents

  array[object]

  List of the opponents involved in this match.

  • number

    integer

    The match opponent number (a relative identifier within a match)

    Example: 1

  • position

    integer

    The match opponent position (calculate by internal processes)

    Example: 1

  • result

    string|null

    The match result of the opponent

    Possible values: win, draw, loss

  • rank

    integer|null

    The match rank of the opponent

    Example: 3

  • forfeit

    boolean

    Whether the opponent is forfeit

    Example: false

  • score

    integer|null

    The score of the opponent

    Example: 15

  • participant

    object|null
    • id

      string

      The id of the participant

      Example: "375143143408309123"

    • name

      string

      The participant name (maximum 40 characters)

      Example: "Jon Snow"

    • custom_user_identifier

      string|null

      An external user identifier, use the format that suits you best

      Example: "acme:account:1234"

    • custom_fields

      object

      The country and logo custom fields of the participant

      • country

        string|null

        The country of the participant

        Format: ISO 3166-1 alpha-2

        Example: "GB"

      • logo

        object|null

        The participant logo on every available formats.

        Example: {"logo_small":"url_to_small_image","logo_medium":"url_to_medium_image","logo_large":"url_to_large_image"}

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",
    "report_closed": true,
    "opponents": [
        {
            "number": 1,
            "position": 1,
            "result": "win",
            "rank": 3,
            "forfeit": false,
            "score": 15,
            "participant": {
                "id": "375143143408309123",
                "name": "Jon Snow",
                "custom_user_identifier": "acme:account:1234",
                "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"

• report_closed

  boolean

  Wathever if the match report is closed

  Example: true

• opponents

  array[object]
  • number

    integer

    The match opponent number (a relative identifier within a match)

    Example: 1

  • position

    integer

    The match opponent position (calculate by internal processes)

    Example: 1

  • result

    string|null

    The match result of the opponent

    Possible values: win, draw, loss

  • rank

    integer|null

    The match rank of the opponent

    Example: 3

  • forfeit

    boolean

    Whether the opponent is forfeit

    Example: false

  • score

    integer|null

    The score of the opponent

    Example: 15

  • participant

    object|null
    • id

      string

      The id of the participant

      Example: "375143143408309123"

    • name

      string

      The participant name (maximum 40 characters)

      Example: "Jon Snow"

    • custom_user_identifier

      string|null

      An external user identifier, use the format that suits you best

      Example: "acme:account:1234"

    • custom_fields

      object

      The country and logo custom fields of the participant

      • country

        string|null

        The country of the participant

        Format: ISO 3166-1 alpha-2

        Example: "GB"

      • logo

        object|null

        The participant logo on every available formats.

        Example: {"logo_small":"url_to_small_image","logo_medium":"url_to_medium_image","logo_large":"url_to_large_image"}

  • properties

    object

    Features of the game played by the opponent.

    Example: {"bans":["druid","cra"]}

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.

  • number

    integer

    The match opponent number (a relative identifier within a match)

    Example: 1

  • position

    integer

    The match opponent position (calculate by internal processes)

    Example: 1

  • result

    string|null

    The match result of the opponent

    Possible values: win, draw, loss

  • rank

    integer|null

    The match rank of the opponent

    Example: 3

  • forfeit

    boolean

    Whether the opponent is forfeit

    Example: false

  • score

    integer|null

    The score of the opponent

    Example: 15

  • properties

    object

    Features of the game played by the opponent.

    Example: {"bans":["druid","cra"]}

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",
    "report_closed": true,
    "opponents": [
        {
            "number": 1,
            "position": 1,
            "result": "win",
            "rank": 3,
            "forfeit": false,
            "score": 15,
            "participant": {
                "id": "375143143408309123",
                "name": "Jon Snow",
                "custom_user_identifier": "acme:account:1234",
                "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"

• report_closed

  boolean

  Wathever if the match report is closed

  Example: true

• opponents

  array[object]
  • number

    integer

    The match opponent number (a relative identifier within a match)

    Example: 1

  • position

    integer

    The match opponent position (calculate by internal processes)

    Example: 1

  • result

    string|null

    The match result of the opponent

    Possible values: win, draw, loss

  • rank

    integer|null

    The match rank of the opponent

    Example: 3

  • forfeit

    boolean

    Whether the opponent is forfeit

    Example: false

  • score

    integer|null

    The score of the opponent

    Example: 15

  • participant

    object|null
    • id

      string

      The id of the participant

      Example: "375143143408309123"

    • name

      string

      The participant name (maximum 40 characters)

      Example: "Jon Snow"

    • custom_user_identifier

      string|null

      An external user identifier, use the format that suits you best

      Example: "acme:account:1234"

    • custom_fields

      object

      The country and logo custom fields of the participant

      • country

        string|null

        The country of the participant

        Format: ISO 3166-1 alpha-2

        Example: "GB"

      • logo

        object|null

        The participant logo on every available formats.

        Example: {"logo_small":"url_to_small_image","logo_medium":"url_to_medium_image","logo_large":"url_to_large_image"}

  • properties

    object

    Features of the game played by the opponent.

    Example: {"bans":["druid","cra"]}