{"openapi":"3.1.0","info":{"title":"YetiPoll API","version":"1.0.0","summary":"Surveys for your users, from your server.","description":"The server-side API of the YetiPoll survey wall. Call it from your backend with an app's secret key; the key decides the app and the mode, so the same code runs against the sandbox (yp_test_sk_…) and against live traffic (yp_live_sk_…). Never call it from a browser or a mobile app.\n\nGuide: https://yetipoll.com/developers/api","termsOfService":"https://yetipoll.com/legal/terms","contact":{"name":"YetiPoll","url":"https://yetipoll.com/contact"}},"externalDocs":{"description":"Developer documentation","url":"https://yetipoll.com/developers"},"servers":[{"url":"https://yetipoll.com/api/v1"}],"security":[{"secretKey":[]}],"paths":{"/app":{"get":{"operationId":"getApp","summary":"The app the key belongs to","description":"Name, mode, status and currency settings. Handy as a connection test.","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/App"},"example":{"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}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"405":{"$ref":"#/components/responses/Error405"},"429":{"$ref":"#/components/responses/Error429"}}}},"/surveys":{"get":{"operationId":"listSurveys","summary":"The surveys one user can take right now","description":"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.","parameters":[{"name":"user_id","in":"query","description":"Your own id for the user: 1 to 128 characters from letters, digits and _ . @ : -","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.@:-]+$"},"required":true},{"name":"ip","in":"query","description":"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.","schema":{"type":"string"}},{"name":"country","in":"query","description":"Two-letter country code, if you know it. Worked out from ip when left out.","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"user_agent","in":"query","description":"The user's browser or device user agent. Improves matching.","schema":{"type":"string","maxLength":400}},{"name":"limit","in":"query","description":"How many surveys to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyList"},"example":{"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=..."}]}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"405":{"$ref":"#/components/responses/Error405"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}}}},"/wall-url":{"get":{"operationId":"getWallUrl","summary":"A signed address of the hosted wall for one user","description":"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.","parameters":[{"name":"user_id","in":"query","description":"Your own id for the user: 1 to 128 characters from letters, digits and _ . @ : -","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.@:-]+$"},"required":true}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WallUrl"},"example":{"user_id":"user-42","mode":"test","url":"https://yetipoll.com/wall?app=yp_test_pk_...&user=user-42&sig=..."}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"405":{"$ref":"#/components/responses/Error405"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}}}},"/conversions":{"get":{"operationId":"listConversions","summary":"Completions for this app and mode, newest first","description":"The same data your postbacks carry. Use it to reconcile or to catch up after downtime.","parameters":[{"name":"user_id","in":"query","description":"Only this user.","schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_.@:-]+$"}},{"name":"status","in":"query","description":"Only conversions in this state.","schema":{"type":"string","enum":["credited","reversed"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversionList"},"example":{"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}]}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"405":{"$ref":"#/components/responses/Error405"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"}}}},"/conversions/{transaction_id}":{"get":{"operationId":"getConversion","summary":"One conversion, by the transaction_id from its postback","description":"Answers with its current state: a completion that was taken back since comes back as reversed.","parameters":[{"name":"transaction_id","in":"path","required":true,"description":"The 26-character id a postback carried.","schema":{"type":"string","pattern":"^[0-9A-Za-z]{26}$"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversion"},"example":{"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}}}},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"405":{"$ref":"#/components/responses/Error405"},"429":{"$ref":"#/components/responses/Error429"}}}}},"webhooks":{"reward":{"get":{"operationId":"receivePostback","summary":"The postback we send to your server","description":"Sent to the postback URL of the app when a user completes a survey, is screened out, or when a completion is taken back. Verify signature = HMAC-SHA256(\"user_id:transaction_id:reward:status\", secret key) as lowercase hex, using the values exactly as they arrive. Apply each transaction_id + status pair once: a reversal reuses the transaction_id of the completion it cancels, with the reward negated. Answer with any 2xx status. The parameter names below are used when your URL has no placeholders; with placeholders you choose the names.\n\nGuide: https://yetipoll.com/developers/postbacks","security":[],"parameters":[{"name":"user_id","in":"query","description":"Your own id for the user.","schema":{"type":"string"}},{"name":"transaction_id","in":"query","description":"Our id for the completion. A reversal reuses it.","schema":{"type":"string"}},{"name":"reward","in":"query","description":"Amount in your currency. Negative on a reversal.","schema":{"type":"string"}},{"name":"payout_usd","in":"query","description":"What the completion earned you, in US dollars.","schema":{"type":"string"}},{"name":"currency","in":"query","description":"The name of your reward currency.","schema":{"type":"string"}},{"name":"status","in":"query","description":"completed, screenout or reversed.","schema":{"type":"string"}},{"name":"type","in":"query","description":"complete, screenout or bonus.","schema":{"type":"string"}},{"name":"country","in":"query","description":"Two-letter country of the user, when known.","schema":{"type":"string"}},{"name":"test","in":"query","description":"1 for sandbox and test postbacks, otherwise 0.","schema":{"type":"string"}},{"name":"timestamp","in":"query","description":"Unix time the postback was built.","schema":{"type":"string"}},{"name":"signature","in":"query","description":"HMAC-SHA256 of user_id:transaction_id:reward:status.","schema":{"type":"string"}}],"responses":{"200":{"description":"Any 2xx status tells us you have it. Anything else is retried."}}}}},"components":{"securitySchemes":{"secretKey":{"type":"http","scheme":"bearer","description":"The secret key of an app: yp_test_sk_… for the sandbox, yp_live_sk_… for live data."}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window, per app and mode.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time the window ends.","schema":{"type":"integer"}}},"responses":{"Error401":{"description":"error.code is one of: missing_key, invalid_key, public_key_used","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error403":{"description":"error.code is one of: account_suspended, app_paused, user_blocked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error404":{"description":"error.code is one of: not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error405":{"description":"error.code is one of: method_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error422":{"description":"error.code is one of: invalid_user_id, missing_ip, invalid_ip, invalid_country, invalid_status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error429":{"description":"error.code is one of: rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["missing_key","invalid_key","public_key_used","account_suspended","app_paused","user_blocked","not_found","method_not_allowed","invalid_user_id","missing_ip","invalid_ip","invalid_country","invalid_status","rate_limited"]},"message":{"type":"string","description":"For a developer to read, not to show to a user."}}}}},"App":{"type":"object","required":["id","name","platform","status","mode","currency","postback_url","require_signature"],"properties":{"id":{"type":"string","description":"The app's id: eight characters, stable for the life of the app."},"name":{"type":"string"},"platform":{"type":"string"},"status":{"type":"string"},"mode":{"type":"string","enum":["test","live"],"description":"Decided by the key: test is the sandbox."},"currency":{"type":"object","required":["name","singular","per_usd","decimals"],"properties":{"name":{"type":"string","description":"What your reward currency is called, more than one."},"singular":{"type":"string","description":"What exactly one is called. May be empty."},"per_usd":{"type":"number","description":"Units of your currency per US dollar you earn."},"decimals":{"type":"integer","description":"Decimal places a reward is shown with."}}},"postback_url":{"type":"string","description":"Empty when none is set."},"require_signature":{"type":"boolean","description":"Whether the hosted wall only opens with a signed link."}}},"Survey":{"type":"object","required":["id","category","length_minutes","rating","reward","reward_label","payout_usd","click_url"],"properties":{"id":{"type":"string"},"category":{"type":"string","description":"The topic, such as \"Travel plans\". Empty when a survey has none: show your own wording then, such as \"Survey\"."},"length_minutes":{"type":"integer"},"rating":{"type":"number","description":"How users rated it, out of 5. 0 when not rated yet."},"reward":{"type":"number","description":"What the user earns, in your currency at your app's rate."},"reward_label":{"type":"string","description":"The reward ready to show, such as \"1,470 Coins\"."},"payout_usd":{"type":"number","description":"What a completion earns you, in US dollars."},"click_url":{"type":"string","format":"uri","description":"Where to send this user to start. Personal and valid for a few hours."}}},"SurveyList":{"type":"object","required":["user_id","mode","count","surveys"],"properties":{"user_id":{"type":"string"},"mode":{"type":"string","enum":["test","live"],"description":"Decided by the key: test is the sandbox."},"count":{"type":"integer"},"surveys":{"type":"array","items":{"$ref":"#/components/schemas/Survey"}}}},"WallUrl":{"type":"object","required":["user_id","mode","url"],"properties":{"user_id":{"type":"string"},"mode":{"type":"string","enum":["test","live"],"description":"Decided by the key: test is the sandbox."},"url":{"type":"string","format":"uri"}}},"Conversion":{"type":"object","required":["transaction_id","user_id","type","status","reward","payout_usd","net_reward","currency","country","test","created_at","reversed_at"],"properties":{"transaction_id":{"type":"string","description":"The id its postback carried. A reversal keeps it."},"user_id":{"type":"string"},"type":{"type":"string","enum":["complete","screenout","bonus"]},"status":{"type":"string","enum":["credited","reversed"]},"reward":{"type":"number","description":"The amount in your currency when it was credited."},"payout_usd":{"type":"number","description":"What it earned you, in US dollars."},"net_reward":{"type":"number","description":"What the user should hold for it now: the reward while credited, 0 once reversed."},"currency":{"type":"string"},"country":{"type":"string","description":"Two-letter country of the user, or empty."},"test":{"type":"boolean","description":"True for sandbox conversions."},"created_at":{"type":"string","format":"date-time"},"reversed_at":{"type":["string","null"],"format":"date-time"}}},"ConversionList":{"type":"object","required":["page","per_page","total","conversions"],"properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"conversions":{"type":"array","items":{"$ref":"#/components/schemas/Conversion"}}}}}}}