Forsta Sample Marketplace Partner APIs

openapi: 3.0.0
info:
  version: 1.0-beta
  title: Sample Marketplace Partner API Contract
  description: |
    # Summary

    Sample providers that wish to be added to the Forsta Sample Marketplace must implement
    an API following the specifications outlined in this document after obtaining an authentication key from Forsta.

    # Disclaimer

    Subject to the execution of a Non-Disclosure Agreement with FocusVision Worldwide, Inc (“Forsta”), Forsta hereby grants you a limited, revocable, non-exclusive, non-transferable,
    non-sublicensable license during the term of the Agreement to:
    (a) use the API solely for your internal business purposes in developing Your Applications that will communicate and interoperate with the Forsta Offering; and
    (b) display certain Forsta Marks in compliance with usage guidelines that we may specify from time to time solely in connection with the use of the API and the Applications
    and not in connection with the advertising, promotion, distribution, or sale of any other products or services. You acknowledge that there are no implied licenses granted under this Agreement.
    We reserve all rights that are not expressly granted. You may not use the API or any Forsta Mark for any other purpose without our prior written consent.
    You must obtain an API Key through the registration process available to use and access the API. You may not share your API Key with any third party, must keep your API Key and all log-in information secure,
    and must use the API Key as your sole means of accessing the API. Your API Key may be revoked at any time by us.


    # Introduction

    Integration with the Forsta Sample Marketplace provides valuable opportunity to provide sample to Decipher surveys.

    # Qualifications

    Qualifications are used to constrict sample to participants that have specific qualities or traits. Each qualification is introduced in a particular version of the API.

    Qualifications need to match the locale that the sample is intended for. For instance, if a sample is created for en_CA, the qualifications must be from the en_CA qualification list.

    As new qualifications are added to the Forsta Sample Marketplace, the API contract version will have a minor version upgrade. If there are breaking changes such as renaming of a specific qualification or the options of a qualification, a larger change is required and the major version of the API contract will change.

    The schema for each qualification and the version they are added to will be listed below:

    A list of all en_US qualifications are below. For a list of qualifcations for each region, refer to [this](qualification-list) page.

    Qualification | API version added
    --------------|------------------
    [Age and Gender of Child](/static/media/questions/en_US/child_ages.yml) | [1.0-beta](#) |  [Translation]()
    [Age](/static/media/questions/en_US/age.yml) | [1.0-beta](#) |  [Translation]()
    [Auto Purchase Type](/static/media/questions/en_US/auto_purchase_type.yml) | [1.0-beta](#) |  [Translation]()
    [Business Decision Maker](/static/media/questions/en_US/department_decision_maker.yml) | [1.0-beta](#) |  [Translation]()
    [Cell Carrier US](/static/media/questions/en_US/cell_carrier_us.yml) | [1.0-beta](#) |  [Translation]()
    [Cell Carrier](/static/media/questions/en_US/cell_carrier.yml) | [1.0-beta](#) |  [Translation]()
    [Department](/static/media/questions/en_US/employee_dept.yml) | [1.0-beta](#) |  [Translation]()
    [Division](/static/media/questions/en_US/division.yml) | [1.0-beta](#) |  [Translation]()
    [DMA](/static/media/questions/en_US/dma.yml) | [1.0-beta](#) |  [Translation]()
    [Education](/static/media/questions/en_US/education.yml) | [1.0-beta](#) |  [Translation]()
    [Education 2](/static/media/questions/en_US/education_v2.yml) | [1.0-beta](#) |  [Translation]()
    [Employment](/static/media/questions/en_US/employment.yml) | [1.0-beta](#) |  [Translation]()
    [Ethnicity](/static/media/questions/en_US/ethnicity.yml) | [1.0-beta](#) |  [Translation]()
    [Gender](/static/media/questions/en_US/gender.yml) | [1.0-beta](#) |  [Translation]()
    [Grocery Shopper](/static/media/questions/en_US/grocery_shopper.yml) | [1.0-beta](#) |  [Translation]()
    [Hispanic](/static/media/questions/en_US/hispanic.yml) | [1.0-beta](#) |  [Translation]()
    [Home Owner](/static/media/questions/en_US/home_owner.yml) | [1.0-beta](#) |  [Translation]()
    [Household Responsibility](/static/media/questions/en_US/hh_responsibility.yml) | [1.0-beta](#) |  [Translation]()
    [Income](/static/media/questions/en_US/income.yml) | [1.0-beta](#) |  [Translation]()
    [Industry within Household](/static/media/questions/en_US/household_industry.yml) | [1.0-beta](#) |  [Translation]()
    [Job Title](/static/media/questions/en_US/job_title.yml) | [1.0-beta](#) |  [Translation]()
    [Mobile](/static/media/questions/en_US/mobile.yml) | [1.0-beta](#) |  [Translation]()
    [Organization Income](/static/media/questions/en_US/org_income.yml) | [1.0-beta](#) |  [Translation]()
    [Organization Size](/static/media/questions/en_US/org_census.yml) | [1.0-beta](#) |  [Translation]()
    [Parent](/static/media/questions/en_US/has_children.yml) | [1.0-beta](#) |  [Translation]()
    [Pets](/static/media/questions/en_US/pets.yml) | [1.0-beta](#) |  [Translation]()
    [Primary Decision Maker](/static/media/questions/en_US/primary_decision_maker.yml) | [1.0-beta](#) |  [Translation]()
    [Profession](/static/media/questions/en_US/personal_industry.yml) | [1.0-beta](#) |  [Translation]()
    [Region](/static/media/questions/en_US/region.yml) | [1.0-beta](#) |  [Translation]()
    [Spanish Speaking](/static/media/questions/en_US/spanish_speaking.yml) | [1.0-beta](#) |  [Translation]()
    [State](/static/media/questions/en_US/state.yml) | [1.0-beta](#) |  [Translation]()
    [Tablet](/static/media/questions/en_US/tablet.yml) | [1.0-beta](#) |  [Translation]()
    [Urban Rural](/static/media/questions/en_US/urban_rural.yml) | [1.0-beta](#) |  [Translation]()
    [Webcam](/static/media/questions/en_US/webcam.yml) | [1.0-beta](#) |  [Translation]()
    [Zip Code](/static/media/questions/en_US/zip.yml) | [1.0-beta](#) |  [Translation]()


    # API Workflow

    <ol>
      <li>
      The `/estimates` endpoint is always requested before any other endpoint, the result of which will be included
      in the bid results page of the Sample Marketplace. The user may select a bid result from any provider they wish to purchase from
      at this point.
      </li>
      <li>
      Whichever provider the user selects is then used to create a new sample. If there is no project already made
      for this provider for the survey the user is purchasing sample for, one will be created using the `/projects`
      endpoint, otherwise the same project id is used that is already tied to the survey.
      </li>
      <li>
      A new sample is then created using the `/samples` endpoint with the same specifications provided by the user
      that were previously used to obtain the feasibility estimate. The sample is created using the project id obtained
      from the previous step.
      </li>
      <li>
      Once the user is ready to begin receiving participants in the Decipher survey, they will finalize their sample selection and the sample status will be set to live using the `/samples`
      endpoint.
      </li>
    </ol>

    # Test Runner

    To validate the implementation of the API Contract, we will use a test runner.
    This test runner has been made publicly available [here](http://smp-docs-fvdev.s3-website-us-west-2.amazonaws.com/test-runner.zip).
    We will use this test runner to ensure that each of the endpoints work as expected.

    All requests that come from the test runner include the header <b>"X-FV-TEST"</b> with a value of "true" to enable
    the ability to differentiate fake requests from real requests.
    For more information on how to run the test runner, refer to the readme within the zipped test runner.
tags:
  - name: OAuth2
    description: The OAuth2 resources are used to validate authentication tokens to allow communication between the applications.
  - name: Estimates
    description: The Estimate resources are used to determine the pricing and feasibility of a potential sample bid. The Forsta Sample Marketplace expects responses to these calls within 10 seconds before terminating the request. If the sample's quota is unable to be fufilled, a null price in the result object should be returned.
  - name: Projects
    description: The Project resources are used to create organizational containers for Samples. The Forsta Sample Marketplace expects responses to these calls within 10 seconds before terminating the request.
  - name: Samples
    description: The Sample resources are used to create or alter sample purchases.  The Forsta Sample Marketplace expects responses to these calls within 10 seconds before terminating the request.
paths:
  /oauth2/token:
    post:
      summary: Client Credentials Access Token
      tags:
        - OAuth2
      description: This is used to gain an access token to use for the rest of the APIs following the <a href="https://tools.ietf.org/html/rfc6749#section-4.4">Client Credentials Grant</a> flow of the OAuth2 spec. Authorization used for this endpoint should be of the form `Basic Base64Encode(client_id:client_secret)`. We will use your client_id and client_secret that is set in the apispec endpoint in the partner signup process.
      security:
        - BasicAuth: []
      operationId: demo.post_token
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /estimates:
    post:
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/EstimateBody'
      tags:
        - Estimates
      summary: Sample Estimates
      description: Endpoint that returns an estimated cost for a potential sample. If the sample's quota is unable to be fufilled, a null price in the result object should be returned.
      security:
        - OAuth2: []
      operationId: demo.post_estimate
      responses:
        '200':
          description: Estimate created
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      result:
                        type: object
                        properties:
                          price:
                            type: number
                            description: The expected price per complete for each participant.
                            example: 2.5
                  - $ref: '#/components/schemas/EstimateBody'
        '401':
          $ref: '#/components/responses/401'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /projects/{project_id}:
    get:
      parameters:
        - name: project_id
          in: path
          required: true
          example: f7694b5e-3f50-4bb6-b307-f68b0fe111aa
          description: The ID tied to a specific project.
          schema:
            type: string
      tags:
        - Projects
      summary: Get project data
      security:
        - OAuth2: []
      operationId: demo.get_project
      responses:
        '200':
          description: Project data retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Projects'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    patch:
      parameters:
        - name: project_id
          in: path
          required: true
          example: f7694b5e-3f50-4bb6-b307-f68b0fe111aa
          description: The ID tied to a specific project.
          schema:
            type: string
      operationId: demo.patch_project
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  properties:
                    name:
                      type: string
                      example: Myke's Project
                      description: The name used to identify the project.
      tags:
        - Projects
      summary: Update project data
      security:
        - OAuth2: []
      responses:
        '200':
          description: Project updated
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Projects'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /projects:
    post:
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  properties:
                    name:
                      type: string
                      example: Myke's Project
                      description: The name associated with the project. For organizational purposes.
      tags:
        - Projects
      summary: Create project
      security:
        - OAuth2: []
      operationId: demo.post_project
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Projects'
        '401':
          $ref: '#/components/responses/401'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /samples/{sample_id}:
    get:
      parameters:
        - name: sample_id
          in: path
          required: true
          schema:
            type: string
            example: 18ebed02-6e91-4504-af97-a83c103dca41
            description: The UUID (an immutable ID tied to a specific resource) tied to a specific example.
      tags:
        - Samples
      summary: Get sample data
      security:
        - OAuth2: []
      operationId: demo.get_sample
      responses:
        '200':
          description: Sample retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SampleOutput'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    patch:
      parameters:
        - name: sample_id
          in: path
          required: true
          example: 18ebed02-6e91-4504-af97-a83c103dca41
          description: The UUID (an immutable ID tied to a specific resource) used to identify a particular sample.
          schema:
            type: string
      operationId: demo.patch_sample
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  properties:
                    name:
                      type: string
                      example: CSAT Survey
                      description: A name used to identfiy the survey.
                    live_url:
                      type: string
                      example: https://release.decipherinc.com/survey/demo/dashboard
                      description: The full URL to the live survey to receive participants. Required if setting sample to the live state.
                      format: URI
                    status:
                      type: string
                      example: live
                      description: The status of this sample
                      enum:
                        - pending
                        - live
                        - paused
                        - closed
                        - deleted
      tags:
        - Samples
      summary: Update sample
      security:
        - OAuth2: []
      responses:
        '200':
          description: Sample patched
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SampleOutput'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /samples:
    post:
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Sample'
      tags:
        - Samples
      summary: Create Sample
      security:
        - OAuth2: []
      operationId: demo.post_sample
      responses:
        '201':
          description: Sample created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SampleOutput'
        '401':
          $ref: '#/components/responses/401'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: See https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token/
          scopes: {}
      x-tokenInfoFunc: demo.token_auth
    BasicAuth:
      type: http
      scheme: basic
      x-basicInfoFunc: demo.basic_auth
  schemas:
    Projects:
      type: object
      properties:
        name:
          type: string
          example: Myke's Projects
          description: The name of the project.
        project_id:
          type: string
          example: f7694b5e-3f50-4bb6-b307-f68b0fe111aa
          description: The unique identifier of the project.
    EstimateBody:
      type: object
      required:
        - quantity
        - days
        - incidence
        - pii
        - locale
        - length_of_interview
        - currency
        - category
      properties:
        incidence:
          type: integer
          example: 50
          description: Incidence or Qualifying Rate is the expected percentage of persons eligible to participate in a survey within a given population.
          minimum: 1
          maximum: 100
        pii:
          type: boolean
          example: true
          description: Boolean used to determine if the survey intends to collect personally identifiable information.
        days:
          type: integer
          example: 5
          description: Number of days the survey will be fielded.
          minimum: 1
        length_of_interview:
          type: integer
          example: 20
          description: Number in minutes the average respondent will take to finish the survey.
          minimum: 1
        category:
          type: string
          example: Business
          description: The category in which best describes the topic of the survey.
          enum:
            - No Selection
            - Automotive
            - Beauty/Costmetics
            - Beverages - Alcoholic
            - Beverages - Non-alcoholic
            - Business
            - Children & Parenting
            - Coalition/Loyalty Programs
            - Credit Cards
            - Destinations & Tourism
            - Education
            - Electronics/Computer/Software
            - Entertainment & Leisure
            - Explicit Content
            - Fashion & Clothing - Department Store
            - Fashion & Clothing - Other
            - Finance, Banking Investing & Insurance
            - Food/Snacks
            - Gambling/Lottery
            - Government & Politics
            - Heathcare/Pharmaceuticals
            - Home (Utilities, Appliances)
            - Home Entertainment (DVD, VHS)
            - Home Improvement/Real Estate/Construction
            - IT (Servers, Databases, etc)
            - Media & Publishing
            - Personal Care/Toiletries
            - Pets
            - Restaurants
            - Sensitive Content
            - Smoking/Tobacco
            - Social Research
            - Sports, Recreation, Fitness
            - Telecommunications (phone, cell phone, cable)
            - Toys
            - Transportation
            - Travel - Airlines
            - Travel - Hotels
            - Travel Services/Agency/Booking
            - Video Games
            - Websites/Internet/E-Commerce
        locale:
          type: string
          example: en_US
          enum:
            - de_DE
            - en_CA
            - en_GB
            - en_US
            - es_ES
            - fr_FR
            - it_IT
            - pt_BR
          description: The locale to describe the language and location of the survey.
        quantity:
          type: integer
          example: 5000
          description: The total number participants in the sample that are purchased.
          minimum: 1
        currency:
          type: string
          example: USD
          description: The type of currency to use to pay for the Sample.
          enum:
            - USD
        qualifications:
          type: array
          description: Demographic criteria required for panelists.
          items:
            anyOf:
              - $ref: '#/components/schemas/en_US_Qualifications'
              - $ref: '#/components/schemas/en_CA_Qualifications'
              - $ref: '#/components/schemas/en_GB_Qualifications'
              - $ref: '#/components/schemas/es_ES_Qualifications'
              - $ref: '#/components/schemas/fr_FR_Qualifications'
              - $ref: '#/components/schemas/it_IT_Qualifications'
              - $ref: '#/components/schemas/pt_BR_Qualifications'
          example:
            - question_id: age
              answers:
                - 18
                - 19
                - 20
                - 21
                - 22
                - 23
                - 24
            - question_id: income
              answers:
                - Less than $14,999
                - $15,000 to $19,999
                - $20,000 to $24,999
                - $25,000 to $29,999
                - $30,000 to $34,999
                - $35,000 to $39,999
                - $40,000 to $44,999
                - $45,000 to $49,999
        quotas:
          allOf:
            - $ref: '#/components/schemas/Quotas'
          example:
            - quantity: 3000
              qualifications:
                question_id: age
                answers:
                  - 18
                  - 19
                  - 20
            - quantity: 2000
              qualifications:
                question_id: age
                answers:
                  - 21
                  - 22
                  - 23
                  - 24
            - quantity: 500
              qualifications:
                question_id: income
                answers:
                  - Less than $14,999
    de_DE_Qualifications:
      type: array
      description: Demographic criteria required for panelists.
      items:
        anyOf:
          - $ref: '#/components/schemas/age-6'
          - $ref: '#/components/schemas/education-7'
          - $ref: '#/components/schemas/employment-5'
          - $ref: '#/components/schemas/gender-5'
          - $ref: '#/components/schemas/hhi_combined-6'
          - $ref: '#/components/schemas/hhi-6'
          - $ref: '#/components/schemas/mobile'
          - $ref: '#/components/schemas/region-5'
          - $ref: '#/components/schemas/tablet'
    en_CA_Qualifications:
      type: array
      description: Demographic criteria required for panelists.
      items:
        anyOf:
          - $ref: '#/components/schemas/age-2'
          - $ref: '#/components/schemas/b2b_decision_maker'
          - $ref: '#/components/schemas/education-2'
          - $ref: '#/components/schemas/employment'
          - $ref: '#/components/schemas/gender'
          - $ref: '#/components/schemas/hhi_combined'
          - $ref: '#/components/schemas/hhi'
          - $ref: '#/components/schemas/mobile'
          - $ref: '#/components/schemas/province'
          - $ref: '#/components/schemas/tablet'
    en_GB_Qualifications:
      type: array
      description: Demographic criteria required for panelists.
      items:
        anyOf:
          - $ref: '#/components/schemas/age_and_gender_of_child'
          - $ref: '#/components/schemas/age-2'
          - $ref: '#/components/schemas/b2b_decision_maker'
          - $ref: '#/components/schemas/company_department'
          - $ref: '#/components/schemas/company_revenue'
          - $ref: '#/components/schemas/county'
          - $ref: '#/components/schemas/education-3'
          - $ref: '#/components/schemas/employment'
          - $ref: '#/components/schemas/gender'
          - $ref: '#/components/schemas/hhi_combined-2'
          - $ref: '#/components/schemas/hhi-2'
          - $ref: '#/components/schemas/industry_personal'
          - $ref: '#/components/schemas/industry'
          - $ref: '#/components/schemas/job_title'
          - $ref: '#/components/schemas/mobile'
          - $ref: '#/components/schemas/no_of_employees'
          - $ref: '#/components/schemas/parental_status_standard'
          - $ref: '#/components/schemas/region-2'
          - $ref: '#/components/schemas/tablet'
    en_US_Qualifications:
      type: array
      description: Demographic criteria required for panelists.
      items:
        anyOf:
          - $ref: '#/components/schemas/age'
          - $ref: '#/components/schemas/auto_purchase_type'
          - $ref: '#/components/schemas/cell_carrier_us'
          - $ref: '#/components/schemas/cell_carrier'
          - $ref: '#/components/schemas/department_decision_maker'
          - $ref: '#/components/schemas/employee_dept'
          - $ref: '#/components/schemas/division'
          - $ref: '#/components/schemas/dma'
          - $ref: '#/components/schemas/education_v2'
          - $ref: '#/components/schemas/education'
          - $ref: '#/components/schemas/employment'
          - $ref: '#/components/schemas/ethnicity'
          - $ref: '#/components/schemas/gender'
          - $ref: '#/components/schemas/grocery_shopper'
          - $ref: '#/components/schemas/hispanic'
          - $ref: '#/components/schemas/home_owner'
          - $ref: '#/components/schemas/hh_responsibility'
          - $ref: '#/components/schemas/income'
          - $ref: '#/components/schemas/household_industry'
          - $ref: '#/components/schemas/job_title'
          - $ref: '#/components/schemas/mobile'
          - $ref: '#/components/schemas/child_ages'
          - $ref: '#/components/schemas/org_income'
          - $ref: '#/components/schemas/org_census'
          - $ref: '#/components/schemas/has_children'
          - $ref: '#/components/schemas/pets'
          - $ref: '#/components/schemas/primary_decision_maker'
          - $ref: '#/components/schemas/personal_industry'
          - $ref: '#/components/schemas/region'
          - $ref: '#/components/schemas/spanish_speaking'
          - $ref: '#/components/schemas/tablet'
          - $ref: '#/components/schemas/urban_rural'
          - $ref: '#/components/schemas/webcam'
          - $ref: '#/components/schemas/zip'
    es_ES_Qualifications:
      type: array
      description: Demographic criteria required for panelists.
      items:
        anyOf:
          - $ref: '#/components/schemas/age-3'
          - $ref: '#/components/schemas/education-4'
          - $ref: '#/components/schemas/employment-2'
          - $ref: '#/components/schemas/gender-2'
          - $ref: '#/components/schemas/hhi_combined-3'
          - $ref: '#/components/schemas/hhi-3'
          - $ref: '#/components/schemas/mobile'
          - $ref: '#/components/schemas/tablet'
    fr_FR_Qualifications:
      type: array
      description: Demographic criteria required for panelists.
      items:
        anyOf:
          - $ref: '#/components/schemas/age-4'
          - $ref: '#/components/schemas/education-5'
          - $ref: '#/components/schemas/employment-3'
          - $ref: '#/components/schemas/gender-3'
          - $ref: '#/components/schemas/hhi_combined-4'
          - $ref: '#/components/schemas/hhi-4'
          - $ref: '#/components/schemas/mobile'
          - $ref: '#/components/schemas/region-3'
          - $ref: '#/components/schemas/tablet'
    it_IT_Qualifications:
      type: array
      description: Demographic criteria required for panelists.
      items:
        anyOf:
          - $ref: '#/components/schemas/age-5'
          - $ref: '#/components/schemas/education-6'
          - $ref: '#/components/schemas/employment-4'
          - $ref: '#/components/schemas/gender-4'
          - $ref: '#/components/schemas/hhi_combined-5'
          - $ref: '#/components/schemas/hhi-5'
          - $ref: '#/components/schemas/mobile'
          - $ref: '#/components/schemas/region-4'
          - $ref: '#/components/schemas/tablet'
    pt_BR_Qualifications:
      type: array
      description: Demographic criteria required for panelists.
      items:
        anyOf:
          - $ref: '#/components/schemas/age-5'
          - $ref: '#/components/schemas/education-6'
          - $ref: '#/components/schemas/employment-4'
          - $ref: '#/components/schemas/gender-4'
          - $ref: '#/components/schemas/hhi_combined-5'
          - $ref: '#/components/schemas/hhi-5'
          - $ref: '#/components/schemas/mobile'
          - $ref: '#/components/schemas/region-4'
          - $ref: '#/components/schemas/tablet'
    Quotas:
      description: A quota is defined by a set of qualifications and a complete count.
      type: array
      items:
        type: object
        properties:
          quantity:
            type: integer
            description: The number of qualified participants to be accepted.
            example: 100
            minimum: 1
          qualifications:
            items:
              anyOf:
                - $ref: '#/components/schemas/en_US_Qualifications'
                - $ref: '#/components/schemas/en_CA_Qualifications'
                - $ref: '#/components/schemas/en_GB_Qualifications'
                - $ref: '#/components/schemas/es_ES_Qualifications'
                - $ref: '#/components/schemas/fr_FR_Qualifications'
                - $ref: '#/components/schemas/it_IT_Qualifications'
                - $ref: '#/components/schemas/pt_BR_Qualifications'
            description: Demographic criteria required for panelists.
    Sample:
      allOf:
        - $ref: '#/components/schemas/EstimateBody'
      required:
        - name
        - cpi
        - project_id
      properties:
        name:
          type: string
          example: CSAT Survey
          description: A name used to identfiy the survey.
          maximum: 255
        cpi:
          type: number
          example: 2.5
          description: The price per complete in the currency designated.
          minimum: 0
        live_url:
          type: string
          example: https://release.decipherinc.com/survey/demo/dashboard
          description: The full URL to the live survey to receive participants. Required if setting sample to the live state.
          format: URI
        project_id:
          type: string
          example: f7694b5e-3f50-4bb6-b307-f68b0fe111aa
          description: The UUID (an immutable ID tied to a specific resource) tied to a specific project ID.
    SampleOutput:
      allOf:
        - $ref: '#/components/schemas/Sample'
        - type: object
          properties:
            id:
              type: string
              example: 18ebed02-6e91-4504-af97-a83c103dca41
              description: The UUID (an immutable ID tied to a specific resource) tied to a specific example.

# --- truncated at 32 KB (117 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/forsta/refs/heads/main/openapi/forsta-sample-marketplace-partner-contract-openapi.yml