openapi: 3.0.3
info:
  title: Pollfish 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.


    Two hosts are covered:

    - `https://www.pollfish.com` - the Dashboard API (publisher app management and
      analytics), HTTP Basic Auth with your Pollfish account email and secret key.
    - `https://wss.pollfish.com` - the survey-serving / offerwall API used as an
      alternative to the SDK. Despite the `wss` hostname, the transport is HTTPS
      GET/HEAD, NOT WebSocket.


    Endpoints 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: Apps
    description: Publisher app / placement management (Dashboard API).
  - name: Performance
    description: Survey-serving performance metrics.
  - name: Revenue
    description: Revenue reporting per provider and per country.
  - name: Demographics
    description: Respondent demographic profiles.
  - name: Logs
    description: Per-user survey logs and disqualification reasons.
  - name: Survey Distribution
    description: Device register, offerwall, and survey rendering.
paths:
  /api/public/v2/apps:
    get:
      operationId: listApps
      tags: [Apps]
      summary: List apps
      description: Returns an array of the authenticated developer's apps.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      responses:
        '200':
          description: Array of app objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/App'
    post:
      operationId: createApp
      tags: [Apps]
      summary: Create an app
      description: Creates a new publisher app (monetization placement) and returns its api_key.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppCreate'
      responses:
        '200':
          description: The created app.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '400':
          description: Missing or invalid parameters.
  /api/public/v2/apps/{api_key}:
    parameters:
      - $ref: '#/components/parameters/ApiKeyPath'
    get:
      operationId: getApp
      tags: [Apps]
      summary: Get an app
      description: Returns a single app object by its api_key.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      responses:
        '200':
          description: The app object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '403':
          description: App does not exist or you lack permission.
    put:
      operationId: updateApp
      tags: [Apps]
      summary: Update an app
      description: Updates properties of an existing app. Only supplied fields are changed.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppUpdate'
      responses:
        '200':
          description: The updated app.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '400':
          description: Missing or invalid parameters.
        '403':
          description: App does not exist or you lack permission.
    delete:
      operationId: deleteApp
      tags: [Apps]
      summary: Delete an app
      description: Deletes an app by its api_key.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      responses:
        '204':
          description: App deleted.
        '403':
          description: App does not exist or you lack permission.
  /api/public/v3/apps/performance:
    get:
      operationId: getAllAppsPerformance
      tags: [Performance]
      summary: Performance for all apps
      description: >-
        Returns performance metrics (served, seen, accepted, completed) per survey
        network for all of the developer's apps over a date range of up to 31 days.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
      responses:
        '200':
          description: Performance series grouped by network.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkPerformance'
        '400':
          description: Missing or invalid parameters.
  /api/public/v3/apps/{api_key}/performance:
    parameters:
      - $ref: '#/components/parameters/ApiKeyPath'
    get:
      operationId: getAppPerformance
      tags: [Performance]
      summary: Performance for one app
      description: Returns performance metrics for a single app over a date range of up to 31 days.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
      responses:
        '200':
          description: Performance series grouped by network.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkPerformance'
        '400':
          description: Missing or invalid parameters.
  /api/public/v3/apps/{api_key}/performanceByCountry:
    parameters:
      - $ref: '#/components/parameters/ApiKeyPath'
    get:
      operationId: getAppPerformanceByCountry
      tags: [Performance]
      summary: Performance for one app grouped by country
      description: Returns performance metrics for a single app, grouped by country and network, over a date range of up to 31 days.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
      responses:
        '200':
          description: Country-grouped performance. Shape is documented by example; modeled loosely here.
          x-endpoint-status: modeled
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    countryISO:
                      type: string
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/NetworkPerformance'
        '400':
          description: Missing or invalid parameters.
  /api/public/v3/apps/revenue:
    get:
      operationId: getAllAppsRevenue
      tags: [Revenue]
      summary: Revenue per provider for all apps
      description: Returns total revenue per survey provider for all apps over a date range, optionally filtered by country.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
        - $ref: '#/components/parameters/Countries'
      responses:
        '200':
          description: Revenue series grouped by provider.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProviderRevenue'
        '400':
          description: Missing or invalid parameters.
  /api/public/v3/apps/{api_key}/revenue:
    parameters:
      - $ref: '#/components/parameters/ApiKeyPath'
    get:
      operationId: getAppRevenue
      tags: [Revenue]
      summary: Revenue per provider for one app
      description: Returns total revenue per survey provider for a single app over a date range, optionally filtered by country.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
        - $ref: '#/components/parameters/Countries'
      responses:
        '200':
          description: Revenue series grouped by provider.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProviderRevenue'
        '400':
          description: Missing or invalid parameters.
  /api/public/v3/apps/revenuePerCountry:
    get:
      operationId: getAllAppsRevenuePerCountry
      tags: [Revenue]
      summary: Revenue per country for all apps
      description: Returns total revenue per country for all apps over a date range, optionally filtered by country.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
        - $ref: '#/components/parameters/Countries'
      responses:
        '200':
          description: Daily revenue with per-country breakdown.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RevenuePerCountryDay'
        '400':
          description: Missing or invalid parameters.
  /api/public/v3/apps/{api_key}/revenuePerCountry:
    parameters:
      - $ref: '#/components/parameters/ApiKeyPath'
    get:
      operationId: getAppRevenuePerCountry
      tags: [Revenue]
      summary: Revenue per country for one app
      description: Returns total revenue per country for a single app over a date range, optionally filtered by country.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      parameters:
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
        - $ref: '#/components/parameters/Countries'
      responses:
        '200':
          description: Daily revenue with per-country breakdown.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RevenuePerCountryDay'
        '400':
          description: Missing or invalid parameters.
  /api/public/v3/apps/demographics:
    get:
      operationId: getRespondentDemographics
      tags: [Demographics]
      summary: Get respondent demographics
      description: Returns the collected demographic profile for a given respondent device id.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      parameters:
        - name: user
          in: query
          required: true
          description: The device id to fetch demographics for.
          schema:
            type: string
      responses:
        '200':
          description: Demographic profile using Pollfish enumeration codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Demographics'
        '400':
          description: Missing or invalid parameters.
  /api/public/v3/apps/{api_key}/users_log:
    parameters:
      - $ref: '#/components/parameters/ApiKeyPath'
    get:
      operationId: getUsersLog
      tags: [Logs]
      summary: Get user logs
      description: Returns paginated per-user survey logs for a given device_id or request_uuid.
      x-endpoint-status: confirmed
      security:
        - basicAuth: []
      parameters:
        - name: key
          in: query
          required: true
          description: The search term (device_id or request_uuid).
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Page number when results are paginated.
          schema:
            type: integer
        - name: rows
          in: query
          required: false
          description: Number of rows returned.
          schema:
            type: integer
      responses:
        '200':
          description: Paginated survey log results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersLog'
        '400':
          description: Missing or invalid parameters.
  /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:
  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).
  parameters:
    ApiKeyPath:
      name: api_key
      in: path
      required: true
      description: The app's api_key.
      schema:
        type: string
    From:
      name: from
      in: query
      required: false
      description: Start date (ISO 8601 yyyy-MM-dd, UTC). Defaults to one month before `to`. The from/to window must not exceed 31 days.
      schema:
        type: string
        format: date
    To:
      name: to
      in: query
      required: false
      description: End date (ISO 8601 yyyy-MM-dd, UTC). Defaults to the current date.
      schema:
        type: string
        format: date
    Countries:
      name: countries
      in: query
      required: false
      description: Comma-separated ISO Alpha-2 country codes to filter revenue by. Omit for all countries.
      schema:
        type: string
  schemas:
    App:
      type: object
      properties:
        api_key:
          type: string
        id:
          type: integer
        name:
          type: string
        platform:
          type: string
          description: Android, iOS, Windows Phone, or Web.
        category:
          type: string
          description: IAB category code.
        subcategory:
          type: string
        url:
          type: string
        image:
          type: string
        behavior:
          type: integer
        incentive:
          type: boolean
        revenue:
          type: number
          format: float
        short_surveys_enabled:
          type: boolean
        third_party_surveys_enabled:
          type: boolean
        data_collection_surveys_enabled:
          type: boolean
        rewarded_survey:
          $ref: '#/components/schemas/RewardedSurvey'
        offerwall:
          $ref: '#/components/schemas/OfferwallReward'
    AppCreate:
      type: object
      required: [name, category, subcategory, url, platform]
      properties:
        name:
          type: string
        category:
          type: string
        subcategory:
          type: string
        url:
          type: string
        platform:
          type: integer
          description: 0 android, 1 ios, 2 windows phone, 3 web.
        callback_url:
          type: string
          description: URL for server-to-server postback callbacks.
        behavior:
          type: integer
          description: 0 indicators, 1 dynamic (recommended), 2 force slide regularly, 3 force all the time.
        data_collection_surveys_enabled:
          type: boolean
        third_party_surveys_enabled:
          type: boolean
        rewarded_survey:
          $ref: '#/components/schemas/RewardedSurvey'
        offerwall:
          $ref: '#/components/schemas/OfferwallReward'
    AppUpdate:
      type: object
      properties:
        name:
          type: string
        category:
          type: string
        subcategory:
          type: string
        url:
          type: string
        callback_url:
          type: string
        behavior:
          type: integer
        data_collection_surveys_enabled:
          type: boolean
        third_party_surveys_enabled:
          type: boolean
        rewarded_survey:
          $ref: '#/components/schemas/RewardedSurvey'
        offerwall:
          $ref: '#/components/schemas/OfferwallReward'
    RewardedSurvey:
      type: object
      properties:
        currency_name:
          type: string
        variable_amount:
          type: number
          format: float
        fixed_amount:
          type: boolean
    OfferwallReward:
      type: object
      properties:
        currency_name:
          type: string
        variable_amount:
          type: number
          format: float
    NetworkPerformance:
      type: object
      properties:
        name:
          type: string
          description: Survey network name (Pollfish, Cint, Toluna, etc.).
        data:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              served:
                type: integer
              seen:
                type: integer
              accepted:
                type: integer
              completed:
                type: integer
    ProviderRevenue:
      type: object
      properties:
        name:
          type: string
        total:
          type: number
          format: float
        data:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              amount:
                type: number
                format: float
    RevenuePerCountryDay:
      type: object
      properties:
        date:
          type: string
          format: date
        total:
          type: number
          format: float
        countries:
          type: array
          items:
            type: object
            properties:
              iso_code:
                type: string
              amount:
                type: number
                format: float
    Demographics:
      type: object
      description: Demographic enumeration codes; see pollfish.com/docs/demographic-surveys.
      properties:
        device_id:
          type: string
        gender:
          type: integer
        year_of_birth:
          type: integer
        marital_status:
          type: integer
        parental:
          type: integer
        education:
          type: integer
        employment:
          type: integer
        career:
          type: integer
        race:
          type: integer
        income:
          type: integer
    UsersLog:
      type: object
      properties:
        totalCount:
          type: integer
        results:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              survey_started:
                type: integer
                format: int64
                description: Epoch millis when the survey started.
              completed:
                type: boolean
              disqualified_reason:
                type: string
                nullable: true
                description: One of the public termination reasons (Quota Full, Survey Closed, Screenout, Duplicate, VPN, Quality, etc.) or null.
    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]
    OfferwallResponse:
      type: object
      properties:
        surveys:
          type: array
          items:
            $ref: '#/components/schemas/OfferwallSurvey'
        hasDemographics:
          type: boolean
    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