Surveys FAQ

All questions are organised by topic for easier navigation:

Screenout Postbacks
Postback Hash Verification & Security
Postback Technical Details
Validation & Reconciliation Postbacks
Payout Field Format
Development & Testing
Surveys List API
Conversion Rate & Decimal Precision
API Success and Error Responses
User Support
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.

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

How do I construct the hash?

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

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.

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`

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

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.

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.

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:

Update the conversion rate and decimal precision setting in your dashboard.
In parallel, update your reward calculation logic to match the new format.
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:

{
  "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).

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.

Error Responses

Unauthorised or malformed request — returns HTTP 200 with:

{
  "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:

{
  "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.

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

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

The user submits a survey response.
Prime Earn immediately fires a completion postback (type=1).
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

Getting Started

Reference

Surveys FAQ

Surveys FAQ

Screenout Postbacks

Postback Hash Verification & Security

Postback Technical Details

Validation & Reconciliation Postbacks

Payout Field Format

Development & Testing

Surveys List API

Publisher Payout & Reward Calculation

Conversion Rate & Decimal Precision

API Success and Error Responses

Successful Response

Error Responses

User Support

Supported Translation Languages

​Surveys FAQ

​Screenout Postbacks

​Postback Hash Verification & Security

​Postback Technical Details

​Validation & Reconciliation Postbacks

​Payout Field Format

​Development & Testing

​Surveys List API

​Publisher Payout & Reward Calculation

​Conversion Rate & Decimal Precision

​API Success and Error Responses

​Successful Response

​Error Responses

​User Support

​Supported Translation Languages

Surveys FAQ

Screenout Postbacks

Postback Hash Verification & Security

Postback Technical Details

Validation & Reconciliation Postbacks

Payout Field Format

Development & Testing

Surveys List API

Publisher Payout & Reward Calculation

Conversion Rate & Decimal Precision

API Success and Error Responses

Successful Response

Error Responses

User Support

Supported Translation Languages