> ## 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

> Programmatically fetch and display available surveys for your users using the Prime Earn Surveys API. Full reference for request parameters, the example flow, and webhook callbacks.


# 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](./iframe), the API gives you full control over how surveys are displayed to your users.

<Info>
  **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](./iframe).
</Info>

***

## 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**.

<Danger>
  **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.
</Danger>

***

## Quick Start

```
https://partners.primeearn.com/{API_TOKEN}/api/surveys?output=API&app={APP_KEY}&external_user_id={USER_ID}&ip={USER_IP}&user_agent={USER_AGENT}
```

Replace the placeholders:

| Placeholder    | Description                                  |
| -------------- | -------------------------------------------- |
| `{API_TOKEN}`  | Your API token (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/{API_TOKEN}/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

```http theme={null}
GET https://partners.primeearn.com/{API_TOKEN}/api/surveys
```

Returns a list of available surveys for the given user.

### Required Parameters

<ParamField query="output" type="string" required>
  Must always be set to `"API"`.
</ParamField>

<ParamField query="app" type="string" required>
  Your unique App Key, available in the publisher dashboard.
</ParamField>

<ParamField query="external_user_id" type="string" required>
  A stable, unique identifier for the end user within your system. Used for deduplication and reward attribution.
</ParamField>

<ParamField query="ip" type="string" required>
  IP address of the user loading the survey list. Used for geo-targeting.
</ParamField>

<ParamField query="user_agent" type="string">
  User-Agent string of the user's browser or device. Required unless `device` is provided instead.
</ParamField>

<ParamField query="device" type="string">
  Fallback when `user_agent` is unavailable. Accepted values: `Desktop`, `Mobile`. Provide either `user_agent` **or** `device` — not both.
</ParamField>

<Warning>
  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.
</Warning>

### Optional Parameters

<ParamField query="limit" type="integer">
  Maximum number of surveys to return. Must be between `1` and `50`. Defaults to the platform maximum if omitted.
</ParamField>

<ParamField query="age" type="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.
</ParamField>

<ParamField query="birthday" type="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.
</ParamField>

<ParamField query="gender" type="string">
  Gender of the end user. Accepted values: `m` (Male), `f` (Female). When passed, users skip the gender onboarding question in surveys.
</ParamField>

<ParamField query="zip" type="string">
  Postal / ZIP code of the end user. Used for geo-targeted survey matching. When passed, users skip the location onboarding question in surveys.
</ParamField>

<ParamField query="maid" type="string">
  Mobile Advertising ID — IDFA on iOS or GAID on Android. If available, this **must** be provided; it significantly improves our product's performance.
</ParamField>

<ParamField query="locale" type="string">
  Interface language. Pass `en` or `en-US` to set the wall language to English. Currently only English is supported.
</ParamField>

<ParamField query="source" type="integer">
  Numeric traffic source identifier. Use the ID from the lookup table below to indicate how the user arrived in your app.
</ParamField>

<ParamField query="network" type="integer">
  Numeric network identifier. Use the ID from the lookup table below to indicate the specific ad network or channel.
</ParamField>

<ParamField query="placement" type="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.
</ParamField>

**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.

| ID | Network                  | Source type     |
| -- | ------------------------ | --------------- |
| 1  | Google                   | Paid UA         |
| 2  | Facebook                 | Paid UA         |
| 3  | Instagram                | Paid UA         |
| 4  | Organic Google           | Organic         |
| 5  | Unknown                  | Other           |
| 6  | Other                    | Other           |
| 7  | Referral / Tell a friend | Organic         |
| 8  | Apple Search Ads         | Paid UA         |
| 9  | TikTok Ads               | Paid UA         |
| 10 | Bidease                  | Paid UA         |
| 11 | Mintegral                | Paid UA         |
| 12 | AppLovin                 | Paid UA         |
| 13 | iOS organic              | Organic         |
| 14 | IronSource / Unity Ads   | Paid UA         |
| 15 | Moloco                   | Paid UA         |
| 16 | Liftoff                  | Paid UA         |
| 17 | Vungle                   | Paid UA         |
| 18 | Email                    | Organic / Owned |
| 19 | Push notification        | Organic / Owned |

<Tip>
  **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.
</Tip>

***

## 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.

<Info>
  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.
</Info>