Skip to main content
Quests keep players engaged throughout your game’s lifecycle. Players complete objectives, earn rewards, and climb leaderboards—whether your game is pre-launch or live.

​
Overview

The Audience Builder Program includes in-game quests hosted on your game’s Audience Builder page in Immutable Play. Players sign up using Immutable Passport (simple social sign-on) to:
  • Access the Immutable Play platform, game quests, and leaderboard competitions
  • Track questing and leaderboard progress
  • Receive rewards
  • Link social accounts to their Immutable Play account
No Passport integration required in-game. Your game doesn’t need to implement Immutable Passport as its login/wallet system or integrate any Immutable chain infrastructure. Simply track player progress using your existing backend and notify Immutable when a quest is completed via a lightweight API call.

​
Responsibilities

TaskOwnerDescription
Campaign & quest designStudio + ImmutableCollaborate to define quest structure, reward types, and timing
Player onboarding & linkingImmutablePlayers link an identifier matched to your backend during onboarding
Game login & player trackingStudioUse your existing login and backend systems
Quest completion submissionStudioTrack quest progress in-game and send completions to Immutable’s Quest API
Reward matching & deliveryImmutableMatch identifier to Passport and deliver rewards

​
How to Integrate

1

Define Quests

Work with Immutable to agree on quests (e.g., “Play 30 arena matches”) and their rewards
2

Get API Access

Create an API key on Immutable Hub and share your Org ID
3

Track Quest Logic

Use your existing backend to monitor when players meet quest criteria
4

Submit Quest Completion

When a quest is completed, send a POST request to the Immutable Quest API with the player’s linked identifier
5

Rewards Delivered

Immutable handles player matching and instantly updates their Play inventory

​
Supported Identifiers

Players can link one of these accounts to their Passport. Use this identifier when submitting quest completions.
Account TypeAccount IDExample
telegramTelegram user ID1191097385
discordDiscord user ID1374611107196440770
emailEmail address[email protected]
metamaskMetaMask wallet address0xc257274276a4e539741ca11b590b9447b26a8051
passportPassport wallet address0xa9361c0dd68e1c3a69b43f646133fdab8d3859a2
epic_gamesEpic Games user IDa26eca91eca340a7a8cadb886e7c1190
Notes on account types:
  • email is not supported in Sandbox. Use another account type for testing.
  • epic_games account linking is not yet supported in Immutable Play. However, quest completions with epic_games will be stored and credited once linking is available—no progress will be lost.

​
Quest Types

In-Game Quests

Track gameplay actions: matches played, levels completed, items collected

Social Quests

Follow on Twitter, join Discord, share content, engage with posts

Referral Quests

Invite friends, reach referral milestones, build your network

On-Chain Quests

Verify blockchain actions: first trade, first mint, collection completion

​
Leaderboards

Gamify your community with competitive rankings:
LeaderboardCriteriaRewards
All-TimeTotal points earnedFounder badges, exclusive items
WeeklyPoints this weekFeatured spotlight, bonus rewards
ReferralFriends referredVIP access, revenue share
Players can spend gems to showcase their username on leaderboards across Immutable Play.

​
Developer Reference

​
Complete Quests

This API endpoint completes a quest. The user is identified by their account type and account ID.
Quest completions are stored for non-Passport users. If the identified user is not yet a registered Immutable Passport user, the quest completion will be stored with a reference to the account type and ID supplied in the request. When the user registers with Immutable Passport and links that account, they will be instantly rewarded and credited for this quest (and any other stored completions). This means user accounts do not need to be current Passport users when making requests.

​
Prerequisites

​
Required Quest: Login and Play Game

As part of the Quest API integration, partners are required to implement the Login and Play Game quest, identified by the login-play-game external_id. This quest is configured as a daily recurring quest and should be triggered every time a player logs in. While triggered on login, it tracks participation on a daily basis, providing valuable insights into player engagement and recurring behavior patterns. 
{
  "external_id": "login-play-game",
  "account_type": "discord",
  "account_id": "901290221440733204"
}

​
Endpoint

POST https://api.immutable.com/quests/v2/games/{game_id}/quest-completions

​
Authentication

HeaderDescription
x-immutable-api-keyRequired. Your Immutable API key
x-api-keyOptional. For rate limiting

​
Request Body

{
  "external_id": "string",
  "account_type": "string",
  "account_id": "string",
  "reference": "string",
  "completion_time": "string"
}
FieldTypeRequiredDescription
external_idstringYesThe quest identifier (e.g., "catch-3-fish", "login-play-game")
account_typestringYes"telegram", "discord", "email", "metamask", "passport", or "epic_games"
account_idstringYesThe player’s linked account ID
referencestringNoIdempotency key to prevent duplicate completions
completion_timestringNoRFC3339 UTC timestamp (e.g., "2026-01-08T12:00:00Z")
We highly recommend using the reference field to ensure the same user cannot complete the same quest twice.

​
Example Request

curl -X POST "https://api.immutable.com/quests/v2/games/{game_id}/quest-completions" \
  -H "Content-Type: application/json" \
  -H "x-immutable-api-key: your-api-key" \
  -d '{
    "external_id": "catch-3-fish",
    "account_type": "discord",
    "account_id": "901290221440733204"
  }'

​
Success Response

Status Code: 200 OK 
{
  "result": {
    "game_id": "4f188ae5-8439-40dd-b6b7-c4626c7badec",
    "external_id": "catch-3-fish",
    "account_type": "discord",
    "account_id": "901290221440733204"
  }
}

​
Error Codes

CodeDescription
200Success
400Bad Request - Invalid request body or parameters
401Unauthorized - Invalid or missing API key
403Forbidden - API key doesn’t have access to this game
404Not Found - Game or quest not found
409Conflict - Duplicate completion (reference already used)
500Internal Server Error
504Gateway Timeout

​
Best Practices

Include a unique reference for each quest completion to prevent duplicate submissions. A good pattern is {playerId}-{questId}-{timestamp}.
This daily recurring quest is required and provides valuable engagement data. Trigger it on every player login.
If the API returns a 409 Conflict, the completion was already recorded—don’t retry. For 5xx errors, implement exponential backoff.
Ensure the account ID format matches the account type before submitting. Discord IDs are numeric strings, Telegram IDs are numeric, and wallet addresses are hex strings starting with 0x.

Get API Access

Create your API key in Immutable Hub

Contact Us

Get help setting up your quest campaign