openapi: 3.0.3
info:
  title: Pollfish Apps Survey Distribution API
  version: '2026.07'
  description: "Unified OpenAPI description of Pollfish's documented public REST surfaces. Pollfish is a mobile survey and market-research platform owned by Prodege LLC.\n\nTwo hosts are covered:\n- `https://www.pollfish.com` - the Dashboard API (publisher app management and\n  analytics), HTTP Basic Auth with your Pollfish account email and secret key.\n- `https://wss.pollfish.com` - the survey-serving / offerwall API used as an\n  alternative to the SDK. Despite the `wss` hostname, the transport is HTTPS\n  GET/HEAD, NOT WebSocket.\n\n\nEndpoints are annotated with `x-endpoint-status` of `confirmed` (documented in Pollfish's own GitHub docs at github.com/pollfish/docs) or `modeled` (shape inferred where the response body is HTML or the schema is not exhaustively documented). Survey creation / audience design for researchers is done in the Pollfish dashboard and is not part of this documented public REST API."
  contact:
    name: Pollfish (Prodege)
    url: https://www.pollfish.com/docs
  termsOfService: https://www.pollfish.com/terms/
  license:
    name: Proprietary
    url: https://www.pollfish.com/terms/
servers:
- url: https://www.pollfish.com
  description: Dashboard API (apps, performance, revenue, demographics, logs)
- url: https://wss.pollfish.com
  description: Survey serving and offerwall API (HTTPS, not WebSocket)
tags:
- name: Survey Distribution
  description: Device register, offerwall, and survey rendering.
paths:
  /v2/device/register/true:
    get:
      operationId: registerDevice
      tags:
      - Survey Distribution
      summary: Request a survey / offerwall for a device
      description: Requests a matching survey (or, with `offerwall=true`, an offerwall) for a respondent device. All register parameters are passed inside the `json` query parameter as a JSON string; `dontencrypt=true` must be included. With `offerwall=true` and `content_type=json`, returns a JSON list of surveys with reward and remaining-completes data; otherwise returns an HTML page. Response is HTTP 200 when a survey is available, 204 when none is available. This host is wss.pollfish.com but the call is a normal HTTPS GET, not a WebSocket connection.
      servers:
      - url: https://wss.pollfish.com
      x-endpoint-status: confirmed
      parameters:
      - name: json
        in: query
        required: true
        description: URL-encoded JSON object carrying all register parameters (api_key, device_id, timestamp, ip, os, locale, version, encryption, placement_key, offerwall, content_type, reward_name, reward_conversion, click_id, targeting demographics, etc.). See the register JSON schema.
        schema:
          $ref: '#/components/schemas/RegisterJson'
      - name: dontencrypt
        in: query
        required: true
        description: Must be set to true on every request.
        schema:
          type: boolean
          default: true
      - name: sig
        in: query
        required: false
        description: Base64 + percent-encoded HMAC-SHA1 of reward_conversion+reward_name+click_id signed with your account secret key. Required when reward_conversion is passed.
        schema:
          type: string
      responses:
        '200':
          description: Survey available. Body is an HTML page, or (offerwall JSON mode) an OfferwallResponse JSON object.
          content:
            text/html:
              schema:
                type: string
            application/json:
              schema:
                $ref: '#/components/schemas/OfferwallResponse'
        '204':
          description: No survey available.
        '400':
          description: Bad request (for example, "Hash check failed" when sig validation fails).
    head:
      operationId: checkSurveyAvailability
      tags:
      - Survey Distribution
      summary: Check survey availability (no body)
      description: Same as the GET register call but returns only the status code, letting you check availability without transferring the HTML body.
      servers:
      - url: https://wss.pollfish.com
      x-endpoint-status: confirmed
      parameters:
      - name: json
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/RegisterJson'
      - name: dontencrypt
        in: query
        required: true
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Survey available.
        '204':
          description: No survey available.
  /v2/device/survey/{survey_id}:
    get:
      operationId: loadSurvey
      tags:
      - Survey Distribution
      summary: Load / render a specific survey
      description: Loads a specific survey by id, as referenced by the `survey_link` returned in an offerwall response. Renders the survey HTML to the respondent. The `json` and `dontencrypt` query parameters mirror the register call. Marked modeled because the response is an HTML survey experience rather than a documented JSON schema.
      servers:
      - url: https://wss.pollfish.com
      x-endpoint-status: modeled
      parameters:
      - name: survey_id
        in: path
        required: true
        description: The survey id (as returned in an offerwall survey_link).
        schema:
          type: integer
      - name: json
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/RegisterJson'
      - name: dontencrypt
        in: query
        required: true
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: HTML survey page.
          content:
            text/html:
              schema:
                type: string
        '204':
          description: Survey no longer available.
components:
  schemas:
    OfferwallSurvey:
      type: object
      properties:
        survey_id:
          type: integer
        survey_cpa:
          type: integer
          description: Payout in US dollar cents.
        survey_class:
          type: string
          description: Provider and optional type, e.g. "Pollfish/Demographics", "Toluna", "Cint".
        survey_ir:
          type: integer
          description: Estimated incidence rate 0-100.
        survey_loi:
          type: integer
          description: Estimated length of interview in minutes.
        survey_lang:
          type: string
        reward_name:
          type: string
        reward_value:
          type: number
        survey_link:
          type: string
          description: URL to load/render this survey (GET /v2/device/survey/{survey_id}).
        remaining_completes:
          type: integer
          description: Remaining completes (Pollfish surveys only).
        ordering:
          type: integer
    OfferwallResponse:
      type: object
      properties:
        surveys:
          type: array
          items:
            $ref: '#/components/schemas/OfferwallSurvey'
        hasDemographics:
          type: boolean
    RegisterJson:
      type: object
      description: The JSON object passed (URL-encoded) as the `json` query parameter on the register/survey calls. Only the most common fields are listed; see the Pollfish API documentation for the full parameter table. Every value must be a string.
      required:
      - api_key
      - device_id
      - timestamp
      - ip
      - os
      - locale
      - encryption
      - version
      properties:
        api_key:
          type: string
        device_id:
          type: string
          description: Advertising id (IDFA / AAID) or a stable per-user UUID.
        timestamp:
          type: string
          description: Request time in epoch millis.
        ip:
          type: string
        os:
          type: integer
          description: 0 Android, 1 iOS, 2 Windows Phone, 3 Web.
        locale:
          type: string
        encryption:
          type: string
          enum:
          - NONE
        version:
          type: integer
          description: Current API version (7).
        placement_key:
          type: string
          description: Placement id whose settings apply.
        offerwall:
          type: boolean
        content_type:
          type: string
          enum:
          - json
          - html
        always_return_content:
          type: boolean
        reward_name:
          type: string
        reward_conversion:
          type: string
        click_id:
          type: string
        debug:
          type: boolean
        sortBy:
          type: string
          enum:
          - reward
          - loi
          - ir
        order:
          type: string
          enum:
          - asc
          - desc
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth for the Dashboard API. Username is your Pollfish account email, password is your account secret key (from Account Information in the publisher dashboard).