# Get started with matchmaking

> Install and set up Matchmaker and create your first matching ticket.

Match players together in games using the Multiplayer Services SDK. Enable Matchmaker, create the first matchmaking ticket, and create a hosting provider allocation.

## Configure your hosting

Before enabling Matchmaker, initialize your chosen hosting solution, or a client-hosted solution provided by Unity. Refer to [Connect players](../networking/networking-toc), and the [Distributed Authority Quickstart](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest?subfolder=/manual/learn/distributed-authority-quick-start.html) for details about using these services with Matchmaker.

## Install the Multiplayer Services SDK

Follow the [Install the Multiplayer Services SDK](../install-and-upgrade) documentation to install the Multiplayer Services SDK.

## Set up Matchmaker

You can set up and manage Matchmaker through the [Unity Dashboard](https://cloud.unity.com):

1. In the [Unity Dashboard](https://cloud.unity.com), go to **Development** > **Products**.
2. Select **Matchmaker**.

When you launch Matchmaker for the first time, this adds Matchmaker to the **Shortcuts** section on the sidebar and opens the **Overview** page.

## Create a queue and a pool

The next step in working with Matchmaker is to set up a [queue and pool](./queues-pools.md) to control how Matchmaker groups and matches tickets.

If you use a game hosting provider, you must use [Cloud Code](/cloud-code.md)'s allocation function to return allocation data from the hosting provider. Refer to [Matchmaker hosting providers](./mm-hosting-providers.md) for more information.

To create a queue and pool, follow these steps:

1. Select **Queues** > **Create queue**.
2. Choose a name for the first queue and set the maximum number of players on a matchmaking ticket.
3. Select **Create**.
4. Select the queue you just created, then in the **Pools** tab, select **Create pool**.
   * Choose a name for the pool.
   * Choose the queue that you created in the previous step.
   * Select a **Pool type**.
   * Set the timeout value for a ticket.
     Select **Next**.
5. Select your hosting type:
   * If you're using a hosting provider, select **Hosting via Cloud Code**, then in the dropdown menu, select the Cloud Code **Module Name** that contains the allocation and poll functions for your hosting provider.
   * If you're using a client-hosted solution provided by Unity, select **Client Hosting**.
6. Select **Next**.
7. Specify the rules used to define the matches created when sending ticket to that queue and pool. Select **JSON** and copy/paste the following block of code to create matches of one team with a minimum of one player and a maximum of five players:

```json
{
  "Name": "Test",
  "MatchDefinition": {
    "Teams": [
      {
        "Name": "Main team",
        "TeamCount": {
          "Min": 1,
          "Max": 1
        },
        "PlayerCount": {
          "Min": 1,
          "Max": 5
        }
      }
    ],
    "MatchRules": []
  },
  "BackfillEnabled": false
}
```

8. Select **Create** at the bottom of the page.

Matchmaker is now configured. In the **Matchmaker** section, select **Queues** to check the queue and pool that were created.

> **Important:**
>
> Before using a hosting provider, refer to [Matchmaker hosting providers](./mm-hosting-providers.md) to integrate [Cloud Code modules](/cloud-code/modules/overview.md) to allocate game servers and coordinate matchmaking results.

## Create a matchmaking ticket

Now that the matchmaker is configured, you can create and send a ticket to request a hosting allocation:

### Unity SDK

```cs
using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Unity.Services.Authentication;
using Unity.Services.Core;
using Unity.Services.Multiplayer;
using UnityEngine;

public class MatchmakerExample : MonoBehaviour
{
    ISession m_Session;
    CancellationTokenSource m_MatchmakingCts;

    async void Start()
    {
        await UnityServices.InitializeAsync();
        await AuthenticationService.Instance.SignInAnonymouslyAsync();

        await StartMatchmakingAsync();
    }

    async Task StartMatchmakingAsync()
    {
        m_MatchmakingCts = new CancellationTokenSource();

        var matchOptions = new MatchmakerOptions
        {
            QueueName = "MyQueue",
            // Optional: filters/attributes used by pool rules
            TicketAttributes = new Dictionary<string, object>
            {
                { "gameMode", "ranked" }
            },
            // Optional: per-player custom data used by matchmaking rules
            PlayerProperties = new Dictionary<string, PlayerProperty>
            {
                { "skill", new PlayerProperty("1200") }
            }
        };

        var sessionOptions = new SessionOptions
        {
            MaxPlayers = 5
        }.WithRelayNetwork(); // or .WithDistributedAuthorityNetwork() for Distributed Authority

        try
        {
            m_Session = await MultiplayerService.Instance.MatchmakeSessionAsync(
                matchOptions, sessionOptions, m_MatchmakingCts.Token);

            Debug.Log($"Match found and session joined: {m_Session.Id}");
        }
        catch (SessionException e)
        {
            Debug.LogError($"Matchmaking failed: {e.Message}");
        }
    }

    // Cancel matchmaking
    public void CancelMatchmaking()
    {
        m_MatchmakingCts?.Cancel();
    }
}
```

### CURL

```console Curl
# Fetch anonymous token
curl -X POST -H "ProjectId: <projectId>" https://player-auth.services.api.unity.com/v1/authentication/anonymous

# Call the create ticket endpoint
curl -X POST -H "Authorization: Bearer <TOKEN>" \
-H 'Content-Type: application/json' \
--data-raw '{
    "queueName": "Default",
    "attributes": {},
    "players": [{
        "id": "Player 1",
        "customData": {}
    }]
}' \
'https://matchmaker.services.api.unity.com/v2/tickets'
```

> **Note:**
>
> Player IDs must be different to be matched together.

### REST API

[https://services.docs.unity.com/matchmaker/v2/index.html#tag/Tickets/operation/createTicket](https://services.docs.unity.com/matchmaker/v2/index.html#tag/Tickets/operation/createTicket)