Supplier integration guide
Add surveys and offers to your website or app, and receive reward updates.
Already have a placement? Iframe setup API setup
Getting started
A placement holds your website, reward settings and postback URL. You need one for either integration.
Create an account
Register, verify your email and wait for supplier approval.
Add a placement
Open Placement → Add Placement. Enter your website, full Base Postback URL, currency and reward settings. Controls depend on your account permissions.
Set up reward delivery
Under Variables Mapping, enter the parameter names your receiver expects. See the postback example. Save and confirm your placement is active, then use its iframe link or API feed.

Reward amounts: supplier commission is your payout in USD. Respondent commission is the member’s reward in your placement currency. Do not apply the currency multiplier twice.
Iframe integration
Copy the embed from your placement and replace {user_id} with your member’s ID. Add it to your page. Use your own placement’s full HTTPS URL, not another supplier’s link.
<iframe
src="https://enlignesurvey.com/iframe?placement_id=YOUR_PLACEMENT_ID&user_id=YOUR_MEMBER_ID"
title="Enligne Survey rewards"
width="100%"
height="700"
style="border: 0">
</iframe>This example uses placeholders. Use the placement token from your dashboard and a stable, URL-encoded member ID—not an email address. Avoid __, which is reserved internally.
New respondents may see a profile or verification step before the wall. Existing respondents continue through the usual offerwall flow. Availability depends on the visitor, active networks and placement settings.
Location, tracking and mobile settings
Open the wall in the visitor’s browser; do not fetch it server-side. Country comes from their IP. Country/IP URL overrides and generic aff_sub pass-through are not supported on the iframe entry URL.
Use a responsive width and enough height for the wall and profile form. The parent page must allow scrolling. Test opening a survey with a real user click; restrictive iframe sandbox settings can block forms, navigation or new tabs.
API feed
Use the API if you want to display surveys and offers in your own interface instead of the iframe.
1. Get your API key
Open API Feed in the dashboard. Select Generate API key if you do not have one, or Copy API key if you do. Choose your placement and use Preview inventory to check the feed without creating clicks.

Do not put it in browser JavaScript, public app code, screenshots or launch URLs. Rotate key invalidates the old key immediately, including legacy feed URLs. Opening or refreshing the page does not rotate it.
2. Request inventory
GET /api/feed/v2 accepts exactly one authentication header: Authorization: Bearer YOUR_API_KEY or X-API-Key: YOUR_API_KEY. Do not send both. Your dashboard login session does not authenticate server-to-server feed requests.
curl --request GET \
'https://enlignesurvey.com/api/feed/v2?placement_id=YOUR_PLACEMENT_ID&type=all&limit=20&offset=0' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Accept: application/json'Use type=survey, type=offer or type=all. The feed returns available stored inventory across all countries.
Request parameters and limits
| Parameter | Values & behavior |
|---|---|
placement_id | Required. An active placement belonging to the supplier whose key you use. Use its copied token or numeric ID. |
type | all (default), survey or offer. Router campaigns are included in survey; router is not a valid filter. |
limit | 1–100 items per request. API default: 50; dashboard builder default: 20. |
offset | 0–10000. Default: 0. Follow meta.next_offset in the response. |
user_id | Optional. A nonempty member ID, up to 255 characters, with no control characters. If omitted, entry URLs contain {userId}. |
No country filter. Use each item’s countries when displaying inventory. Do not send country, country_code, ip or api_key in the query. Unknown or repeated parameters are rejected.
Personalized GRL, MyPinio and Prime surveys are not included in this feed. Final eligibility depends on the respondent’s IP and survey availability at launch.
API response
Open a survey
Use the returned entry_url. If you did not send user_id, replace its literal {userId} with your URL-encoded member ID. If you sent it, the URL is ready and meta.user_id_placeholder is null.
Keep all other tracking parameters. Do not add your API key or use a provider’s direct link.
Load more results
Request meta.next_offset until it is null. meta.count is the current page count, not the inventory total. Deduplicate by item ID because inventory can change between requests.
Full JSON example and field reference
All values below are examples, not live inventory or promised payouts.
{
"status": "Success",
"api_version": "2.0",
"data": [{
"id": "lms:123:4",
"survey_id": "SURVEY-DEMO-123",
"type": "survey",
"category": "survey",
"source": "lms",
"name": "Consumer habits study",
"description": "",
"image_url": null,
"network": "Voqall",
"countries": ["IN", "US"],
"loi": "12",
"ir": "65",
"device_codes": [],
"supplier_payout": "1.20",
"payout_currency": "USD",
"points": "120.00",
"currency": "Coins",
"entry_url": "https://enlignesurvey.com/start_survey?survey_id=SURVEY-DEMO-123&user_id={userId}&placement_id=42&company=voqall"
}],
"meta": {
"count": 1,
"has_more": false,
"next_offset": null,
"pagination_limit_reached": false,
"limit": 20,
"offset": 0,
"filters": {"type": "all"},
"inventory_scope": "all_countries_catalog",
"excluded_personalized_sources": ["grl", "mypinio", "primesurvey"],
"country_filter": false,
"launch_country_source": "respondent_ip",
"user_id_placeholder": "{userId}"
}
}Response fields
| Fields | Meaning |
|---|---|
id, survey_id | Catalogue identity and survey/campaign reference. Keep the returned entry URL instead of reconstructing provider links. |
type, category, source, network | Inventory classification and network. Source is lms or campaign; category can be survey, offer or router. |
name, description, image_url | Display content. Description is plain text and empty for LMS surveys; image may be null. Render text safely, not as trusted HTML. |
countries | Country-code array. ["ALL"] denotes worldwide catalogue targeting. Final launch eligibility still depends on the respondent. |
loi, ir | Survey length and incidence fields, returned as strings when present. Campaign items use null. |
device_codes | String codes: 1 Android, 2 Apple/tablet, 3 web. LMS items return an empty array; do not invent device restrictions from it. |
supplier_payout, payout_currency | Your advertised commission and USD. The amount is a decimal string, not a JSON number; precision may vary. |
points, currency | The member reward and placement currency. Points are a decimal string calculated from placement settings. |
payout_model, minimum_supplier_payout, minimum_points | Optional variable-router fields. When payout_model is variable, display the minimum as a starting value—not a guaranteed fixed reward. Not every router returns these fields. |
At the offset cap, pagination_limit_reached is true and has_more may still be true. Stop when next_offset is null; consider narrowing the type filter.
API errors and retry guidance
{"status":"Failed","error":{"code":"invalid_type","message":"type must be all, survey, or offer."}}| Status | Action |
|---|---|
| 400 | Read error.code: invalid_parameters, invalid_placement, invalid_type, invalid_pagination or invalid_user_id. Correct the request before retrying. |
| 401 | invalid_api_key: verify key, authentication header and active supplier access. |
| 403 / 409 | placement_unavailable: check ownership/status (403) or reward configuration (409). |
| 405 | method_not_allowed: use GET. HEAD is also supported and returns no response body. |
| 429 | rate_limited: wait for Retry-After seconds. Limits are deployment-configurable; do not poll in a tight loop. |
Postbacks
A postback tells your server when to credit or reverse a reward. Enligne Survey sends a GET request to your placement’s Base Postback URL.
1. Set your URL and parameter names
Enter your full reward endpoint, such as https://publisher.example/rewards. Under Variables Mapping, enter the names it expects. For Transaction ID, use tx_id—not {tx_id}. These are parameter names, not macros.

All available mapping fields
| Placement field | Example name | Delivered value |
|---|---|---|
| Respondent ID | user_id | Your attributed member ID. |
| Transaction ID | tx_id | The transaction reference; use it with the placement when reconciling. |
| Survey Status | status | 1 completion; 2 reversal. |
| Supplier Commission | payout | Supplier commission in USD. |
| Respondent Commission | reward | Member reward in the configured placement currency. |
| Campaign / Placement / Supplier ID | campaign / placement / supplier | The relevant campaign, placement and supplier references. |
| Country ISO / IP Address | country / ip | Available respondent country/IP. Treat as personal data. |
| Offer Name / Affiliate Sub | offer_name / aff_sub | Offer name and affiliate reference, where supplied by the integration. Iframe entry does not forward a generic affiliate sub. |
Blank mappings and absent values are omitted. Values are URL-encoded. Existing query parameters on the Base Postback URL are preserved, so do not repeat a mapped name there.
2. Receive a completion
With user_id, tx_id, placement, status, payout and reward mapped, a completion looks like this:
https://publisher.example/rewards?placement=42&user_id=member_demo&status=1&tx_id=demo_transaction_001&payout=1.20&reward=120.00status=1 means completion; status=2 means reversal. Names come from your mappings and amounts here are examples. Use the delivered member reward without multiplying it again.
3. Record and acknowledge the result
- Use a public HTTPS endpoint with a valid certificate and an approved destination hostname. A homepage, login screen or redirect is not a reward receiver.
- Return a direct 2xx only after durable processing, including for an already-processed duplicate. The response body is ignored; redirects are not followed.
- Transport failures, 408, 425, 429 and 5xx responses can be retried within configured limits. Do not assume a fixed retry schedule or exactly-once delivery.
- Keep a transaction ledger scoped to your supplier/placement. Validate the member, status and amounts before changing a balance.
Supplier postbacks do not add a universal HMAC signature or authentication header. Agree receiver authentication with support before enabling credit. Protect and validate any approved shared secret server-side, and redact it from logs. Provider callback signatures do not authenticate supplier postbacks.
Reversals
A reversal uses the same Base Postback URL, with the mapped status value 2. It refers to the original transaction; it is not a new member reward.
https://publisher.example/rewards?placement=42&user_id=member_demo&status=2&tx_id=demo_transaction_001&payout=1.20&reward=120.00| Incoming event | What your system should do |
|---|---|
| First verified completion · 1 | Record and credit once, atomically. |
| Repeated delivery of the current state | Acknowledge the duplicate without another balance change. |
| Verified reversal · 2 | Find the matched saved credit and reverse it once. Store the resulting state and audit trail. |
| Unknown, late or conflicting transaction | Hold for reconciliation rather than guessing. A later verified reconciliation can restore a reversed result; a permanent “seen status” flag alone is insufficient. |
Use the status, not the amount’s sign. A reversal amount can be positive or zero. Reverse the original matched credit once. Supplier status 2 means reversal—not screenout or overquota.
Testing checklist
Start with your own test member and a non-crediting test endpoint. Check the complete journey, not just whether a page opens.
- Confirm access. Verify email and account approval, an active placement, and the expected reward currency.
- Open the wall as a test member. Replace the user placeholder; check profile completion, scrolling and survey launch on mobile and desktop. Do not complete real surveys just to simulate a callback.
- Preview the feed, if used. Check all three type filters, pagination, empty results and a bad-key response. The dashboard preview is read-only; opening an entry link creates a tracked attempt.
- Agree a test with support. A Test Postback is a real request to your URL, not a dry run. Use dedicated test identifiers; the manual test is not automatically retried.
- Exercise your receiver locally. Test a completion, duplicate delivery, reversal, duplicate reversal and an unknown transaction. Reconcile late or conflicting events before changing balances.
- Reconcile records. Match the transaction, placement, member, status and reward with the result and delivery logs. An HTTP success alone does not prove that your member received a credit.
Do not credit from a success page. Wait for your backend to validate and record an authenticated, expected postback.
Troubleshooting
Use the exact error and transaction reference. Avoid sharing API keys, postback secrets, respondent emails or IP addresses in screenshots.
I cannot log in or my placement is not authorized
Verify the account email and check whether supplier approval is pending. The supplier and placement must both be active. Copy the embed from the correct placement and replace the user placeholder; contact support if the status is unclear.
The API returns 401 or 403
For 401, check the current key and use only one authentication header. A rotated key stops working immediately. For 403 placement_unavailable, use an active placement owned by the supplier whose key you sent.
The API rejects my filters or returns 429
Only placement_id, type, limit, offset and optional user_id are accepted. Remove country, IP and query-string API-key parameters. For 429, respect the response’s Retry-After value before retrying.
There are no surveys, or a listed survey will not open
A catalogue item is not a guaranteed allocation. Availability and eligibility can change before the respondent arrives. Use a fresh returned entry_url, a real member ID and the respondent’s browser. The bulk feed excludes personalized GRL, MyPinio and Prime inventory.
The iframe is clipped, cannot scroll, or will not launch a survey
Give the embed sufficient height and remove restrictive height or overflow rules from its parent. Do not add a restrictive sandbox without testing the required profile and new-tab flows. Browser pop-up controls, embedded-browser restrictions and privacy settings can affect launch. Test a direct user click in a normal browser and send support the browser version and a redacted screenshot.
A postback was rejected, or a member has not been credited
Check the full endpoint path, parameter mappings, HTTP response and your receiver’s application logs. A base domain is not a reward handler. Return a direct 2xx only after durable processing; redirects and login pages are not valid acknowledgements. Compare the exact transaction and placement before requesting a resend.
My new postback URL is not used for an old transaction
Queued deliveries preserve their original payload and destination. Editing a placement does not rewrite already-created delivery records. Ask support to inspect the affected transaction; do not keep changing the endpoint or manually replaying credits.
Dashboard totals and my daily ledger look different
Click-cohort metrics use the click date; completion-date earnings use the completion date. Align the reporting period and status before comparing. Retained earnings already exclude reversed records, so do not subtract the same reversal twice.