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
Responsibilities
| Task | Owner | Description |
|---|---|---|
| Campaign & quest design | Studio + Immutable | Collaborate to define quest structure, reward types, and timing |
| Player onboarding & linking | Immutable | Players link an identifier matched to your backend during onboarding |
| Game login & player tracking | Studio | Use your existing login and backend systems |
| Quest completion submission | Studio | Track quest progress in-game and send completions to Immutable’s Quest API |
| Reward matching & delivery | Immutable | Match identifier to Passport and deliver rewards |
How to Integrate
Define Quests
Get API Access
Submit Quest Completion
Supported Identifiers
Players can link one of these accounts to their Passport. Use this identifier when submitting quest completions.| Account Type | Account ID | Example |
|---|---|---|
telegram | Telegram user ID | 1191097385 |
discord | Discord user ID | 1374611107196440770 |
email | Email address | user@example.com |
metamask | MetaMask wallet address | 0xc257274276a4e539741ca11b590b9447b26a8051 |
passport | Passport wallet address | 0xa9361c0dd68e1c3a69b43f646133fdab8d3859a2 |
epic_games | Epic Games user ID | a26eca91eca340a7a8cadb886e7c1190 |
Quest Types
In-Game Quests
Social Quests
Referral Quests
On-Chain Quests
Leaderboards
Gamify your community with competitive rankings:| Leaderboard | Criteria | Rewards |
|---|---|---|
| All-Time | Total points earned | Founder badges, exclusive items |
| Weekly | Points this week | Featured spotlight, bonus rewards |
| Referral | Friends referred | VIP access, revenue share |
Questing API
The Questing API provides endpoints for recording quest completions, retrieving active quests, and fetching player earnings. Use these endpoints to integrate quest functionality into your game backend.Prerequisites
- Immutable API Key: Create one in Immutable Hub
- Game ID: Provided during onboarding
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 thelogin-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.
Important Notes
API Endpoints
The Questing API provides three main endpoints:- Quest Completions — Record quest completions and trigger rewards (requires authentication)
- Get Live Quests — Retrieve all currently active quests for your game (no authentication required)
- Latest Earnings — Fetch player gem earning history by wallet address (no authentication required)
Best Practices
Follow these best practices to ensure reliable quest completion tracking and optimal integration with the Quest API.Idempotency
Always use thereference field to prevent duplicate quest completions.
Recommended Pattern
Use a unique reference string that combines player identifier, quest ID, and timestamp:
- Prevents accidental duplicate submissions
- Enables safe retries on network failures
- Provides audit trail for debugging
Error Handling
Implement robust error handling with appropriate retry logic. Retry Strategy| Status Code | Action |
|---|---|
200 | Success - quest completion recorded |
409 | Already recorded - treat as success, don’t retry |
400, 401, 403, 404 | Client error - don’t retry, log and investigate |
500, 504 | Server error - retry with exponential backoff |
Logging
Always log quest completion requests for debugging and auditing. What to Log- Log before making the API request
- Log the response status and any errors
- Include the reference ID for correlation
- Don’t log sensitive data (mask account IDs if needed)
- Use structured logging for easier querying
Rate Limiting
The Quest API implements rate limiting to ensure fair usage. Rate Limit Tiers| Tier | Rate Limit |
|---|---|
| Standard | 50 req/sec |
| Enterprise | Custom |
- Global default: 5 requests per second per public IP
- Partner adjusted rate limit: 50 requests per second per API key
- Enterprise: Custom rate limits based on your agreement
- Batch quest completions when possible (if multiple quests complete simultaneously)
- Implement client-side rate limiting to avoid hitting limits
- Use exponential backoff when receiving rate limit errors (typically
429status) - Monitor your API usage in Immutable Hub — see Hub Overview for details
Account ID Validation
Validate account IDs before submitting to ensure correct format. Validation ExamplesAsync Processing
Consider processing quest completions asynchronously to avoid blocking game logic. Queue-Based ApproachTesting
Test your integration thoroughly before going live. Test Scenarios- Successful completion - Verify quest is recorded correctly
- Duplicate submission - Ensure idempotency works with same reference
- Invalid account ID - Verify proper error handling
- Network failures - Test retry logic
- Rate limiting - Verify backoff behavior
- Required quest - Ensure
login-play-gameis triggered on login
- Use Sandbox environment for all testing
- Test with
discord,telegram, ormetamaskaccount types (notemail) - Verify quest completions appear in Immutable Play (Sandbox)
Monitoring
Set up monitoring and alerts for quest completion failures. Key Metrics to Track- Quest completion success rate
- API error rates by status code
- Average response time
- Rate limit hits
- Duplicate completion attempts
- Error rate > 5%
- Response time > 2 seconds
- Rate limit errors detected
FAQ
Do I need to integrate Passport in my game?
Do I need to integrate Passport in my game?
What happens if a player hasn't linked their account yet?
What happens if a player hasn't linked their account yet?
Can I submit quest completions for players who aren't Passport users?
Can I submit quest completions for players who aren't Passport users?
What is the login-play-game quest?
What is the login-play-game quest?
login-play-game quest is a required daily recurring quest that tracks player engagement. You must trigger this quest every time a player logs into your game. It provides valuable data on daily active users and recurring behavior patterns.How do I prevent duplicate quest completions?
How do I prevent duplicate quest completions?
reference field in your quest completion requests. Use a pattern like {accountId}-{externalId}-{timestamp}. If you receive a 409 Conflict response, the quest was already recorded—don’t retry.What account types can I use?
What account types can I use?
telegram, discord, email, metamask, passport, and epic_games. Note that email is not supported in Sandbox—use discord, telegram, or metamask for testing.Important: metamask and other third-party wallets need to be linked by the user either through the Play profile settings or a custom UX built by the studio using the link wallet API/SDK functionality.How do I get my Game ID?
How do I get my Game ID?
What should I do if I get a 409 Conflict error?
What should I do if I get a 409 Conflict error?
409 Conflict means the quest completion was already recorded (likely due to a duplicate reference). Treat this as success—don’t retry the request.How should I handle API errors?
How should I handle API errors?
- 4xx errors (400, 401, 403): Don’t retry—these indicate client errors that need investigation
- 404 Not Found: Don’t retry—see common causes below
- 409 Conflict: Treat as success—quest already recorded
- 429 Rate Limit: Wait for the
Retry-Afterheader duration, then retry - 5xx errors (500, 504): Retry with exponential backoff
What causes 404 Not Found errors?
What causes 404 Not Found errors?
404 Not Found error can occur when:- The quest doesn’t exist (check the
external_idis correct) - The quest has expired (check
valid_fromandvalid_todates) - The request was made to a production endpoint with a sandbox quest ID (or vice versa)
Can I submit quest completions in batches?
Can I submit quest completions in batches?
How do I test my integration?
How do I test my integration?
https://api.sandbox.immutable.com) for testing. Test with discord, telegram, or metamask account types. Verify quest completions appear in Immutable Play (Sandbox).Additionally, studios can:- Visit play.sandbox.immutable.com to see quest and reward status
- Use the Live Quests endpoint (
GET /v1/quests/games/{game_id}/quests) to see the number of quest completions
What is the completion_time field for?
What is the completion_time field for?
completion_time field allows you to specify when the quest was actually completed (in RFC3339 UTC format). This is useful for retroactive attribution or batch processing. If omitted, the API uses the current time.How quickly are rewards delivered?
How quickly are rewards delivered?
Where can I see quest completion data?
Where can I see quest completion data?
What if I need to change quest definitions?
What if I need to change quest definitions?
Is there rate limiting on the Quest API?
Is there rate limiting on the Quest API?
- Standard tier: 50 requests per second per API key
- Global default: 5 requests per second per public IP
- Enterprise: Custom rate limits based on your agreement
429 Too Many Requests response, implement exponential backoff and retry after the duration specified in the Retry-After header.Common causes of 429 errors:- The API key is not being used correctly in the request flow
- Sub-optimal integration where too many requests are made than needed
- Increase in base traffic (which is a great sign for the project)
Can I use the same API key for other Immutable APIs?
Can I use the same API key for other Immutable APIs?
How do I get help or report issues?
How do I get help or report issues?