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 URLhttps://yetipoll.com/api/v1
AuthenticationAuthorization: Bearer <secret key>. A sandbox secret key works on sandbox data, a live one on live data.
FormatJSON responses. Every endpoint is a GET; parameters go in the query string. Times are ISO 8601 in UTC.
Rate limitPer 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 _ . @ : -"
  }
}
StatusCodes
401missing_key, invalid_key, public_key_used
403account_suspended, app_paused, user_blocked
404not_found
405method_not_allowed
422invalid_user_id, missing_ip, invalid_ip, invalid_country, invalid_status
429rate_limited

GET /surveys

The surveys one user can take right now, best match first.

ParameterMeaning
user_idYour id for the user. Required.
ipThe 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.
countryTwo-letter country code, if you know it. Optional.
user_agentThe user's browser or device user agent. Optional, improves matching.
limit1 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=..."
    }
  ]
}

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.

ParameterMeaning
user_idOnly this user. Optional.
statuscredited or reversed. Optional.
page, per_pagePaging. 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.1https://yetipoll.com/openapi.json
Guide in one filehttps://yetipoll.com/llms-full.txt
Indexhttps://yetipoll.com/llms.txt