Skip to main content

​
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. Prime Earn 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. Prime Earn fires a webhook to your server to notify you of the completed survey and the user to reward.

​
Authentication

Your API token is embedded directly in the request URL path. You receive this token during onboarding. It is visible in your publisher dashboard under Settings → API Access.
Keep your API 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.

​
Quick Start

Replace the placeholders: Full example:

​
Endpoint: Get Surveys

Returns a list of available surveys for the given user.

​
Required Parameters

​
string
required
Must always be set to "API".
​
string
required
Your unique App Key, available in the publisher dashboard.
​
string
required
A stable, unique identifier for the end user within your system. Used for deduplication and reward attribution.
​
string
required
IP address of the user loading the survey list. Used for geo-targeting.
​
string
User-Agent string of the user’s browser or device. Required unless device is provided instead.
​
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

​
integer
Maximum number of surveys to return. Must be between 1 and 50. Defaults to the platform maximum if omitted.
​
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.
​
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.
​
string
Gender of the end user. Accepted values: m (Male), f (Female). When passed, users skip the gender onboarding question in surveys.
​
string
Postal / ZIP code of the end user. Used for geo-targeted survey matching. When passed, users skip the location onboarding question in surveys.
​
string
Mobile Advertising ID — IDFA on iOS or GAID on Android. If available, this must be provided; it significantly improves our product’s performance.
​
string
Interface language. Pass en or en-US to set the wall language to English. Currently only English is supported.
​
integer
Numeric traffic source identifier. Use the ID from the lookup table below to indicate how the user arrived in your app.
​
integer
Numeric network identifier. Use the ID from the lookup table below to indicate the specific ad network or channel.
​
string
Describes where in your app the survey wall is placed (e.g. post_level, main_menu). Useful when you embed the wall in multiple locations and want to compare performance per placement.
Source & Network ID Reference Pass the numeric ID as the value for both source and network. Choose the row that best describes how the user arrived in your app.
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, Prime Earn 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.