Matchmaker
Unity Matchmaker is part of Unity's growing suite of multiplayer services that are designed to help you create and operate multiplayer games no matter what engine you're using.
Download OpenAPI specification:
Create a matchmaking ticket
Start matchmaking by creating a matchmaking ticket. Returns the ticket ID of the ticket created.
Authorizations
ClientAuth
HTTP: ClientAuth
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Request body for "{title}"
Media Type:
application/jsonAn object that holds a dictionary of attributes (number or string), indexed by the attribute name. The attributes are compared against the corresponding filters defined in the matchmaking config and used to segment the ticket population into pools. The default pool is used if a pool isn't provided.
Code samples for "{title}":
Request example
curl -X POST \ -H "impersonated-user-id: <impersonated-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "queueName": "4vs4", "attributes": { "region": "NA", "platform": "PC" }, "players": [ { "id": "6cc5ac8d-dfab-4b50-9ede-c1d026d8dc81", "customData": { "Skill": 123, "Hero": "tank" }, "qosResults": [ { "regionId": "75721794-e9fd-4d8a-9879-aa853ed18885", "packetLoss": 0.8, "latency": 50 }, { "regionId": "1e29bd54-8acc-433a-ae7d-28ae5fc192a1", "packetLoss": 0.5, "latency": 20 } ] } ]}' \ "https://matchmaker.services.api.unity.com/v2/tickets"
Response example
{ "id": "ec362579-7e46-4040-b79d-8ee856137e36"}
Delete a matchmaking ticket
End matchmaking by deleting a matchmaking ticket using its ticket ID. This is called when the user wants to cancel matchmaking.
Authorizations
ClientAuth
HTTP: ClientAuth
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Code samples for "{title}":
Request example
curl -X DELETE \ -H "impersonated-user-id: <impersonated-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://matchmaker.services.api.unity.com/v2/tickets"
Response example
{ "type": "string", "title": "string", "errors": {}, "status": 0, "detail": "string", "instance": "string"}
Gets the status of a ticket match assignment in the matchmaker
Gets the status of a ticket match assignment in the Matchmaker.
Poll this resource until the match assignment is fulfilled. Rate of polling should not be more than once every second.
Poll this resource until the match assignment is fulfilled. Rate of polling should not be more than once every second.
Authorizations
ClientAuth
HTTP: ClientAuth
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Code samples for "{title}":
Request example
curl -X GET \ -H "impersonated-user-id: <impersonated-user-id>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://matchmaker.services.api.unity.com/v2/tickets/status"
Response example
{ "assignmentType": "MultiplayAssignment", "message": "", "status": "Found", "ip": "27.49.78.99", "port": 9000, "matchId": "257c4290-df73-40dd-b08f-b74f34bade21"}
Approve a backfill ticket
Returns the BackfillTicket. Approving a backfill ticket allows all proposed tickets associated with that backfill ticket to be assigned. To get players using backfill, call this periodically.
It is recommended that this be called no faster than once a second while backfill is in progress.
This request should only be performed by the dedicated game server.
It is recommended that this be called no faster than once a second while backfill is in progress.
This request should only be performed by the dedicated game server.
Authorizations
GameServerHostingAuth
HTTP: GameServerHostingAuth
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Code samples for "{title}":
Request example
curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://matchmaker.services.api.unity.com/v2/backfill/{id}/approvals"
Response example
{ "id": "9465e2af-91b9-44f3-b8e9-e7de7d562f97", "created": 1648749745107, "attributes": {}, "properties": { "Data": "eyJtYXRjaFByb3BlcnRpZXMiOnsidGVhbXMiOlt7InRlYW1OYW1lIjoiUmVkIFRlYW0iLCJ0ZWFtSWQiOiI3MmNlYjU4Zi04NTBkLTQ0YTAtYmYzZC04ZDIzMDQ4YTE2ZmMiLCJwbGF5ZXJJZHMiOlsiMmQyYjRiOTktZGJlNy00ODJkLTljZTMtYTk4NTZkMDQ3MGYwIiwiNjc0ZGZiOTktZTMyNS00YWE2LWI5ZjgtZDU2ZDczNDkxM2MxIl19XSwicGxheWVycyI6W3siaWQiOiIyZDJiNGI5OS1kYmU3LTQ4MmQtOWNlMy1hOTg1NmQwNDcwZjAiLCJjdXN0b21EYXRhIjp7fSwicW9zUmVzdWx0cyI6W3sicmVnaW9uSWQiOiI3NTcyMTc5NC1lOWZkLTRkOGEtOTg3OS1hYTg1M2VkMTg4ODUiLCJwYWNrZXRMb3NzIjowLjAxLCJsYXRlbmN5Ijo1MH0seyJyZWdpb25JZCI6ImJkOTg0ZDZmLTM3YTYtNDczZC1hNzY2LTg5NDRhZTQzOTUyNiIsInBhY2tldExvc3MiOjAuMDIsImxhdGVuY3kiOjIwfV19LHsiaWQiOiI2NzRkZmI5OS1lMzI1LTRhYTYtYjlmOC1kNTZkNzM0OTEzYzEiLCJjdXN0b21EYXRhIjp7fSwicW9zUmVzdWx0cyI6W3sicmVnaW9uSWQiOiI3NTcyMTc5NC1lOWZkLTRkOGEtOTg3OS1hYTg1M2VkMTg4ODUiLCJwYWNrZXRMb3NzIjowLCJsYXRlbmN5IjoxNTB9LHsicmVnaW9uSWQiOiJiZDk4NGQ2Zi0zN2E2LTQ3M2QtYTc2Ni04OTQ0YWU0Mzk1MjYiLCJwYWNrZXRMb3NzIjowLjA1LCJsYXRlbmN5IjoxMTB9XX1dLCJyZWdpb24iOiJiZDk4NGQ2Zi0zN2E2LTQ3M2QtYTc2Ni04OTQ0YWU0Mzk1MjYiLCJiYWNrZmlsbFRpY2tldElkIjoiOTQ2NWUyYWYtOTFiOS00NGYzLWI4ZTktZTdkZTdkNTYyZjk3In19" }, "connection": "127.200.20.29:9000"}
Create a backfill ticket
A request allowing the game server to receive new players from the matchmaker.
The request should contain the teams, theirs players and the players information so that the matchmaker can add players to that match.
The request should only be performed by the dedicated game server.
The request should contain the teams, theirs players and the players information so that the matchmaker can add players to that match.
The request should only be performed by the dedicated game server.
Authorizations
GameServerHostingAuth
HTTP: GameServerHostingAuth
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Request body for "{title}"
Media Type:
application/jsonAn object that holds a dictionary of attributes (number or string), indexed by the attribute name. The attributes are compared against the corresponding filters defined in the matchmaking config and used to segment the ticket population into pools. The default pool is used if a pool isn't provided.
The ID of the pool to create the backfill ticket in. Cannot be used if the field is present. The MatchmakingResults in the allocation payload contains the pool ID of the match it was created in. The allocation payload is retrieved by the game server from the payload proxy as described in the Game Server Hosting Documentation.
attributesAn object that will contain the data representing a Backfill Ticket. The information about the backfill ticket properties is stored in the property of that object. Backfill Ticket Properties is serialized in base64 (with padding).
DataThe ID of the match that this backfill ticket is targeting. The match ID is contained in the MatchmakingResults in the allocation payload. The allocation payload is retrieved by the game server from the payload proxy as described in the Game Server Hosting Documentation.
Code samples for "{title}":
Request example
curl -X POST \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "queueName": "4vs4", "attributes": { "region": "NA", "platform": "PC" }, "connection": "27.49.78.99:9000", "properties": { "Data": "eyJtYXRjaFByb3BlcnRpZXMiOnsidGVhbXMiOlt7InRlYW1OYW1lIjoiUmVkIFRlYW0iLCJ0ZWFtSWQiOiI3MmNlYjU4Zi04NTBkLTQ0YTAtYmYzZC04ZDIzMDQ4YTE2ZmMiLCJwbGF5ZXJJZHMiOlsiMmQyYjRiOTktZGJlNy00ODJkLTljZTMtYTk4NTZkMDQ3MGYwIiwiNjc0ZGZiOTktZTMyNS00YWE2LWI5ZjgtZDU2ZDczNDkxM2MxIl19XSwicGxheWVycyI6W3siaWQiOiIyZDJiNGI5OS1kYmU3LTQ4MmQtOWNlMy1hOTg1NmQwNDcwZjAiLCJjdXN0b21EYXRhIjp7fSwicW9zUmVzdWx0cyI6W3sicmVnaW9uSWQiOiI3NTcyMTc5NC1lOWZkLTRkOGEtOTg3OS1hYTg1M2VkMTg4ODUiLCJwYWNrZXRMb3NzIjowLjAxLCJsYXRlbmN5Ijo1MH0seyJyZWdpb25JZCI6ImJkOTg0ZDZmLTM3YTYtNDczZC1hNzY2LTg5NDRhZTQzOTUyNiIsInBhY2tldExvc3MiOjAuMDIsImxhdGVuY3kiOjIwfV19LHsiaWQiOiI2NzRkZmI5OS1lMzI1LTRhYTYtYjlmOC1kNTZkNzM0OTEzYzEiLCJjdXN0b21EYXRhIjp7fSwicW9zUmVzdWx0cyI6W3sicmVnaW9uSWQiOiI3NTcyMTc5NC1lOWZkLTRkOGEtOTg3OS1hYTg1M2VkMTg4ODUiLCJwYWNrZXRMb3NzIjowLCJsYXRlbmN5IjoxNTB9LHsicmVnaW9uSWQiOiJiZDk4NGQ2Zi0zN2E2LTQ3M2QtYTc2Ni04OTQ0YWU0Mzk1MjYiLCJwYWNrZXRMb3NzIjowLjA1LCJsYXRlbmN5IjoxMTB9XX1dLCJyZWdpb24iOiJiZDk4NGQ2Zi0zN2E2LTQ3M2QtYTc2Ni04OTQ0YWU0Mzk1MjYiLCJiYWNrZmlsbFRpY2tldElkIjoiOTQ2NWUyYWYtOTFiOS00NGYzLWI4ZTktZTdkZTdkNTYyZjk3In19" }}' \ "https://matchmaker.services.api.unity.com/v2/backfill"
Response example
{ "id": "string"}
Delete a backfill ticket
When a backfill ticket is deleted, the matchmaker rejects all proposed tickets associated with that backfill ticket.
Rejected tickets return to the tickets pool and can be matched again.
This should be called when backfill ends and the request is only made by the dedicated game server.
Rejected tickets return to the tickets pool and can be matched again.
This should be called when backfill ends and the request is only made by the dedicated game server.
Authorizations
GameServerHostingAuth
HTTP: GameServerHostingAuth
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Code samples for "{title}":
Request example
curl -X DELETE \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://matchmaker.services.api.unity.com/v2/backfill/{id}"
Response example
{ "type": "string", "title": "string", "errors": {}, "status": 0, "detail": "string", "instance": "string"}
Update a backfill ticket
This should be called when the server state changes in order to reflect the current server state, such as when people leave the server or when people join the server without the involvement of the matchmaker.
Updating a backfill ticket will reject all unapproved tickets associated with that backfill ticket. Rejected tickets will return to the pool of tickets queryable by the matchmaker if they were not approved.
The request should only be performed by the dedicated game server.
Updating a backfill ticket will reject all unapproved tickets associated with that backfill ticket. Rejected tickets will return to the pool of tickets queryable by the matchmaker if they were not approved.
The request should only be performed by the dedicated game server.
Authorizations
GameServerHostingAuth
HTTP: GameServerHostingAuth
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Request body for "{title}"
Media Type:
application/jsonAn object that holds a dictionary of attributes (number or string), indexed by the attribute name. The attributes are compared against the corresponding filters defined in the matchmaking config and used to segment the ticket population into pools. The default pool is used if a pool isn't provided.
An object that will contain the data representing a Backfill Ticket. The information about the backfill ticket properties is stored in the property of that object. Backfill Ticket Properties is serialized in base64 (with padding).
DataCode samples for "{title}":
Request example
curl -X PUT \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "id": "9465e2af-91b9-44f3-b8e9-e7de7d562f97", "created": 1648749745107, "attributes": {}, "properties": { "Data": "eyJtYXRjaFByb3BlcnRpZXMiOnsidGVhbXMiOlt7InRlYW1OYW1lIjoiUmVkIFRlYW0iLCJ0ZWFtSWQiOiI3MmNlYjU4Zi04NTBkLTQ0YTAtYmYzZC04ZDIzMDQ4YTE2ZmMiLCJwbGF5ZXJJZHMiOlsiMmQyYjRiOTktZGJlNy00ODJkLTljZTMtYTk4NTZkMDQ3MGYwIiwiNjc0ZGZiOTktZTMyNS00YWE2LWI5ZjgtZDU2ZDczNDkxM2MxIl19XSwicGxheWVycyI6W3siaWQiOiIyZDJiNGI5OS1kYmU3LTQ4MmQtOWNlMy1hOTg1NmQwNDcwZjAiLCJjdXN0b21EYXRhIjp7fSwicW9zUmVzdWx0cyI6W3sicmVnaW9uSWQiOiI3NTcyMTc5NC1lOWZkLTRkOGEtOTg3OS1hYTg1M2VkMTg4ODUiLCJwYWNrZXRMb3NzIjowLjAxLCJsYXRlbmN5Ijo1MH0seyJyZWdpb25JZCI6ImJkOTg0ZDZmLTM3YTYtNDczZC1hNzY2LTg5NDRhZTQzOTUyNiIsInBhY2tldExvc3MiOjAuMDIsImxhdGVuY3kiOjIwfV19LHsiaWQiOiI2NzRkZmI5OS1lMzI1LTRhYTYtYjlmOC1kNTZkNzM0OTEzYzEiLCJjdXN0b21EYXRhIjp7fSwicW9zUmVzdWx0cyI6W3sicmVnaW9uSWQiOiI3NTcyMTc5NC1lOWZkLTRkOGEtOTg3OS1hYTg1M2VkMTg4ODUiLCJwYWNrZXRMb3NzIjowLCJsYXRlbmN5IjoxNTB9LHsicmVnaW9uSWQiOiJiZDk4NGQ2Zi0zN2E2LTQ3M2QtYTc2Ni04OTQ0YWU0Mzk1MjYiLCJwYWNrZXRMb3NzIjowLjA1LCJsYXRlbmN5IjoxMTB9XX1dLCJyZWdpb24iOiJiZDk4NGQ2Zi0zN2E2LTQ3M2QtYTc2Ni04OTQ0YWU0Mzk1MjYiLCJiYWNrZmlsbFRpY2tldElkIjoiOTQ2NWUyYWYtOTFiOS00NGYzLWI4ZTktZTdkZTdkNTYyZjk3In19" }, "connection": "127.200.20.29:9000"}' \ "https://matchmaker.services.api.unity.com/v2/backfill/{id}"
Response example
{ "type": "string", "title": "string", "errors": {}, "status": 0, "detail": "string", "instance": "string"}
Returns the StoredMatchmakingResults
Returns the results of the matchmaking process (e.g. team compositions, queues/pool info, etc).
Authorizations
ClientAuth
HTTP: ClientAuth
HTTP Authorization Scheme: bearer
ServiceAccount
HTTP: ServiceAccount
To get started with authentication, visit the Service Account Authentication section.
HTTP Authorization Scheme: bearer
Code samples for "{title}":
Request example
curl -X GET \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Authorization: Bearer <YOUR_TOKEN>" \ "https://matchmaker.services.api.unity.com/v2/projects/{projectId}/matches/{matchId}/matchmaking-results"
Response example
{ "matchProperties": { "teams": [ { "teamName": "Red Team", "teamId": "14f18a3e-921d-4165-90b6-ada353e186ca", "playerIDs": [ "d8d7bb2f-a524-4e93-a44a-e8bc10d5d8e1" ] }, { "teamName": "Blue Team", "teamId": "5aa8ae3b-d5b6-463a-9795-9bc10210dc86", "playerIDs": [ "a67cf7fe-975b-4fd3-b694-e8b8452cc702" ] } ], "players": [ { "id": "d8d7bb2f-a524-4e93-a44a-e8bc10d5d8e1", "customData": { "Skill": 123, "Hero": "tank" }, "qosResults": [ { "regionId": "75721794-e9fd-4d8a-9879-aa853ed18885", "packetLoss": 0.8, "latency": 50 }, { "regionId": "1e29bd54-8acc-433a-ae7d-28ae5fc192a1", "packetLoss": 0.5, "latency": 20 } ] }, { "id": "d8d7bb2f-a524-4e93-a44a-e8bc10d5d8e1", "customData": { "Skill": 250, "Hero": "healer" }, "qosResults": [ { "regionId": "75721794-e9fd-4d8a-9879-aa853ed18885", "packetLoss": 0.7, "latency": 25 }, { "regionId": "1e29bd54-8acc-433a-ae7d-28ae5fc192a1", "packetLoss": 0.8, "latency": 20 } ] } ], "region": "05083faf-3795-47b8-a0dc-c626089c5ac9", "backfillTicketId": "dc156067-d140-4c5e-b7d4-90ec51c8333f" }, "queueName": "default queue", "poolName": "default pool", "environmentId": "6b83ec25-4073-45c2-ae32-61e7e51ab722", "backfillTicketId": "dc156067-d140-4c5e-b7d4-90ec51c8333f", "matchId": "62bd4ec2-e7ce-4202-93ed-67c3d3148d4f", "poolId": "4badd0c2-5c28-44b3-bfd2-bef5f2153e0e"}