# YetiPoll developer guide > YetiPoll is a survey wall for apps, games and websites. Users answer paid surveys and are rewarded in the publisher's own currency; the publisher's server is told about every reward. This file is the whole developer documentation in one place. The pages it is built from start at https://yetipoll.com/developers. ## How an integration works 1. The publisher creates an account at https://yetipoll.com and adds an app. Sign-up is instant. 2. The app shows the wall to a signed-in user, passing the app's public key and the publisher's own id for that user. 3. The user completes a survey. YetiPoll calls the publisher's postback URL. 4. The publisher's server verifies the signature and credits the user once. Nothing else is needed. The API is optional: it is for publishers who want to draw their own survey list or reconcile. ## Rules to follow when writing an integration - The secret key stays on the server. Never put it in a web page, a mobile app or a game client. Only the public key goes there. - Start with the sandbox keys (`yp_test_…`). Going live is swapping the keys, nothing else. - Credit users from the postback, never from the client. The wall and the SDKs do not report rewards to the app on purpose. - Handle each `transaction_id` + `status` pair once. A reversal carries the same `transaction_id` as the completion it cancels, so deduplicating on the id alone would ignore every reversal. - When `test` is `1`, run the code but do not credit a real balance. - A user id is 1 to 128 characters from letters, digits and `_ . @ : -`. Use a stable account id, not an email address. ## Keys Each app has four keys. The key decides the mode. | Key | Looks like | Where it goes | |---|---|---| | Sandbox public | `yp_test_pk_…` | In pages and apps while building. Practice surveys only. | | Sandbox secret | `yp_test_sk_…` | On the server: verifies sandbox postbacks, opens the API in sandbox. | | Live public | `yp_live_pk_…` | In pages and apps in production. | | Live secret | `yp_live_sk_…` | On the server only. | A secret key can be replaced from the app page in the dashboard. The old one stops working at once. ## Showing the wall ### Web: the script ```html
``` | Attribute | Meaning | |---|---| | `data-app` | The public key. Required. | | `data-user` | The publisher's id for the signed-in user. Required. | | `data-signature` | Signature of the user id, when the app requires signed links. | | `data-target` | CSS selector of the element to render into. Without it the wall is placed after the script tag. | | `data-display` | `inline` (default) or `button`. | | `data-label` | Text of the button. The button has the class `yetipoll-button` and no styling of its own. | For single-page apps, load the script once without data attributes and start it when the user is known: ```js YetiPoll.init({ app: "yp_test_pk_your_key", user: currentUser.id, target: "#surveys" }); YetiPoll.on("survey_opened", function () { /* the user started a survey */ }); ``` `YetiPoll.open()` and `YetiPoll.close()` show the wall as an overlay from your own button. Events: `ready`, `survey_opened`, `close`. A site with a Content Security Policy allows `https://yetipoll.com` in `script-src` and `frame-src`. ### Anywhere: the wall as a page ```html ``` | Parameter | Meaning | |---|---| | `app` | The public key. Required. | | `user` | The publisher's id for the user. Required. | | `sig` | Signature of the user id. Required when the app has "Require signed wall links" on. | | `embed` | `1` hides the wall's own heading. | The wall posts its height to the parent page whenever it changes: ```js window.addEventListener("message", function (event) { if (event.origin !== "https://yetipoll.com") return; if (event.data && event.data.source === "yetipoll" && event.data.type === "height") { document.querySelector("iframe").style.height = event.data.height + "px"; } }); ``` The wall sets no cookies and needs no session. Its colour, light or dark background, heading and corner style are set per app in the dashboard. ### Mobile and game engines: the SDKs Each SDK is one source file to add to the project. It opens the wall for the signed-in user inside the app and refreshes the list when the user comes back. | Platform | File | |---|---| | Web script | https://yetipoll.com/sdk/v1/yetipoll.js | | Android (Kotlin) | https://yetipoll.com/sdk/android/YetiPoll.kt | | iOS (Swift) | https://yetipoll.com/sdk/ios/YetiPoll.swift | | Unity (C#) | https://yetipoll.com/sdk/unity/YetiPoll.cs | | Flutter (Dart) | https://yetipoll.com/sdk/flutter/yetipoll.dart | | React Native | https://yetipoll.com/sdk/react-native/YetiPoll.tsx | | React (web) | https://yetipoll.com/sdk/react/YetiPoll.jsx | ```kotlin YetiPoll.open(context, appKey = "yp_test_pk_your_key", userId = currentUser.id) ``` ```swift YetiPoll.present(from: self, appKey: "yp_test_pk_your_key", userId: currentUser.id) ``` ```csharp YetiPoll.Open("yp_test_pk_your_key", playerId); ``` Any other platform that can show a web page loads `https://yetipoll.com/wall?app=…&user=…` in a web view. ### Signing wall links By default anyone who knows a user id could open that user's wall. Rewards still only reach users through the publisher's server, but for production turn on "Require signed wall links" in the app settings. The wall then only opens with a signature the server made: `sig = HMAC-SHA256(user id, secret key)`, as lowercase hex. ```php $sig = hash_hmac("sha256", $userId, $secretKey); ``` ```js const sig = crypto.createHmac("sha256", secretKey).update(userId).digest("hex"); ``` ```python sig = hmac.new(secret_key.encode(), user_id.encode(), hashlib.sha256).hexdigest() ``` Or ask the API for a ready-made signed address: `GET /api/v1/wall-url`. ## Postbacks: receiving rewards A postback is an HTTP GET from YetiPoll to the publisher's server, sent when a user completes a survey, is screened out, or when a completion is taken back. The URL is set per app. Placeholders are replaced with URL-encoded values: ``` https://your-server.example/yetipoll?user={user_id}&tx={transaction_id}&reward={reward}&status={status}&test={test}&sig={signature} ``` A URL without any placeholder gets every value appended as a query parameter under the names below. | Placeholder | Value | |---|---| | `{user_id}` | Your own id for the user | | `{transaction_id}` | Our id for the completion. A reversal reuses it | | `{reward}` | Amount in your currency. Negative on a reversal | | `{payout_usd}` | What the completion earned you, in US dollars | | `{currency}` | The name of your reward currency | | `{status}` | completed, screenout or reversed | | `{type}` | complete, screenout or bonus | | `{country}` | Two-letter country of the user, when known | | `{test}` | 1 for sandbox and test postbacks, otherwise 0 | | `{timestamp}` | Unix time the postback was built | | `{signature}` | HMAC-SHA256 of user_id:transaction_id:reward:status | ### The three statuses | `status` | Meaning | `reward` | |---|---|---| | `completed` | The user finished a survey. Credit them. | Positive | | `screenout` | The user did not qualify. Usually nothing to credit. | 0, or a small consolation amount | | `reversed` | An earlier completion was taken back after a quality check. Deduct it. | Negative: the original amount, negated | ### What the handler does 1. Verify the signature. Reject anything that does not match. 2. If this `transaction_id` + `status` pair was handled before, answer 200 and stop. 3. Unless `test` is `1`, add `reward` to the user's balance (it is negative on a reversal). 4. Remember the pair. Answer with any 2xx status; the body does not matter. ### Verifying the signature `signature = HMAC-SHA256("user_id:transaction_id:reward:status", secret key)`, lowercase hex. Use the values exactly as they arrive, without reformatting the reward, and the secret key of the mode the postback belongs to (the sandbox key for sandbox postbacks). ```php { const { user, tx, reward, status, test, sig = "" } = req.query; const expected = crypto .createHmac("sha256", process.env.YETIPOLL_SECRET) .update(`${user}:${tx}:${reward}:${status}`) .digest("hex"); const ok = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)); if (!ok) return res.sendStatus(403); if (await alreadyHandled(tx, status)) return res.sendStatus(200); if (test !== "1") await addToBalance(user, Number(reward)); await remember(tx, status); res.sendStatus(200); }); ``` ```python # Python (Flask) import hashlib, hmac, os from flask import request @app.get("/yetipoll") def yetipoll(): q = request.args payload = f"{q['user']}:{q['tx']}:{q['reward']}:{q['status']}" expected = hmac.new(os.environ["YETIPOLL_SECRET"].encode(), payload.encode(), hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, q.get("sig", "")): return "", 403 if already_handled(q["tx"], q["status"]): return "", 200 if q.get("test", "0") != "1": add_to_balance(q["user"], float(q["reward"])) remember(q["tx"], q["status"]) return "", 200 ``` ### Retries If the server does not answer with a 2xx status within a few seconds, the postback is sent again with growing pauses, from about a minute up to a day, for several attempts. Then it is marked failed and can be resent from the postback log in the dashboard. The same data can always be read from `GET /api/v1/conversions`. ### Testing The app page in the dashboard sends a test completion and a test reversal. Both are signed with the secret key of the mode being viewed and carry `test=1`. ## Sandbox and live | | Sandbox | Live | |---|---|---| | Keys | `yp_test_pk_…`, `yp_test_sk_…` | `yp_live_pk_…`, `yp_live_sk_…` | | Surveys | Practice surveys that end the way the tester chooses | Real surveys, matched to each user | | Earnings | None | Added to the publisher's balance and invoiced monthly | | Postbacks | Same URL, `test=1`, signed with the sandbox secret key | `test=0`, signed with the live secret key | | API | Sandbox data only | Live data only | A full test run: open the wall with the sandbox public key as any user id, open a practice survey, choose "Complete the survey" (a `completed` postback arrives), then "Now reverse it" (a `reversed` postback with the same `transaction_id` and the reward negated). Open another and choose "Screen out". Before live traffic: - The integration uses the live public key. - The postback handler verifies with the live secret key, deducts on `reversed`, and does not credit real users when `test=1`. - "Require signed wall links" is on and the server signs user ids. ## API reference For the publisher's server only. Base URL `https://yetipoll.com/api/v1`. Machine-readable description: https://yetipoll.com/openapi.json - Authentication: `Authorization: Bearer `. A sandbox secret key reads sandbox data, a live one live data. - Every endpoint is a GET with query parameters and answers JSON. - Rate limit: per app and mode. Every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix time). Over the limit the answer is 429. - Times are ISO 8601 in UTC. ```bash curl "https://yetipoll.com/api/v1/surveys?user_id=user-42&ip=203.0.113.9" \ -H "Authorization: Bearer yp_test_sk_your_key" ``` ### GET /app The app the key belongs to. Name, mode, status and currency settings. Handy as a connection test. ```json { "id": "k7m2q9x4", "name": "Coin Quest", "platform": "web", "status": "active", "mode": "test", "currency": { "name": "Coins", "singular": "Coin", "per_usd": 1000, "decimals": 0 }, "postback_url": "https://your-server.example/yetipoll?user={user_id}&tx={transaction_id}&reward={reward}&status={status}&sig={signature}", "require_signature": true } ``` ### GET /surveys The surveys one user can take right now. Best match first. A list is personal: fetch it when you show it, never store it, and never show one user's list to another. Send the user to click_url to start a survey. | Parameter | In | Required | Meaning | |---|---|---|---| | `user_id` | query | yes | Your own id for the user: 1 to 128 characters from letters, digits and _ . @ : - | | `ip` | query | no | The user's public IP address. Required with a live key: surveys are matched to the person, and your server's address would describe a data centre. | | `country` | query | no | Two-letter country code, if you know it. Worked out from ip when left out. | | `user_agent` | query | no | The user's browser or device user agent. Improves matching. | | `limit` | query | no | How many surveys to return. 1 to 100. Default 30. | ```json { "user_id": "user-42", "mode": "test", "count": 1, "surveys": [ { "id": "k3v9m2xq.5f0c2a9d4b7e61c3a2f0", "category": "Travel plans", "length_minutes": 12, "rating": 4.7, "reward": 1470, "reward_label": "1,470 Coins", "payout_usd": 1.47, "click_url": "https://yetipoll.com/wall/go/k3v9m2xq.5f0c2a9d4b7e61c3a2f0?t=..." } ] } ``` ### GET /wall-url A signed address of the hosted wall for one user. For iframes, web views and the SDKs. The signature is already in the address, so it opens even when the app requires signed wall links. | Parameter | In | Required | Meaning | |---|---|---|---| | `user_id` | query | yes | Your own id for the user: 1 to 128 characters from letters, digits and _ . @ : - | ```json { "user_id": "user-42", "mode": "test", "url": "https://yetipoll.com/wall?app=yp_test_pk_...&user=user-42&sig=..." } ``` ### GET /conversions Completions for this app and mode, newest first. The same data your postbacks carry. Use it to reconcile or to catch up after downtime. | Parameter | In | Required | Meaning | |---|---|---|---| | `user_id` | query | no | Only this user. | | `status` | query | no | Only conversions in this state. One of: credited, reversed. | | `page` | query | no | Default 1. | | `per_page` | query | no | 1 to 100. Default 50. | ```json { "page": 1, "per_page": 50, "total": 1, "conversions": [ { "transaction_id": "01JD3M5Q8ZK7W2V9X4T6B1N0CE", "user_id": "user-42", "type": "complete", "status": "credited", "reward": 1470, "payout_usd": 1.47, "net_reward": 1470, "currency": "Coins", "country": "US", "test": true, "created_at": "2026-11-19T10:21:07+00:00", "reversed_at": null } ] } ``` ### GET /conversions/{transaction_id} One conversion, by the transaction_id from its postback. Answers with its current state: a completion that was taken back since comes back as reversed. | Parameter | In | Required | Meaning | |---|---|---|---| | `transaction_id` | path | yes | The 26-character id a postback carried. | ```json { "transaction_id": "01JD3M5Q8ZK7W2V9X4T6B1N0CE", "user_id": "user-42", "type": "complete", "status": "credited", "reward": 1470, "payout_usd": 1.47, "net_reward": 1470, "currency": "Coins", "country": "US", "test": true, "created_at": "2026-11-19T10:21:07+00:00", "reversed_at": null } ``` ### Errors Errors use the HTTP status and one shape: ```json { "error": { "code": "invalid_user_id", "message": "user_id is required: 1 to 128 letters, digits and _ . @ : -" } } ``` | Status | Codes | |---|---| | 401 | `missing_key`, `invalid_key`, `public_key_used` | | 403 | `account_suspended`, `app_paused`, `user_blocked` | | 404 | `not_found` | | 405 | `method_not_allowed` | | 422 | `invalid_user_id`, `missing_ip`, `invalid_ip`, `invalid_country`, `invalid_status` | | 429 | `rate_limited` | `message` is written for a developer. Do not show it to users. ## Getting paid Earnings from live traffic are invoiced automatically every month and paid out on the terms shown at https://yetipoll.com/payouts. A publisher chooses a payout method in the dashboard at any time. Billing details are asked for once the balance has reached the payout minimum, not before. Sandbox traffic earns nothing. ## Help https://yetipoll.com/contact