Skip to integration guide
Enligne Survey

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.

  1. Create an account

    Register, verify your email and wait for supplier approval.

  2. Add a placement

    Open Placement → Add Placement. Enter your website, full Base Postback URL, currency and reward settings. Controls depend on your account permissions.

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

Placement form showing website, Base Postback URL, Coins currency and conversion settings with example values.
Placement setup · Demo dataView full size (new tab) ↗

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.

HTML · example embed
<iframe
  src="https://enlignesurvey.com/iframe?placement_id=YOUR_PLACEMENT_ID&amp;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.

API Feed workspace with a masked demo key, Copy API key, Rotate key and Refresh controls, plus catalogue guidance.
API Feed workspace · Demo dataView full size (new tab) ↗
Keep your API key on your server.

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 · run from your backend
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
Supported query parameters
ParameterValues & behavior
placement_idRequired. An active placement belonging to the supplier whose key you use. Use its copied token or numeric ID.
typeall (default), survey or offer. Router campaigns are included in survey; router is not a valid filter.
limit1–100 items per request. API default: 50; dashboard builder default: 20.
offset0–10000. Default: 0. Follow meta.next_offset in the response.
user_idOptional. 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.

JSON · one-page example
{
  "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

Item fields and how to use them
FieldsMeaning
id, survey_idCatalogue identity and survey/campaign reference. Keep the returned entry URL instead of reconstructing provider links.
type, category, source, networkInventory classification and network. Source is lms or campaign; category can be survey, offer or router.
name, description, image_urlDisplay content. Description is plain text and empty for LMS surveys; image may be null. Render text safely, not as trusted HTML.
countriesCountry-code array. ["ALL"] denotes worldwide catalogue targeting. Final launch eligibility still depends on the respondent.
loi, irSurvey length and incidence fields, returned as strings when present. Campaign items use null.
device_codesString codes: 1 Android, 2 Apple/tablet, 3 web. LMS items return an empty array; do not invent device restrictions from it.
supplier_payout, payout_currencyYour advertised commission and USD. The amount is a decimal string, not a JSON number; precision may vary.
points, currencyThe member reward and placement currency. Points are a decimal string calculated from placement settings.
payout_model, minimum_supplier_payout, minimum_pointsOptional 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
JSON · error envelope
{"status":"Failed","error":{"code":"invalid_type","message":"type must be all, survey, or offer."}}
HTTP statuses
StatusAction
400Read error.code: invalid_parameters, invalid_placement, invalid_type, invalid_pagination or invalid_user_id. Correct the request before retrying.
401invalid_api_key: verify key, authentication header and active supplier access.
403 / 409placement_unavailable: check ownership/status (403) or reward configuration (409).
405method_not_allowed: use GET. HEAD is also supported and returns no response body.
429rate_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.

Placement Variables Mapping fields using user_id, status, tx_id, payout and reward, followed by the generated iframe snippet.
Postback mapping & copied embed · Demo dataView full size (new tab) ↗
All available mapping fields
Example names—match them to your receiver
Placement fieldExample nameDelivered value
Respondent IDuser_idYour attributed member ID.
Transaction IDtx_idThe transaction reference; use it with the placement when reconciling.
Survey Statusstatus1 completion; 2 reversal.
Supplier CommissionpayoutSupplier commission in USD.
Respondent CommissionrewardMember reward in the configured placement currency.
Campaign / Placement / Supplier IDcampaign / placement / supplierThe relevant campaign, placement and supplier references.
Country ISO / IP Addresscountry / ipAvailable respondent country/IP. Treat as personal data.
Offer Name / Affiliate Suboffer_name / aff_subOffer 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:

GET · synthetic completion
https://publisher.example/rewards?placement=42&user_id=member_demo&status=1&tx_id=demo_transaction_001&payout=1.20&reward=120.00

status=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.
No automatic outgoing signature.

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.

GET · synthetic reversal of the same transaction
https://publisher.example/rewards?placement=42&user_id=member_demo&status=2&tx_id=demo_transaction_001&payout=1.20&reward=120.00
Recommended receiver behavior
Incoming eventWhat your system should do
First verified completion · 1Record and credit once, atomically.
Repeated delivery of the current stateAcknowledge the duplicate without another balance change.
Verified reversal · 2Find the matched saved credit and reverse it once. Store the resulting state and audit trail.
Unknown, late or conflicting transactionHold 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.

  1. Confirm access. Verify email and account approval, an active placement, and the expected reward currency.
  2. 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.
  3. 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.
  4. 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.
  5. Exercise your receiver locally. Test a completion, duplicate delivery, reversal, duplicate reversal and an unknown transaction. Reconcile late or conflicting events before changing balances.
  6. 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.

Back to the top