GYP API Documentation

The Recreational Games API provides endpoints for managing matchups between users or groups.

This requires the Server to Server API Integration, you can check how to implement it here.

Basic Concepts

Subtype

• Group vs Group: GROUP_VS_GROUP In this type of matchup users compete in groups, or teams. The total pot is split evenly among the participants of the winning group.

• Free for All: FREE_FOR_ALL In this type of matchup users compete against all other users. The winner takes the totality of the pot. Internally users are still participants of groups, with one individual in each.

Matchup Status

• Open: OPEN Matchup is open and accepting new participants

• Confirmed: CONFIRMED Matchup has enough participants

• Locked: LOCKED Matchup is locked and no longer accepting new participants

• Pending Outcomes: PENDING_OUTCOMES Matchup is waiting for game results to be submitted

• Closed: CLOSED Matchup has been completed with a winner determined

• Closed Tie: CLOSED_TIE Matchup has been completed and resulted in a tie

• Dispute: DISPUTE Matchup outcome is being disputed by participants

• Canceled by Owner: CANCELED_BY_OWNER Matchup was canceled by the user who created it

• Canceled Not Accepted: CANCELED_NOT_ACCEPTED Matchup was canceled because not enough participants joined

• Canceled Through API: CANCELED_THROUGH_API Matchup was canceled programmatically via API call

• Canceled Timeout: CANCELED_TIMEOUT Matchup was canceled due to timeout (exceeded time limit for acceptance or completion)

Get Matchup

Retrieve details about a specific recreational game matchup.

Endpoint:

GET /api/rest/recreational-games/:matchupId

Response:

{
  "matchup": {
    "id": "...", // uuid matchup identifier in Lucra
    "createdByUserId": "...", // uuid user identifier in Lucra
    "gameId": "SOME_ID", // game identifier in Lucra
    "winnerGroupId": "..." // uuid group ideentifier in Lucra. Optional
    "status": "OPEN", // matchup status. See basic concepts section
    "type": "RECREATIONAL_GAME",
    "subtype": "GROUP_VS_GROUP", // "GROUP_VS_GROUP" | "FREE_FOR_ALL". See basic concepts section
    "buyInAmount": 7, // Amount each user has to pay to join (can be 0)
    "isPublic": true, // can be joined by any user 
    "groups": [
      {
        "groupId": "...", // uuid group ideentifier in Lucra
        "name": "Team 1",
        "users": [
          {
            "userId": "...", // uuid user identifier in Lucra
            "reward": {
              "type": "CASH", // "CASH" | "TENANT_REWARD"
              "value": "15", // the cash reward value if type === "CASH", or the reward intent_id if type === "TENANT_REWARD"
              "metadata": "..." // tenant reward metadata
            }
          }
        ]
      }
    ]
  }
}

Cancel Matchup

Cancel an existing recreational game matchup.

Endpoint:

PUT /api/rest/recreational-games/:matchupId/cancel

Payload:

{}

Response:

{
  "cancel": {
    "code": 200,
    "body": "Matchup canceled successfully"
  }
}

Complete Matchup

Complete a recreational game matchup by setting the outcome.

Endpoint:

PUT /api/rest/recreational-games/:matchupId/complete

Payload (with winner):

{
  "outcome": {
    "isTie": false,
    "winningGroupId": "02966cdb..."
  }
}

Payload (tie scenario):

{
  "outcome": {
    "isTie": true // Only valid for 1 team v 1 team scenarios
  }
}

Response:

{
  "matchup": {
    "id": "...", // uuid matchup identifier in Lucra
    "createdByUserId": "...", // uuid user identifier in Lucra
    "gameId": "SOME_ID", // game identifier in Lucra
    "winnerGroupId": "..." // uuid group ideentifier in Lucra
    "status": "CLOSED", // matchup status. See basic concepts section
    "type": "RECREATIONAL_GAME",
    "subtype": "GROUP_VS_GROUP", // "GROUP_VS_GROUP" | "FREE_FOR_ALL". See basic concepts section
    "buyInAmount": 7, // Amount each user has to pay to join (can be 0)
    "isPublic": true, // can be joined by any user 
    "groups": [
      {
        "groupId": "...", // uuid group ideentifier in Lucra
        "name": "Team 1",
        "users": [
          {
            "userId": "...", // uuid user identifier in Lucra
            "reward": {
              "type": "CASH", // "CASH" | "TENANT_REWARD"
              "value": "15", // the cash reward value if type === "CASH", or the reward intent_id if type === "TENANT_REWARD"
              "metadata": "..." // tenant reward metadata
            }
          }
        ]
      }
    ]
  }
}

Webhooks

This requires webhook subscription, you can check how to configure it here

The following webhook events are available for recreational games:

• RecreationalGameCreated - Triggered when a new matchup is created

• RecreationalGameJoined - Triggered when a user joins matchup

• RecreationalGameCanceled - Triggered when a matchup is canceled

• RecreationalGameCompleted - Triggered when a matchup is completed

• RecreationalGameStarted - Triggered when a matchup is started by the owner

Response:

{
  "event": "RecreationalGameCreated", // one of the event types above
  "matchup": {
    "id": "...", // uuid matchup identifier in Lucra
    "createdByUserId": "...", // uuid user identifier in Lucra
    "gameId": "SOME_ID", // game identifier in Lucra
    "winnerGroupId": "..." // uuid group ideentifier in Lucra
    "status": "OPEN", // matchup status. See basic concepts section
    "type": "RECREATIONAL_GAME",
    "subtype": "GROUP_VS_GROUP", // "GROUP_VS_GROUP" | "FREE_FOR_ALL". See basic concepts section
    "buyInAmount": 7, // Amount each user has to pay to join (can be 0)
    "isPublic": true, // can be joined by any user 
    "groups": [
      {
        "groupId": "...", // uuid group ideentifier in Lucra
        "name": "Team 1",
        "users": [
          {
            "userId": "...", // uuid user identifier in Lucra
            "reward": {
              "type": "CASH", // "CASH" | "TENANT_REWARD"
              "value": "15", // the cash reward value if type === "CASH", or the reward intent_id if type === "TENANT_REWARD"
              "metadata": "..." // tenant reward metadata
            }
          }
        ]
      }
    ]
  }
}