Documentation Index Fetch the complete documentation index at: https://docs.primeearn.com/llms.txt
Use this file to discover all available pages before exploring further.
Rewarded Offers API Version 1.0 — first release of the Partner Offers API.
The Rewarded Offers API enables you, as an authorised publisher, to programmatically fetch available and active rewarded offers — including mobile games and other app categories — and render them inside your own application or website.
Unlike the IFrame Integration , the API gives you full control over the presentation layer while PrimeEarn handles offer sourcing, reward logic, and attribution.
Who is this guide for? This document is intended for developers at partner publisher companies who wish to build a custom UI on top of our offer inventory. If you are looking for the no-code solution, refer to the IFrame Integration Guide .Base URL https://partners.primeearn.com
Keep your app token secret. Never expose it in client-side JavaScript, mobile app source code, or public repositories. If your token is compromised, contact your account manager immediately to have it rotated.
Endpoints Method Path Description GET/{app_token}/api/v1/offersList available offers for a user GET/{app_token}/api/v1/offers/activeList active (started) offers for a user GET/{app_token}/api/v1/offers/{hash}Get details for a single offer
Request Parameters All three endpoints share the same parameters. Each endpoint section below only lists parameters that are unique to that endpoint .
Required Parameters Parameter Location Type Description app_tokenPath string Partner API token issued per app. Available in your publisher dashboard. appQuery string App hash identifier for your integration. external_user_idQuery string Your system’s unique identifier for the end user. Used for deduplication and reward attribution. ipQuery string User’s IP address. Required so we can distribute users to geo-relevant campaigns.
Optional Parameters Parameter Type Description maidstring Mobile Advertising ID. Pass the user’s IDFA (iOS) or GAID (Android) in this field. Must be provided if available — it significantly improves campaign match rates and attribution accuracy. birthdaystring Date of birth in YYYY-MM-DD format. Preferred over age — use this whenever you have it. ageinteger User age (0–150). Only use if birthday is not available. genderstring m (Male) or f (Female).zipstring Postal / ZIP code. Used for geo-targeted offer matching. sourcestring Traffic source identifier. This is not supported yet, but it will be available soon.
The more user attributes you provide, the better the offer targeting and match quality. maid must always be passed when available. When you have both birthday and age, only send birthday — it is more precise.
Quick Start curl "https://partners.primeearn.com/{app_token}/api/v1/offers?app={APP_HASH}&external_user_id=user_abc123"
A successful response returns HTTP 200:
GET /offers — List Available Offers Returns all offers currently available for the given user to start.
GET /{app_token}/api/v1/offers
Additional parameter (this endpoint only): Parameter Type Required Description platformstring No Filter offers by platform. Accepted values: ios, android, web.
Response { "data" : [ { "id" : "abc123" , "title" : "My Game" , "icon" : "https://cdn.example.com/icon.png" , "large_image_url" : "https://cdn.example.com/banner.png" , "genre" : "Action" , "sub_genre" : "RPG" , "platforms" : [ "ios" , "android" ], "reward" : 100 , "tracking_url" : "https://track.example.com/abc123" , "ranking" : 5 } ] }
For now, we support image creatives only. large_image_url is available today, and a dedicated video URL will be added in a future version.
List of available offer objects. Display name of the app or game.
URL to a banner or feature image. May be null — always check before rendering.
Top-level category (e.g. Action, Puzzle).
More specific category within genre.
Supported platforms for this offer. Values: ios, android.
Reward amount the user will earn, including any active bonus.
Unique click/tracking URL for this offer and user. Open this URL when the user taps the offer CTA.
Offer rank. Lower numbers indicate higher priority. Use this to sort the offer list in your UI.
GET /offers/active — List Active Offers Returns offers the user has already started (i.e. clicked and installed). Uses the same parameters as /offers — no additional parameters.
GET /{app_token}/api/v1/offers/active
Response { "data" : [ { "id" : "def456" , "title" : "Installed App" , "icon" : "https://cdn.example.com/icon2.png" , "large_image_url" : null , "sub_genre" : "Puzzle" , "platforms" : [ "ios" ], "reward" : 80 , "tracking_url" : "https://track.example.com/def456" , "status" : "installed" , "installation_time" : "2026-05-20T10:30:00Z" , "ranking" : 3 } ] }
For now, we support image creatives only. large_image_url may be null, and a dedicated video URL will be added in a future version.
List of active offer objects. Show Active offer object fields
Display name of the app or game.
URL to a banner or feature image. May be null.
More specific category within genre.
Supported platforms for this offer.
Reward amount the user will earn.
Unique click/tracking URL for this offer and user.
Current status of this offer for the user. Value: installed.
ISO 8601 timestamp of when the user installed the app. null if not yet recorded.
Offer rank for sorting purposes.
GET /offers/ — Get Offer Details Returns full details for a single offer, including instructions and individual reward tasks.
GET /{app_token}/api/v1/offers/{hash}
Additional parameters (this endpoint only): Parameter Location Type Required Description hashPath string Yes Offer hash identifier — the id field returned by the list endpoints.
Response { "data" : { "id" : "abc123" , "app_name" : "My Game" , "platform" : [ "ios" , "android" ], "ranking" : 5 , "genre" : "Action" , "sub_genre" : "RPG" , "icon" : "https://cdn.example.com/icon.png" , "large_image_url" : "https://cdn.example.com/banner.png" , "offer_description" : "Complete level 20 to earn rewards." , "tracking_url" : "https://track.example.com/abc123" , "offer_status" : null , "installation_time" : null , "total_reward" : 120 , "instructions" : { "steps" : [ "Download the app" , "Reach level 20" ], "offer_expiration_time" : 10080 }, "rewards" : [ { "reward_amount" : 120 , "task" : "Reach Level 20" , "type" : "iap" , "reward_expiration_hours" : 168 } ] } }
Full offer details object. Show Offer details fields
Display name of the app or game.
Supported platforms for this offer (e.g. ["ios", "android"]).
Offer rank for sorting purposes.
More specific category within genre.
URL to a banner or feature image. May be null.
Long-form description of the offer and its requirements.
Unique click/tracking URL for this offer and user. Open this URL when the user taps the offer CTA.
Click/install status for this user (e.g. pending, completed). null if the user has not yet interacted with this offer.
ISO 8601 timestamp of when the user clicked or installed the offer. null if not yet recorded.
Total reward the user can earn from this offer, excluding any active bonus.
Completion instructions and expiry details. Ordered list of human-readable steps the user must complete (e.g. ["Download the app", "Reach level 20"]).
Maximum time in minutes from the first click within which all tasks must be completed.
Individual reward tasks for this offer. Human-readable description of the task (e.g. "Reach Level 20").
Points/currency awarded on completion of this task.
Task classification. Value: iap (requires an in-app purchase).
Hours from first click within which this specific task must be completed. null if no per-task deadline applies.
Error Responses All errors return a JSON body with status and message fields.
{ "status" : "error" , "message" : "App not found or token mismatch." }
HTTP Status Meaning 200Success. 400App not found or token mismatch. Check that app_token and app are correct. 500Internal server error. Contact your account manager if this persists.