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 FAQ

All questions are organised by topic for easier navigation:

​
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.05ona0.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. PrimeEarn 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?
  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.
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. PrimeEarn 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 PrimeEarn’s known IP ranges.
  • Hash verification — validate the URL signature using the method described above.
What IP ranges does PrimeEarn use?
IPv4IPv6
168.119.57.822a01:4f8:c17:ec3d::/64
49.12.33.1962a01:4f8:c17:1511::/64
49.13.14.2512a01: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:
AttemptDelay after previous failure
Retry 11 minute
Retry 25 minutes
Retry 360 minutes
What are the constraints on the user and subid fields?
FieldMax lengthNotes
user255 characters—
subid240 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. PrimeEarn 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 PrimeEarn 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.

​
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 ModeLive Mode
Survey contentDummy surveysReal surveys
Postbacks firedYesYes
Postbacks storedNo — not persisted in PrimeEarn’s systemYes
User trafficIsolated — no real users affectedReal users
Hash includedYesYes
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 PrimeEarn’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 PrimeEarn 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.

​
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: 
{
  "status": "success",
  "uh": "abc123",
  "count": 4,
  "surveys": ["..."],
  "message": null
}
The surveys array above is truncated for brevity. A real response contains full survey objects.
FieldTypeNotes
statusstringAlways "success". See note below.
uhstringUser hash identifier.
countintegerNumber of available surveys.
surveysarrayList of survey objects.
messagestring | nullnull 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:
LinkURL
Localised FAQhttps://monetize.primeearn.com/support?app={app-key}&uuid={external_user_id}
Submit a support tickethttps://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?
  1. The user submits a survey response.
  2. PrimeEarn 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 — PrimeEarn 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