Guides
Start typing to search…

Private Leagues Operations

Private leagues allow users to create custom prediction competitions with friends, colleagues, or other users, complete with scoring, rankings, invitations, and moderation capabilities through the sdk.privateLeagues()

Interface Definition

interface IPrivateLeagues

Package: com.fansunitedmedia.sdk.client.privateLeagues

Core Operations

League Management

Create League

suspend fun create(createPrivateLeague: CreatePrivateLeagueRequest): PrivateLeague?

Creates a new private league with the specified configuration.

Parameters:

  • createPrivateLeague: Configuration for the new league

Returns: The created PrivateLeague object or null if creation failed

Update League

suspend fun update(leagueId: String, updatePrivateLeagueRequest: UpdatePrivateLeagueRequest): PrivateLeague?

Updates an existing league's settings.

Parameters:

  • leagueId: Unique identifier of the league to update
  • updatePrivateLeagueRequest: Updated league configuration

Returns: The updated PrivateLeague object or null if update failed

Update Template

suspend fun updateTemplate(leagueId: String, newTemplateId: String, pastTemplateName: String): PrivateLeague?

Updates the league's scoring template. If the new template ID exists in past templates, it will be removed from past templates. League administrators cannot set the same past template names for different past templates.

Parameters:

  • leagueId: Unique identifier of the league
  • newTemplateId: ID of the new template to apply
  • pastTemplateName: Name for the current template when moved to past templates

Returns: The updated PrivateLeague object or null if update failed

Delete League

suspend fun delete(leagueId: String): Boolean?

Permanently deletes a private league.

Parameters:

  • leagueId: Unique identifier of the league to delete

Returns: true if deletion was successful, false otherwise, or null if operation failed

League Retrieval

Get My Leagues

suspend fun getMyLeagues(myLeaguesFilters: MyLeaguesFilters? = null): SimpleResponse<List<PrivateLeague>>?

Retrieves all private leagues (without member details) that the current user is part of.

Parameters:

  • myLeaguesFilters: Optional filters to apply:
    • type: Filter by league type (PRIVATE or ONE_VS_ONE)
    • userRole: Filter by user's role (MEMBER or ADMINISTRATOR)

Returns: A SimpleResponse containing a list of PrivateLeague objects

Get League by ID

suspend fun getById(leagueId: String, disableCache: Boolean? = null): PrivateLeague?

Retrieves detailed information about a specific league.

Parameters:

  • leagueId: Unique identifier of the league
  • disableCache: Optional flag to bypass cache and fetch fresh data

Returns: The PrivateLeague object or null if not found

Get My League Standings

suspend fun getMyLeaguesStandings(filters: PrivateLeagueFilters? = null): PagedResponse<List<LeagueUserRankingModel>>?

Retrieves the user's results (points and position) across all leagues they're a member of.

Parameters:

  • filters: Optional pagination and filtering options:
    • limit: Number of items per page
    • page: Page number
    • leagueId: Filter by specific league
    • templateId: Filter by specific template
    • sortOrder: Sort order (ASC or DESC)

Returns: A paginated response containing LeagueUserRankingModel objects

Predictions

Get Predictions

suspend fun getPredictions(leagueId: String, filters: LeaguePredictionFilters? = null, disableCache: Boolean? = null): PagedResponse<List<LeaguePrediction>>?

Retrieves the user's own predictions for a specific league.

Parameters:

  • leagueId: Unique identifier of the league
  • filters: Optional filtering options:
    • limit: Number of items per page (maximum 20)
    • page: Page number
    • profileIds: List of profile IDs to filter predictions
  • disableCache: Optional flag to bypass cache

Returns: A paginated response containing LeaguePrediction objects

Member Management

Invite Users

suspend fun invite(privateLeagueId: String, profiles: List<String>): List<String>?

Invites other users to join a league.

Parameters:

  • privateLeagueId: Unique identifier of the league
  • profiles: List of profile IDs to invite (maximum 100 members at once)

Returns: List of successfully invited profile IDs or null if operation failed

Delete Invitations

suspend fun deleteInvitation(privateLeagueId: String, profiles: List<String>): Boolean?

Removes pending invitations for specified users.

Parameters:

  • privateLeagueId: Unique identifier of the league
  • profiles: List of profile IDs whose invitations should be deleted

Returns: true if successful, false otherwise, or null if operation failed

Accept Invitation

suspend fun accept(privateLeagueId: String): Invitation?

Accepts an invitation to join a league.

Parameters:

  • privateLeagueId: Unique identifier of the league

Returns: The Invitation object or null if operation failed

Reject Invitation

suspend fun reject(privateLeagueId: String): Invitation?

Rejects an invitation to join a league.

Parameters:

  • privateLeagueId: Unique identifier of the league

Returns: The Invitation object or null if operation failed

Join by Invitation Code

suspend fun join(invitationCode: String): Invitation?

Joins a league using an invitation code.

Parameters:

  • invitationCode: The invitation code for the league

Returns: The Invitation object or null if operation failed

Leave League

suspend fun leave(privateLeagueId: String): List<String>?

Leaves a league.

Parameters:

  • privateLeagueId: Unique identifier of the league

Returns: List of remaining member profile IDs or null if operation failed

Get Invitations

suspend fun getInvitations(filters: InvitationFilters? = null, disableCache: Boolean? = null): CursorResponse<List<PrivateLeague>>?

Retrieves all leagues the user has been invited to.

Parameters:

  • filters: Optional filtering options:
    • limit: Number of items per page
    • startAfter: ID for cursor-based pagination
    • type: Filter by league type
  • disableCache: Optional flag to bypass cache

Returns: A cursor-based paginated response containing PrivateLeague objects

User Moderation

Ban Users

suspend fun banUsers(privateLeagueId: String, profiles: List<String>): List<String>?

Bans users from a league.

Parameters:

  • privateLeagueId: Unique identifier of the league
  • profiles: List of profile IDs to ban (maximum 100 members at once)

Returns: List of successfully banned profile IDs or null if operation failed

Unban Users

suspend fun unbanUsers(privateLeagueId: String, profiles: List<String>): List<String>?

Removes bans from users in a league.

Parameters:

  • privateLeagueId: Unique identifier of the league
  • profiles: List of profile IDs to unban (maximum 100 members at once)

Returns: List of successfully unbanned profile IDs or null if operation failed

Content Moderation

Moderate Post

suspend fun moderatePost(postId: String, moderationReason: String): DiscussionComment?

Moderates a post from a private league's discussion with a specified reason.

Parameters:

  • postId: Unique identifier of the post to moderate
  • moderationReason: Reason for moderation

Returns: The moderated DiscussionComment object or null if operation failed

Get Reported Posts

suspend fun getReportedPosts(leagueId: String, filters: ReportedPostsFilters? = null): DiscussionResponse<List<DiscussionComment>>?

Retrieves all reported posts in a specific league.

Parameters:

  • leagueId: Unique identifier of the league
  • filters: Optional filtering options:
    • limit: Number of items per page
    • startAfter: ID for cursor-based pagination
    • reportsCount: Minimum number of reports required

Returns: A discussion response containing reported DiscussionComment objects

Data Models

PrivateLeague

Core league entity containing:

  • id: Unique identifier
  • name: League name
  • description: League description
  • type: League type (PRIVATE or ONE_VS_ONE)
  • invitationCode: Code for joining the league
  • templateId: Scoring template ID
  • members: List of member profile IDs
  • administrators: List of administrator profile IDs
  • banned: List of banned profile IDs
  • invites: List of pending invitation profile IDs
  • pinnedPosts: List of pinned post IDs
  • scoringStartsAt: Date when scoring begins
  • usersCanInviteUsers: Whether members can invite others
  • membersCount: Total number of members
  • templateModel: Associated leaderboard template
  • pastTemplates: Historical templates

CreatePrivateLeagueRequest

Request model for creating leagues:

  • name: League name (required)
  • description: League description (required)
  • type: League type (required)
  • templateId: Scoring template ID (required)
  • invitationCode: Custom invitation code (optional)
  • usersCanInviteUsers: Member invitation permissions (default: false)
  • administrators: Additional administrators (optional)
  • scoringStartsAt: Scoring start date (optional)

UpdatePrivateLeagueRequest

Request model for updating leagues:

  • name: Updated league name
  • description: Updated description
  • invitationCode: Updated invitation code
  • templateId: Updated template ID
  • usersCanInviteUsers: Updated invitation permissions
  • administrators: Updated administrator list
  • scoringStartsAt: Updated scoring start date
  • pinnedPosts: Updated pinned posts (maximum 3)

Enums

PrivateLeagueType

  • PRIVATE: Standard private league
  • ONE_VS_ONE: Head-to-head challenge league

UserRole

  • MEMBER: Regular league member
  • ADMINISTRATOR: League administrator with management privileges

Usage Examples

Creating a Private League

val createRequest = CreatePrivateLeagueRequest(
    name = "My Premier League Predictions",
    description = "Predict Premier League matches with friends",
    type = PrivateLeagueType.PRIVATE,
    templateId = "premier-league-template-id",
    usersCanInviteUsers = true,
    scoringStartsAt = "2024-08-01"
)

val league = privateLeagues.create(createRequest)

Inviting Users

val invitedProfiles = privateLeagues.invite(
    privateLeagueId = "league-id",
    profiles = listOf("user1-id", "user2-id", "user3-id")
)

Getting League Standings

val filters = PrivateLeagueFilters(
    limit = 20,
    page = 1,
    leagueId = "specific-league-id"
)

val standings = privateLeagues.getMyLeaguesStandings(filters)

Error Handling

All methods return nullable types, indicating that operations may fail. Always check for null returns and handle them appropriately in your application logic.

Rate Limits and Constraints

  • Maximum 100 members can be invited/banned at once
  • Maximum 20 predictions per page when retrieving predictions
  • Maximum 3 pinned posts per league
  • Invitation codes must be unique across the platform

Updated 21 days ago