Group Match API

This is the API used for matching in groups, such as acquaintances or friends, during gameplay.

Before making a matching request, two or more app users must create a group, and the group representative will proceed with the matching request.

Note

Group API can only be used when the Match ID setting for Match Unit / Personnel is set to Team.

Create group¶

This is an API for creating a group to invite members to the same team.

The creator of the request becomes the group leader (room leader).
It cannot be used during personal matching requests.
An entry code for inviting acquaintances is provided upon creation.
When creating, score information can be entered to correspond to the rules of the match ID.

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group
HTTP METHOD	POST
CONTENT-TYPE	application/json

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier that can be checked in the Hive console app center	int	Y
matchId	Identifier for each match created in the Hive console	int	Y

Request body¶

Field Name	Description	Type	Required
playerId	Account identifier	long	Y
point	This is the score to be used for matching. The input range is `0 ~ 999,999,999`. If not provided, it will be treated as `0`.	integer	N
extraData	Additional account information (nickname, level, country, etc.). Up to 256 characters can be entered. It will be included in the matching result.	string	N

Response¶

Field Name	Description	Type
groupCode	The code required to enter the group	string
ownerPlayerId	The account identifier of the group owner (host)	long
memberInfos	Result message	object
matchInfo	Information about the `gameIndex` and `matchId` the group belongs to	object
requstingStatus	Request status information	string

Request sample¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/group' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":1}'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfos": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}

Join Group¶

This is the API used when app users who wish to join a group use the code (groupCode) received from the group leader (room leader) to participate in the group.

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/groups/code/{code}/member
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/groups/code/{code}/member
HTTP METHOD	POST

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier that can be checked in the Hive console app center	int	Y
matchId	Each match identifier created in the Hive console	int	Y
code	The `groupCode` value received in the response of the group creation API	string	Y

Request body¶

Field Name	Description	Type	Required
playerId	Account identifier	long	Y
point	This is the score to be used for matching. The input range is `0 ~ 999,999,999`. If not entered, it will be treated as `0`.	integer	N
extraData	Additional account information (nickname, level, country, etc.). Up to 256 characters can be entered. It will be included in the matching result.	string	N

Response¶

Field Name	Description	Type
groupCode	Code to enter the corresponding group	string
ownerPlayerId	Identifier for the group leader (host) account	long
memberInfos	Result message	object
matchInfo	Information about the `gameIndex` and `matchId` the group belongs to	object
requestingStatus	Request status information	string

Request sample¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/groups/code/0343322/member' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":2}'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        },
        {
            "playerId": 2
        }
    ],
    "requestingStatus": "notRequested"
}

Leave Group¶

This is the API used when you want to leave the group you are currently in. If the group leader (room leader) leaves, one of the remaining members will become the next group leader.

If there are no remaining members, the group will be removed.

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group
HTTP METHOD	DELETE

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier available in the Hive console app center	int	Y
matchId	Identifier for each match created in the Hive console	int	Y
playerId	User ID	long	Y

Response¶

In the case of 200 OK, the Body is empty.

Request sample¶

curl --location --request DELETE 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/2/group' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

Response sample¶

There is no special response content when processed normally.

Group Forced Ejection (Kick-out)¶

This is an API that allows the group leader (room leader) to forcibly expel a specific member.

요청 URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group/members/{targetPlayerId}
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group/members/{targetPlayerId}
HTTP METHOD	DELETE

헤더 매개변수¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier that can be checked in the Hive console app center	int	Y
matchId	Identifier for each match created in the Hive console	int	Y
playerId	User ID	long	Y
targetPlayerId	ID of the member to be forcibly removed	long	Y

Response¶

This is the format of the result data for the group creation API. Only the information of members forcibly removed from the members' information (memberInfos) will be removed.

Field Name	Description	Type
groupCode	Code to enter the corresponding group	string
ownerPlayerId	Identifier for the group leader (host)	long
memberInfos	Result message	object
matchInfo	Information on `gameIndex` and `matchId` the group belongs to	object
requstingStatus	Request status information	string

Request sample¶

curl --location --request DELETE 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/1/group/members/2' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}

Group Information Retrieval (Based on Group Members)¶

This is an API that retrieves information about the group to which the app user belongs at the time of the request. It can be used for various purposes, and it is necessary to periodically check through polling.

Usually used for the following purposes.

Check the list of app users who joined the group
Check the matching results after the matching request

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group
HTTP METHOD	GET

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier that can be found in the Hive console app center	int	Y
matchId	Identifier for each match created in the Hive console	int	Y
playerId	User ID	long	Y

Response¶

Field Name	Description	Type
groupCode	Code to enter the corresponding group	string
ownerPlayerId	Identifier for the group leader's account	long
memberInfos	Result message	object
matchInfo	Information on `gameIndex` and `matchId` of the group	object
requstingStatus	Request status information	string
requestingInfo	Matching request information	object
matchingInfo	Matching progress information	object

Request sample¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/1/group' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

Response sample¶

// 매칭 요청 전
{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}
// 매칭이 성사된 이후 (2:2 팀전)
{
    "groupCode": "3683207",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1,
            "ready": true
        },
        {
            "playerId": 2,
            "ready": true
        }
    ],
    "matchingInfo": {
        "status": "matched",
        "matchingId": "2:1_2024-12-18T06:55:19.91_1",
        "teamInfos": [
            {
                "teamIndex": 0,
                "playerInfos": [
                    {
                        "playerId": 4,
                        "point": 50,
                        "extraData": "bbb"
                    },
                    {
                        "playerId": 3,
                        "extraData": "aaa"
                    }
                ]
            },
            {
                "teamIndex": 1,
                "playerInfos": [
                    {
                        "playerId": 1,
                        "extraData": "extra1"
                    },
                    {
                        "playerId": 2,
                        "point": 250,
                        "extraData": "aaa"
                    }
                ]
            }
        ]
    },
    "requestingStatus": "requested",
    "requestingInfo": {
        "requestTimeUtc": "2024-12-18T06:55:19.17"
    }
}
// 매칭 시간이 초과된 경우(timeout)
{
    "groupCode": "0400606",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1,
            "ready": true
        },
        {
            "playerId": 2,
            "ready": true
        }
    ],
    "matchingInfo": {
        "status": "timeout"
    },
    "requestingStatus": "requested",
    "requestingInfo": {
        "requestTimeUtc": "2024-12-20T06:37:47.99"
    }
}

Group Information Retrieval (by Code)¶

This is an API that checks whether the group exists using the code (groupCode) provided by the group leader (room leader).

요청 URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/groups
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/groups
HTTP METHOD	GET

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier that can be checked in the Hive console app center	int	Y

Query parameters¶

Field Name	Description	Type	Required
code	Group code (`groupCode)`	string	Y

Response¶

Field Name	Description	Type
groupCode	Code required to enter the group	string
ownerPlayerId	Identifier for the group owner (host)	long
matchInfo	Information about the `gameIndex` and `matchId` the group belongs to	object

Request sample¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/groups?code=0343322' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1
}

Member Information Update¶

This is the API used when a member belonging to a group wants to change their information. The information that can be changed is as follows.

Ready status (ready) - The group leader (room leader) is an unused item.\n
Score (point)\n
Additional information (extraData)

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group/memberinfo
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}/group/memberinfo
HTTP METHOD	PATCH
CONTENT-TYPE	application/json

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier that can be checked in the Hive console app center	int	Y
matchId	Each match identifier created in the Hive console	int	Y
playerId	User ID	long	Y

Request body¶

Field Name	Description	Type	Required
ready	Ready state	boolean	Y
point	This is the score to be used for matching. The input range is `0 ~ 999,999,999`. If not entered, it will be treated as `0`.	integer	N
extraData	Additional account information (nickname, level, country, etc.). Up to 256 characters can be entered. It will be included in the matching result.	string	N

Response¶

Field Name	Description	Type
groupCode	Code to enter the corresponding group	string
ownerPlayerId	Account identifier of the group leader	long
memberInfos	Result message	object
matchInfo	Information on `gameIndex` and `matchId` the group belongs to	object
requstingStatus	Request status information	string

Request sample¶

curl --location --request PATCH 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/players/2/group/memberinfo' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"ready":false,"point":0,"extraData":""}'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        }
    ],
    "requestingStatus": "notRequested"
}

Matching request¶

This is the API requested for each group to start matching.

You must create the match corresponding to matchId in advance in the console. (Same as personal matching request)
There must be at least 2 members at the time of the request.
Members who are not the group leader (room leader) must have their 'ready status' (Ready) set to true.
If there is an existing match in progress, it must be organized (deleted) before making a request.
Only the group representative (room leader) can make the request.

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group/request
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group/request
HTTP METHOD	POST
CONTENT-TYPE	application/json

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier that can be checked in the Hive console app center	int	Y
matchId	Identifier for each match created in the Hive console	int	Y

Request body¶

Field Name	Description	Type	Required
playerId	Account Identifier	long	Y

Response¶

Field Name	Description	Type
groupCode	Code to enter the corresponding group	string
ownerPlayerId	Identifier for the group leader (host)	long
memberInfos	Result message	object
matchInfo	Information about `gameIndex` and `matchId` the group belongs to	object
requstingStatus	Request status information	string
requestingInfo	Matching request information	object
matchingInfo	Matching progress information	object

Request sample¶

curl --location 'http://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/group/request' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":1}'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        },
        {
            "playerId": 2,
            "ready": true
        }
    ],
    "matchingInfo": {
        "status": "matchingInProgress"
    },
    "requestingStatus": "requested",
    "requestingInfo": {
        "requestTimeUtc": "2024-12-05T07:35:35.15"
    }
}

Cancel matching request¶

Request URL¶

LIVE URL	https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group/request
SANDBOX URL	https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/group/request
HTTP METHOD	DELETE

Header parameters¶

Field Name	Description	Type	Required
Authorization	Authentication token for API calls (Bearer)	string	Y

Path parameters¶

Field Name	Description	Type	Required
gameIndex	Project identifier that can be checked in the Hive console app center	int	Y
matchId	Each match identifier created in the Hive console	int	Y

Request body¶

Field Name	Description	Type	Required
playerId	Account Identifier	long	Y

Response¶

Field Name	Description	Type
groupCode	Code to enter the group	string
ownerPlayerId	Identifier for the group leader	long
memberInfos	Result message	object
matchInfo	Information on `gameIndex` and `matchId` the group belongs to	object
requstingStatus	Request status information	string

Request sample¶

curl --location --request DELETE 'https://sandbox-api-match.withhive.com/gameindexes/2/matchmakings/1/group/request' --header 'Content-Type: application/json' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' --data '{"playerId":3}'

Response sample¶

{
    "groupCode": "0343322",
    "matchInfo": {
        "gameIndex": 2,
        "matchId": 1
    },
    "ownerPlayerId": 1,
    "memberInfo": [
        {
            "playerId": 1
        },
        {
            "playerId": 2
        }
    ],
    "requestingStatus": "notRequested"
}

Public response¶

This is a description of the fields commonly used in the API responses related to groups.

memberInfos¶

The fields consisting of information about members belonging to the group (including the group leader or room leader) are as follows.

Field Name	Description	Type
playerId	Account Identifier	long
ready	Ready State	boolean
point	Score entered when joining (updating) the group	integer
extraData	Additional information entered when joining (updating) the group	string

matchInfo¶

The fields consisting of gameIndex and matchId information to which the group belongs are as follows.

Field Name	Description	Type
gameIndex	The `Game Index` value of the project registered in the console's `App Center`	integer
matchId	The `Match ID` registered in the console's `Matchmaking`	integer

requestingStatus¶

The values corresponding to the matching request status field are as follows.

notRequested: Matching not requested
requested: Matching requested

requestingInfo¶

This is the matching request information field.

Field Name	Description	Type
requestTimeUtc	Request time based on UTC+0	string

matchingInfo¶

The fields consisting of matching progress information are as follows.

Field Name	Description	Type
status	Matching progress status	string
matchingId	The Id assigned to the matched pairing. Added when the above status is `matched`.	string
privateInfos	(In case of individual matches) Outputs an array of matched app users' information.	array
teamInfos	(In case of team matches) Outputs an array of matched app users' information.	array

matchingInfo → status¶

The values corresponding to the status field in the matching progress information are as follows.

matchingInProgress : Matching in progress
timeout : No match was made within the time limit
matched : Match successful

matchingInfo → privateInfos¶

The fields that make up the personal matching app user information among the matching progress information are as follows. It is in the same data format as matchingInfo → teamInfos → playerInfos.

Field Name	Description	Type
playerId	Account identifier. Needs to be processed as bot if 0	long
point	Score entered when joining (updating) the group	integer
extraData	Additional information entered when joining (updating) the group	string

matchingInfo → teamInfos¶

The fields that make up the team information matched in the group matching of the matching progress information are as follows.

Field Name	Description	Type
teamIndex	Value for distinguishing teams, starting from 0	integer
playerInfos	Information about app users belonging to the team	array

matchingInfo → teamInfos → playerInfos¶

The fields that configure the app user information of the teams matched in the matching progress are as follows.
It is in the same data format as matchingInfo → privateInfos.

Field Name	Description	Type
playerId	Account identifier. Needs to be processed as bot if 0	long
point	Score entered when joining (updating) the group	integer
extraData	Additional information entered when joining (updating) the group	string