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

> Frequently asked questions covering postback security, reconciliation, payout formats, testing, and the Surveys List API.


# Surveys FAQ

All questions are organised by topic for easier navigation:

* [Screenout Postbacks](#screenout-postbacks)
* [Postback Hash Verification & Security](#postback-hash-verification--security)
* [Postback Technical Details](#postback-technical-details)
* [Validation & Reconciliation Postbacks](#validation--reconciliation-postbacks)
* [Payout Field Format](#payout-field-format)
* [Development & Testing](#development--testing)
* [Surveys List API](#surveys-list-api)
* [Conversion Rate & Decimal Precision](#conversion-rate--decimal-precision)
* [API Success and Error Responses](#api-success-and-error-responses)
* [User Support](#user-support)
* [Supported Translation Languages](#supported-translation-languages)

***

## Screenout Postbacks

**What are screenout rewards?**\
Screenout rewards are small incentives awarded to users who are disqualified during the survey qualification phase. Prime Surveys issues these payouts directly — no action is required on your side.

**When are they triggered?**\
Prime Surveys triggers screenout rewards automatically when it detects churn risk during the qualification flow.

**What is the typical amount?**\
Approximately 5% of the original survey payout — for example, $0.05 on a $1.00 survey.

**Are screenout postbacks sent to my callback URL?**\
Yes. Screenout events generate a postback with a distinct event type, separate from a successful completion.

***

## Postback Hash Verification & Security

**Is postback security supported?**\
Yes. Prime Earn supports URL signature verification using SHA-1 hash validation.

<Warning>
  SHA-1 is supported for legacy compatibility. If your security policy requires a stronger algorithm, contact your account manager to discuss available options.
</Warning>

**How do I construct the hash?**

1. Take the full postback URL, excluding the `hash` parameter.
2. Append your salt value to the end of that URL.
3. Compute the SHA-1 hash of the resulting string.

```js theme={null}
const crypto = require('crypto');
const url = 'https://your-server.com/reward?user=abc&reward=100&tx_id=xyz'; // without &hash=...
const salt = 'your_salt_value';
const hash = crypto.createHash('sha1').update(url + salt).digest('hex');
```

**Where do I find my salt?**\
Your salt is available in the publisher dashboard. If you cannot locate it, contact your account manager.

**Do I need to add `&hash={hash}` to my postback URL in the dashboard?**\
No. Prime Earn appends the `hash` parameter automatically when firing the postback. Do not add it manually to your configured URL.

***

## Postback Technical Details

**What HTTP method is used?**\
All postbacks use `GET`.

**What verification methods are available?**

* **IP whitelisting** — accept requests only from Prime Earn's known IP ranges.
* **Hash verification** — validate the URL signature using the method described [above](#postback-hash-verification--security).

**What IP ranges does Prime Earn use?**

| IPv4            | IPv6                     |
| --------------- | ------------------------ |
| `168.119.57.82` | `2a01:4f8:c17:ec3d::/64` |
| `49.12.33.196`  | `2a01:4f8:c17:1511::/64` |
| `49.13.14.251`  | `2a01:4f8:c17:c73c::/64` |

<Warning>
  Reject any postback request that does not originate from these IPs or fails hash verification to prevent fraudulent reward credits.
</Warning>

**What response codes should I return?**

Return `200` or `201` to acknowledge receipt. Any other status code is treated as a failure and triggers up to **3 retries** (4 total delivery attempts) on the following schedule:

| Attempt | Delay after previous failure |
| ------- | ---------------------------- |
| Retry 1 | 1 minute                     |
| Retry 2 | 5 minutes                    |
| Retry 3 | 60 minutes                   |

**What are the constraints on the `user` and `subid` fields?**

| Field   | Max length                      | Notes                                                            |
| ------- | ------------------------------- | ---------------------------------------------------------------- |
| `user`  | 255 characters                  | —                                                                |
| `subid` | 240 characters (50 recommended) | Letters, numbers, hyphens, and underscores only. Case-sensitive. |

**Can the same `tx_id` appear in multiple postbacks?**\
No. Each `tx_id` is a unique transaction identifier. Prime Earn sends exactly one postback per transaction.

**Is the `survey` parameter included in postbacks?**\
Yes, the `survey` parameter is supported.

**How should I store `type` (integer) fields in my database?**\
Use an unsigned tiny integer (`TINYINT UNSIGNED`).

**What is the purpose of the `hash` parameter?**\
The `hash` parameter is a URL signature used to verify that the postback originated from Prime Earn and has not been tampered with in transit. See [Postback Hash Verification & Security](#postback-hash-verification--security).

***

## Validation & Reconciliation Postbacks

**What triggers a reconciliation postback?**\
A reconciliation postback is sent when a previously credited transaction is reversed — for example, due to detected fraud or a chargeback. These events use `type=4` and carry negative `reward` and `payout` values.

**What is `reconciled_tx_id`?**\
`reconciled_tx_id` is the `tx_id` of the original transaction being reversed. This allows you to look up the original credit in your system.

**Does the reconciliation postback include all parameters?**\
Yes. All standard postback parameters are present. Example:

```
?reward=-0.30&payout=-0.30&type=4&user=abc123&tx_id=new-uuid&reconciled_tx_id=original-uuid
```

**What are the key rules for reconciliation postbacks?**

* Every reconciliation postback carries its own unique `tx_id`, distinct from `reconciled_tx_id`.
* `reconciled_tx_id` is always a 36-character UUID.
* `tx_id` is always unique across all postback types, including reconciliation.
* You only need to store `reconciled_tx_id` if your internal logic requires tracing reversals back to the original transaction.

***

## Payout Field Format

**What is the format of the `payout` field?**\
`payout` is a floating-point decimal with two decimal places (e.g. `12.34`). The typical range is `0.00` to `99.99`, though the system supports values above `99.99`.

**What database column type should I use?**\
Use `DECIMAL(5,2)` to store payout values accurately and avoid floating-point precision loss.

**How are payouts rounded?**\
Payouts are rounded to two decimal places using standard rounding: values of `.005` or higher round up, values below round down. This is standard practice in adtech.

***

## Development & Testing

**Can I create a test environment?**\
Yes. Add a new app in the publisher dashboard and set it to **Test Mode** to test without affecting production traffic.

**What is the difference between Test Mode and Live Mode?**

|                  | Test Mode                                 | Live Mode    |
| ---------------- | ----------------------------------------- | ------------ |
| Survey content   | Dummy surveys                             | Real surveys |
| Postbacks fired  | Yes                                       | Yes          |
| Postbacks stored | No — not persisted in Prime Earn's system | Yes          |
| User traffic     | Isolated — no real users affected         | Real users   |
| Hash included    | Yes                                       | Yes          |

**Can I complete survey URLs manually in Test Mode?**\
Yes. You can open survey URLs directly, complete them, or trigger a screenout. Postbacks are fired but not persisted on Prime Earn's side.

**Is there a standalone mock server?**\
No. Test Mode covers all testing scenarios. Use the **"Test Postback"** button in the publisher dashboard to send a sample postback to your configured callback URL and verify your endpoint.

**Are there IP restrictions on calling the Prime APIs?**\
No. You can call Prime Earn APIs from any IP. Inbound postbacks, however, only originate from the [whitelisted IP ranges](#postback-technical-details).

***

## Surveys List API

**How is the request authenticated?**\
Include your `api_token` in the URL path and pass `app_hash` as a query parameter.

**What formats does the `zip` field accept?**\
`zip` is a string of up to 7 digits.

**Should I use `device` or `user_agent`?**\
`device` is sufficient. Pass one of three PascalCase values: `"Desktop"`, `"Mobile"`, or `"Tablet"`.

**Is the `token` parameter still supported?**\
No. `token` is deprecated. Use `api_token` in the URL path instead.

**What does `user_reward` represent?**\
`user_reward` is the maximum reward a user can earn upon full completion of the survey. It does not include screenout rewards.

***

## Publisher Payout & Reward Calculation

**How is `publisher_payout` sent?**\
`publisher_payout` is always a USD decimal (e.g. `0.02` or `0.50`).

**What is `conversion_rate`?**\
The number of in-app currency units per $1 USD. For example, a `conversion_rate` of `50` means the user earns 50 points per $1.

**How do I calculate the user's reward?**\
Multiply `publisher_payout` by `conversion_rate`:

```
0.50 × 50 = 25 points
```

The user receives 25 in-app points for a \$0.50 payout at a 50× conversion rate.

***

## Conversion Rate & Decimal Precision

**Can we switch to a 2-decimal conversion rate?**\
Yes, and we recommend it. A 2-decimal format simplifies payout calculations and produces cleaner values for display in your UI.

**Who needs to make the change?**\
You (the publisher) need to make the change on your side, because the conversion logic — turning the USD `payout` into in-app currency — runs in your system. Updating the dashboard setting alone, without also adjusting your reward calculation, will produce incorrect values.

**Why can't Prime make the change directly?**\
Prime only sends the raw `payout` in USD. The conversion to in-app currency is applied entirely on your side, so the logic update must come from you.

**Recommended steps:**

1. Update the conversion rate and decimal precision setting in your dashboard.
2. In parallel, update your reward calculation logic to match the new format.
3. Run end-to-end tests to confirm the correct reward is credited to users.

***

## API Success and Error Responses

### Successful Response

Every API call returns `HTTP 200 OK`. On success, the response body follows this structure:

```json theme={null}
{
  "status": "success",
  "uh": "abc123",
  "count": 4,
  "surveys": ["..."],
  "message": null
}
```

> The `surveys` array above is truncated for brevity. A real response contains full survey objects.

| Field     | Type           | Notes                                                                                                                               |
| --------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `status`  | string         | Always `"success"`. See note below.                                                                                                 |
| `uh`      | string         | User hash identifier.                                                                                                               |
| `count`   | integer        | Number of available surveys.                                                                                                        |
| `surveys` | array          | List of survey objects.                                                                                                             |
| `message` | string \| null | `null` when the user has normal access. A non-null value explains why access is restricted (e.g. fraud risk, profile restrictions). |

<Note>
  In practice, `status` is always `"success"` — even when the user cannot access surveys. Errors are communicated through the `message` or `code` fields, not through a different `status` value.
</Note>

### Error Responses

**Unauthorised or malformed request** — returns `HTTP 200` with:

```json theme={null}
{
  "code": 1
}
```

This occurs when required parameters are missing or invalid — for example, an incorrect token or missing app ID.

**User not eligible for surveys** — returns `HTTP 200` with:

```json theme={null}
{
  "status": "success",
  "message": "User does not meet eligibility criteria."
}
```

The request itself is valid, but the user is restricted based on internal rules such as fraud scoring or quota limits.

***

## User Support

**How can users get help after completing a survey?**

Provide users with these two personalised links, substituting your real `app-key` and the user's `external_user_id`:

| Link                    | URL                                                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| Localised FAQ           | `https://monetize.primeearn.com/support?app={app-key}&uuid={external_user_id}`               |
| Submit a support ticket | `https://monetize.primeearn.com/support-create-ticket?app={app-key}&uuid={external_user_id}` |

The FAQ link automatically selects the language based on the user's device locale.

<Warning>
  These links are intended exclusively for survey-related support. Communicate this clearly to users in your app or help centre to avoid confusion.
</Warning>

**What is the lifecycle from survey submission to a potential reversal?**

1. The user submits a survey response.
2. Prime Earn immediately fires a completion postback (`type=1`).
3. If the response is later flagged — due to fraud, poor quality, or rejection by the survey provider — Prime Earn fires a reconciliation postback (`type=4`).

**Is the completion postback delayed pending review?**\
No. The `type=1` postback is fired immediately after the user submits. It is not held while the response is validated upstream.

**Should I credit the user immediately on receiving a `type=1` postback?**\
Yes. Credit the user as soon as you receive the completion postback. If a `type=4` reversal arrives later, you can choose to claw back the reward or absorb it — this is your business decision.

**What do publishers typically do when they receive a `type=4` reconciliation postback?**\
Practices vary. Some publishers reverse the reward from the user's balance; others absorb the loss as part of their margin. There is no single standard across the industry.

***

## Supported Translation Languages

Prime Surveys automatically localises the survey experience for users in the following languages:

Arabic · Chinese (Simplified) · Czech · Danish · Dutch · Filipino · Finnish · French · German · Indonesian · Italian · Japanese · Korean · Malay · Norwegian · Polish · Portuguese · Romanian · Spanish · Swedish · Thai · Turkish · Vietnamese