API reference
The API is for your server. Use it to build your own survey interface, to fetch signed wall addresses, or to check conversions.
Basics
| Base URL | https://yetipoll.com/api/v1 |
|---|---|
| Authentication | Authorization: Bearer <secret key>. A sandbox secret key works on sandbox data, a live one on live data. |
| Format | JSON responses. Every endpoint is a GET; parameters go in the query string. Times are ISO 8601 in UTC. |
| Rate limit | Per app and mode. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit you get 429. |
Never call the API from a browser or a mobile app. The secret key would be visible to anyone.
Errors
Errors use the HTTP status and one shape:
{
"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 |
GET /surveys
The surveys one user can take right now, best match first.
| Parameter | Meaning |
|---|---|
user_id | Your id for the user. Required. |
ip | The user's public IP address. Required in live mode: surveys are matched to the person, and your server's address would describe a data centre. |
country | Two-letter country code, if you know it. Optional. |
user_agent | The user's browser or device user agent. Optional, improves matching. |
limit | 1 to 100, default 30. |
curl "https://yetipoll.com/api/v1/surveys?user_id=user-42&ip=203.0.113.9" \
-H "Authorization: Bearer yp_test_sk_your_key"
{
"user_id": "user-42",
"mode": "test",
"count": 2,
"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=..."
}
]
}
rewardis in your currency, at your app's rate.payout_usdis what a completion earns you.- Send the user to
click_urlto start the survey. It is personal to that user and valid for a few hours, so fetch the list when you show it rather than storing it. - A list is per user. Do not show one user's surveys to another.
GET /wall-url
A signed address of the hosted wall for one user, for iframes, web views and the SDKs.
curl "https://yetipoll.com/api/v1/wall-url?user_id=user-42" \
-H "Authorization: Bearer yp_test_sk_your_key"
{
"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.
| Parameter | Meaning |
|---|---|
user_id | Only this user. Optional. |
status | credited or reversed. Optional. |
page, per_page | Paging. per_page up to 100, default 50. |
{
"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
}
]
}
net_reward is what the user should hold for this conversion now: the reward while it is credited, 0 once it is reversed.
GET /conversions/{transaction_id}
One conversion, by the transaction_id from its postback. Use it to double-check a postback or to reconcile.
GET /app
The app the key belongs to: name, mode, status and currency settings. Handy as a connection test.
For tools and AI assistants
The same reference in the formats tools read. Import the first into Postman, Insomnia or a client generator; hand the second to a coding assistant.
| OpenAPI 3.1 | https://yetipoll.com/openapi.json |
|---|---|
| Guide in one file | https://yetipoll.com/llms-full.txt |
| Index | https://yetipoll.com/llms.txt |