Skip to main content

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.

​
Surveys API

Publisher Integration Guide The Surveys API lets you fetch a live list of available surveys for each user and render them in your own UI. PrimeEarn handles survey sourcing, targeting, and reward logic; you control the presentation. Unlike the IFrame Integration, the API gives you full control over how surveys are displayed to your users.
Who is this guide for? This document is for developers at partner publisher companies who want to build a custom survey UI. If you prefer a no-code solution, see the IFrame Integration Guide.

​
How It Works

  1. Your backend calls the Surveys API for each user.
  2. The API responds with a list of available surveys and a unique Survey URL per survey.
  3. You display the surveys in your own UI.
  4. The user clicks a survey and completes it.
  5. PrimeEarn fires a webhook to your server to notify you of the completed survey and the user to reward.

​
Authentication

Your publisher hash is embedded directly in the request URL path. You receive this hash during onboarding. It is visible in your publisher dashboard under Settings → API Access.
Keep your publisher hash secret. Never expose it in client-side JavaScript, mobile app source code, or public repositories. If your hash is compromised, contact your account manager immediately to have it rotated.

​
Quick Start

https://partners.primeearn.com/{PUBLISHER_HASH}/api/surveys?output=API&app={APP_KEY}&external_user_id={USER_ID}&ip={USER_IP}&user_agent={USER_AGENT}
Replace the placeholders:
PlaceholderDescription
{PUBLISHER_HASH}Your publisher hash (URL path segment)
{APP_KEY}Your unique App Key
{USER_ID}A stable, unique identifier for the end user
{USER_IP}The end user’s IP address
{USER_AGENT}The end user’s User-Agent string
Full example: 
https://partners.primeearn.com/{PUBLISHER_HASH}/api/surveys?output=API&app={APP_KEY}&external_user_id=user-US-1&ip=35.151.72.180&gender=m&zip=32714&birthday=1992-02-19&user_agent=Mozilla%2F5.0%20(Macintosh%3B%20Intel%20Mac%20OS%20X%2010_15_7)%20AppleWebKit%2F537.36%20(KHTML%2C%20like%20Gecko)%20Chrome%2F124.0.0.0%20Safari%2F537.36

​
Endpoint: Get Surveys

GET https://partners.primeearn.com/{PUBLISHER_HASH}/api/surveys
Returns a list of available surveys for the given user.

​
Required Parameters

​
output
string
required
Must always be set to "API".
​
app
string
required
Your unique App Key, available in the publisher dashboard.
​
external_user_id
string
required
A stable, unique identifier for the end user within your system. Used for deduplication and reward attribution.
​
ip
string
required
IP address of the user loading the survey list. Used for geo-targeting.
​
user_agent
string
User-Agent string of the user’s browser or device. Required unless device is provided instead.
​
device
string
Fallback when user_agent is unavailable. Accepted values: Desktop, Mobile. Provide either user_agent or device — not both.
Either user_agent or device must be provided. user_agent is preferred as it gives more accurate targeting. Use device only if you cannot access the User-Agent string.

​
Optional Parameters

​
limit
integer
Maximum number of surveys to return. Must be between 1 and 50. Defaults to the platform maximum if omitted.
​
age
integer
Age of the end user. Range: 0–150. When passed, users skip the age-related onboarding question in surveys. If you have both age and birthday, prefer birthday — it is more precise.
​
birthday
string
Date of birth of the end user in YYYY-MM-DD format (e.g. 1992-02-19). Preferred over age when both are available.
​
gender
string
Gender of the end user. Accepted values: m (Male), f (Female). When passed, users skip the gender onboarding question in surveys.
​
zip
string
Postal / ZIP code of the end user. Used for geo-targeted survey matching. When passed, users skip the location onboarding question in surveys.
​
maid
string
Mobile Advertising ID — IDFA on iOS or GAID on Android. If available, this must be provided; it significantly improves our product’s performance.
Skip onboarding questions: When zip, gender, or age are passed, users skip the related onboarding questions in surveys — significantly improving their experience and survey match rate. Pass all available user attributes.Age vs. birthday: If you have both, prefer birthday — it is more precise and provides better targeting than age alone.

​
Webhook Callback

When a user completes a survey, PrimeEarn fires a server-side webhook to your configured callback URL to notify you which user to reward.
Webhook setup and the full list of callback parameters are covered in your onboarding documentation. Contact your account manager if you need the webhook endpoint configured or updated.