ONEquest Development Guide
ONEquest is a marketing tool that lets developers set up goal-based quests at any time they choose to drive ONE store users to engage with their games. To offer in-game action quests, the developer needs to do development work so that ONEquest can be told whether an in-game action has been completed.
1. Overview
When a quest participant completes a specific in-game action (quest) and claims the reward, the ONEquest server calls the game company's API to verify completion in real time. The game company must build and provide two APIs that follow the specifications in this document.
2. Integration Process
To make reward payouts reliable and keep things easy for users, the integration runs in two phases: ① initial account linking and ② in-game action verification.
Phase 1. Initial account linking (per user)
1
User
Enters their game ID (game_user_id) and taps Link
2
ONEquest
Calls your User Validation API
3
Game Server
Checks that the player exists and returns success
4
ONEquest
If the player is valid, saves the game_user_id and reuses it for every quest in the same quest group
Phase 2. In-game action verification (each time a reward is claimed)
1
User
Finishes the quest and taps Claim Reward, with no ID needed
2
ONEquest
Calls your Quest Verification API with the saved game_user_id
3
Game Server
Looks up the player's progress and returns the result
4
ONEquest
Grants the reward based on the result
3. Prerequisites
3.1 Development Requirements
Protocol
HTTPS recommended (HTTP needs our approval). Use a domain name as the host, not an IP address.
Response time (SLA)
Respond within 500 ms.
Data format
JSON for request and response bodies (Content-Type: application/json).
User ID
Receive game_user_id as a query parameter, whatever the HTTP method. It's the only required parameter.
Endpoint
Use any path and host you like, but the request and response formats must follow this spec.
Redirects
The registered URL must be final. ONEquest doesn't follow 3xx redirects.
3.2 Firewall Allow list IPs
Because the ONEquest server calls the game company's APIs, the game company's server (firewall) must allow inbound access from the ONEquest source IPs below.
Dev (QA)
211.188.207.190
Prod
211.188.201.250
3.3 Console Registration
Developers register their APIs themselves in the Developer Center under ONEconsole > Quest. ONEquest calls the registered URL with only the game_user_id query parameter added.
Quest (in-game action)
One per quest. We recommend putting your own quest ID in the path.
4. game_user_id
Both APIs take a single required user identifier parameter: game_user_id.
Type
String
Format
Standard 36-character UUID (8-4-4-4-12)
Max length
255 characters
Sent as
Query parameter, whatever the HTTP method
Example
13f664fc-3d8a-f011-94e3-e0451a3b66b3
5. User Validation API
When a ONEquest user links their game account for the first time, this API checks whether the game_user_id they entered actually exists on the game server.
5.1 Request
Method
GET (example)
Endpoint (example)
https://{Game_Server_Host}/onequest/users/validate?game_user_id=13f664fc-3d8a-f011-94e3-e0451a3b66b3
Content-Type
application/json
The endpoint path is only an example. Set it up to suit your game service, then register it in ONEconsole. The request and response data formats can't be changed.
Query
game_user_id
String
Y
The player's in-game ID to check (UUID, max 255 characters)
Request Example
5.2 Response
success
Boolean
Y
Whether the user exists (true: exists, false: not found)
joined_at
String
N
When the user joined the game, in ISO 8601 with time zone
Success: valid user
Failure: user does not exist
6. In-Game Action Verification API
When a user completes a specific in-game quest and claims the reward, this API checks in real time whether that user actually completed it. It is called at the URL registered in ONEconsole for each quest.
6.1 Request
Method
GET (example)
Endpoint (example)
https://{Game_Server_Host}/onequest/quests/{quest_id}/verify?game_user_id=13f664fc-3d8a-f011-94e3-e0451a3b66b3
Content-Type
application/json
Path
quest_id
String
N
Your own quest ID. ONEquest calls the registered URL exactly as it is and doesn't read it, so your server uses the URL to tell quest conditions apart (level, tutorial, and so on).
Query
game_user_id
String
Y
The user's in-game ID (UUID), saved during Step 1
Request Example
6.2 Response
Based on the verification result, the response must clearly state either completed (true) or not completed (false).
success
Boolean
Y
Whether the quest was completed (true: completed, false: not completed)
message
String
Y
Result message. Please include the reason when it fails. It's for internal use and isn't shown to players.
Success: quest completed
Failure: quest not completed
Failure: user does not exist
7. Error Handling and Response Codes
If the normal verification logic can't run (for example, during server maintenance), return the appropriate HTTP status code.
200
OK
Handled normally. success in the body says whether the quest was completed.
Completed: reward granted / Not completed: "Conditions not met"
401 / 403
Unauthorized / Forbidden
The request came from an IP that isn't allowed and was blocked.
"Can't check right now." Our ops team is alerted, since the IP may be missing from your allowlist.
500
Internal Server Error
Your server hit an internal error.
"Can't check right now."
503
Service Unavailable
Maintenance or a temporary outage. During maintenance, return 503 right away instead of letting the request time out.
"Game under maintenance."
ONEquest Server Call Policy
Timeout
Connect 1 s / Read 3 s
If exceeded, the check fails ("Can't check right now"). You won't hit this if you meet the 500 ms SLA.
Retries
None (one call)
Each time the player tries again, ONEquest makes a new call. That's why the verify API must be read-only.
Redirects
3xx not followed, so the check fails
The registered URL must be final.
2xx with a non-JSON body or no success
The check fails
This includes an empty body.
Failure isolation
Blocked per game company
If one company's API keeps failing, ONEquest pauses calls to it for a while and tells players it can't check right now. Other companies' quests aren't affected.
8. Implementation Example
Scenario: A user (game_user_id = 13fc-...) completes the "Reach Level 30" quest (game company Quest ID: 1) and claims the reward.
In-game action verification
ONEquest request:
GET /onequest/quests/1/verify?game_user_id=13f664fc-...(Source IP: 211.188.201.250)Game company server logic:
Check that the source IP is on the allowlist → Pass
Look up the user's level in the database → Lv. 32 (condition met)
Game company response:
{"success": true, "message": "Quest Complete"}
9. Integration Checklist
Last updated

