Game Integration API
Definitions
Game Accounts
AccountLinkResponse
Contains a token used for linking the game account to the Challengermode account.
A token identifying the Challengermode user.
DomainHint
A hint describing which domains a user has been authenticated through.
Optional, ID within the domain (e.g steamId).
GameAccount
A user's game account. Minimal implementation provides data to identify the user in the game.
The in-game name of the user.
Optional link to more information about game account.
Optional link to image used for the game account profile. Ignored if not https.
Optional base-64 encoded image, used for the game account profile. If possible use ProfileImageUrl instead.
Optional game account zoning data following a pre-configured schema. This data can be used for restrictions.
GameAccountReference
Uniquely identifies a user's game account, independent of their login method.
Must be unique and immutable. Can be prefixed to avoid ambiguity between realms or regions.
Rating
A description of an in-game rating and rank. This can be used in place of Challengermode standard ranks.
The numerical rating reflecting the user's skill level. This is the value that will be used to match players on Challengermode.
Indicates whether this rating should be considered as primary and used as fallback when no other suitable rating can be found. Only one rank can be primary. By default, the first reported rank is considered as primary.
If the game groups players into ranks, this property can be used to map to a visual representation of the rank that can be configured on your Challengermode game integration.
A common example may be 'gold', 'silver' etc.
If the game has many different types of ratings, this property can be used to distinguish between them. For example, a common practice is to have different ratings per platform.
This value may be used as a key for configuring how the rating type should be displayed on Challengermode.
Additional properties can be added on a custom format which is configurable on your game integration. This may be used to add things such as tracking, or dislaying data alongside the user's rank.
Optional URI to the user's rating either in-game or online. If provided, it will let the user navigate to see more information about their rating/rank.
Ratings
A user's in-game rating data. This rating data can be used in place of Challengermode ranks for matching player's skill level in competitions.
VerifyGameAccount
Used to verify a game account on Challengermode.
A token used for some verification flows.
Setting this flag will verify this game account even if another game account was used before.
Domain
A domain within which a user has been authenticated and can be uniquely indentified.
- 0 = Unknown
- 1 = OwnDomain
- 2 = Google
- 3 = Microsoft
- 4 = Discord
- 5 = Twitch
- 6 = Facebook
- 7 = Steam
- 8 = FifaGG
- 9 = EA
- 10 = GameCenter
- 11 = GooglePlayGames
- 12 = Ubisoft
- 13 = Krafton
GetGameAccountAction
Return a game account.
The major version of the game-integration API (e.g 1 in the case of game-integration/v1/) that this payload adhere to.
GetGameAccountPayload
VerifyGameAccountAction
Verify a game account and return their internal game account ID.
The major version of the game-integration API (e.g 1 in the case of game-integration/v1/) that this payload adhere to.
VerifyGameAccountPayload
The account ID of this user within the specified Domain, verified on Challengermode. Steam account ids are sent in SteamID64 format.
User
UserReference
Information about the logged in user.
The Challengermode id for the logged in user
Miscellaneous
Platform
- 0 = Unknown
- 1 = Other
- 2 = Browser
- 3 = Windows
- 4 = Ios
- 5 = Android
- 6 = Tesla
- 7 = XboxOne
- 8 = XboxSeriesX
- 9 = Ps4
- 10 = Ps5
- 11 = NintendoSwitch
ActionId
- 0 = VerifyGameAccount
- 1 = GetGameAccount
- 2 = LookupAccountId
- 3 = CreateGameSession
- 4 = GetGameSession
- 5 = StartGameSession
- 6 = CancelGameSession
- 7 = NotifyUser
- 8 = ReceiveEvent
- 9 = SubscribeGameSessions
PublicApiEventId
- 0 = Unknown
- 1 = TournamentReadyWindowOpened
- 2 = MatchmakingNewOffer
- 3 = MatchWalkover
- 4 = MatchGoToGameTimeout
- 5 = MatchSeriesWalkover
ReceiveEvent
The major version of the game-integration API (e.g 1 in the case of game-integration/v1/) that this payload adhere to.
ReceiveEventPayload
The Id of the entity that the event relates too.
The time when the tournament ended.
Game Sessions
Competitor
Metadata for competitors participating in a game.
The team the competitor was placed in. Required when reporting subscribed matches if team results are present
CompetitorResult
Result of an individual competitor that participated in a game.
Competitor result, following configured schema on Challengermode.
GameResult
Results of a game, used to determine scoring based on default or custom scoring functions. Individual objects follow schemas defined through Challengermode.
Custom data stucture for general structured results not linked to players or teams. Custom schema is configured on Challengermode.
If applicable, whether the game is in overtime. This is used for round-robin scoring.
GameSession
Description of a Game, its lobby state, and potential results.
Time the players started playing.
Time when the game finished.
GameSessionState
- 1 = Creating
- 2 = Created
- 3 = Starting
- 4 = Started
- 5 = Finished
- 6 = Cancelled
- 7 = Cancelling
GameTag
Identifies a game, and collects additional optional data for how to join.
Unique, immutable, identifier for the game instance. Used exclusively after game has been created.
Lobby name, if applicable.
Lobby password, if applicable.
LineupResult
Results for a specific lineup.
Team identifier, as provided in CreateGame.
Lineup result, following configured schema on Challengermode.
CancelGameSessionAction
Cancel a game, returning the external model of the created session. If successful return a GameSession with the state Cancelled
The major version of the game-integration API (e.g 1 in the case of game-integration/v1/) that this payload adhere to.
CancelGameSessionPayload
Unique, immutable, identifier for the game instance. Used exclusively after game has been created.
A human-readable description for the cancellation reason of the game.
CancelReason
- 0 = FailedByAdmin
- 1 = GoToGameTimeout
- 2 = FailedByChallengermode
CmContext
IDs that can be used to find data through the Challengermode Public API.
GameId on Challengermode, expected to be used for idempotency.
Tournament ID, if game is part of a tournament.
Cup ID, if game is part of a cup.
CreateGameSessionAction
Create a game session on behalf of Challengermode, returning the external model of the created session.
The major version of the game-integration API (e.g 1 in the case of game-integration/v1/) that this payload adhere to.
CreateGameSessionPayload
Game session ID on Challengermode.
Game settings following configured schema on Challengermode.. These settings are configurable by organisers and can be deserialized and used to customize the game settings.
Competitors grouped by lineup, always provided but can be skipped if not applicable.
The recommended time for the game to start. If the game hasn't started after this time, Challengermode might send a cancel request to the game.
GetGameAction
Return the game associated with an internal game ID, providing results if any are available. This is the GameId that was reported when creating the game.
The major version of the game-integration API (e.g 1 in the case of game-integration/v1/) that this payload adhere to.
GetGameActionPayload
Unique, immutable, identifier for the game instance. Used exclusively after game has been created.
Lineup
Metadata for teams participating in a game.
Team identifier, as provided in CreateGame.
The list of competitor account IDs in the playing lineup of this team.
MatchContext
Gives context about a match.
The ID of the match on Challengermode. Can be used to retrieve additional match context data.
How many games does the match consist of.
The number of the game in the best of series.
SubscribeGameSessionsAction
Description of the GameSession subscription.
The major version of the game-integration API (e.g 1 in the case of game-integration/v1/) that this payload adhere to.
SubscribeGameSessionsPayload
The time when the subscription ends. New matches no longer need to be sent.
General
ErrorCode
Numeric error code used to identify the error.
- 0 = Unknown - Internal server error.
- 401 = Unauthorized - Request is unauthorized.
- 404 = NotFound - Resource not found.
- 408 = RequestTimeout - Request timed out.
- 500 = InternalServiceError - Service unavailable.
- 10001 = MissingApiVersion - API version not specified.
- 10002 = InvalidApiVersion - Invalid API version specified.
- 10003 = InvalidApiName - API name is missing.
- 10004 = AppNotApproved - Operation requires your application to be Approved.
- 10005 = InvalidTimeZoneId - Invalid time zone ID.
- 10006 = AppDeactivated - Application is deactivated.
- 10007 = InvalidGameState - Game state validation failed.
- 10008 = TokenExpired - Token has expired.
- 10009 = BadArguments - One or more of the arguments has wrong format.
- 10010 = FeatureNotEnabled - Feature is not enabled for this game integration.
- 10011 = RequiredParamterNullOrEmpty - A parameter is missing or empty in the request.
- 10012 = ValidationError - Some validation checks failed.
- 10017 = GameAccountAlreadyLinked - Another game account is already linked for this game and user.
- 10018 = TournamentStateDisallowsAction - The tournament state disallows the action to be performed.
- 10019 = TeamSizeNotCorrect - The tournament team size does not match the team passed in.
- 10020 = ActionNotAllowed - The action is not allowed.
- 10022 = TournamentIpRestricted - The tournament is IP restricted and needs to be joined from Challengermode.com.
- 10023 = TournamentRequiresReservation - The tournament is not open for everyone and requires an invitation.
- 10024 = TournamentTierRestricted - The tournament is tier restricted.
- 11000 = OAuthUnsupportedGrantType - An unsupported grant type was used.
- 11001 = OAuthTokenExchangeError - An error occurred during token exchange.
- 11002 = OAuthAssertionMissing - The token exchange request is missing required assertion parameter.
- 11003 = OAuthClientNotFound - Specified OAuth client could not be found.
- 11004 = OAuthAssertionGrantProviderNotAuthorized - Client is not authorized to use assertion grant flow using the specificed provider.
- 11005 = OAuthAssertionValidationFailed - Assertion grant is invalid.
- 11006 = OAuthUserCodeMissing - Usercode argument missing.
- 11007 = OAuthUserCodeWrong - Could not find any session corresponding to the provided user code.
- 11008 = EmailInvalid - The email address is invalid.
- 11009 = EmailClaimed - The email is already used by another user.
- 11010 = CreateUsernameFailed - Challengermode was unable to generate a unique username based on the provided preferred username. Provide either another preferred username, or provide none to let Challengermode generate a unique username.
- 11012 = CountryInvalid - The provided country code was either 1) not a valid country code according to the ISO 3166-1 alpha-2 format, or 2) a country which challengermode doesn't support.
- 11013 = PlayerInOtherTeam - The player is already in another team.
- 12001 = CompetitionStateInvalid - The competition state doesn't allow action.
- 13001 = InvalidTeamSize - Invalid team size.
- 13002 = RestrictionNotMet - One or more team members does not match all the restrictions for this competition.
- 13003 = RegistrationClosed - The current state of the cup does not allow anyone to join.
- 13004 = TooFewTeams - Action requires more teams to join the competition.
- 16000 = NoRunningLadder - This ladder is not open for joining.
- 16010 = AlreadyJoinedLadder - This game account has already joined this ladder.
- 110011 = UserBanned - User is banned.
- 1049006 = GameIntegrationNotConfigured - The game integration is not correctly configured.
- 1049007 = GameAccountNotLinked - No game account is linked for this game and user.
- 1049008 = InvalidGameSettings - Indicates that provided game settings are not compatible with the game's associated game settings json schema configured on Challengermode.
ProblemDetails
Country
ISO 3166-1 alpha-2 country code
Denotes if the country has been blocked.