openapi: 3.0.3
info:
  title: Everflow Network API - Custom Scrub Rates
  description: >
    Endpoints for managing custom scrub rate (throttle) settings in the Everflow network.
    The scrub rate mechanism automatically rejects a percentage of conversions
    for specific affiliate/offer combinations. For more details, see the
    [Performance Data Adjustments guide](https://helpdesk.everflow.io/customer/performance-data-adjustments-clicks-conversions-revenue-payout).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Custom Scrub Rates
paths:
  /networks/custom/scrubratetable:
    post:
      summary: Find Custom Scrub Rates (Advanced)
      tags:
        - Custom Scrub Rates
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Page number (1-based).
        - in: query
          name: page_size
          schema:
            type: integer
            default: 50
          description: Number of results per page.
        - in: query
          name: relationship
          schema:
            type: string
            enum:
              - all
          description: Set to `all` to include relationship data (affiliate, offer, ruleset) in the response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"
            example:
              filters:
                network_offer_id:
                  values: [100]
                  comparison: "is"
              sort:
                field: "time_created"
                direction: "desc"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  custom_scrub_rate_settings:
                    type: array
                    items:
                      type: object
                      properties:
                        network_custom_scrub_rate_setting_id:
                          type: integer
                          description: Unique custom scrub rate setting ID.
                        network_id:
                          type: integer
                          description: Network ID.
                        network_affiliate_id:
                          type: integer
                          description: Associated affiliate ID.
                        network_offer_id:
                          type: integer
                          description: Associated offer ID.
                        custom_setting_status:
                          type: string
                          enum:
                            - active
                            - inactive
                          description: Setting status.
                        name:
                          type: string
                          description: Display name for this custom scrub rate setting.
                        scrub_rate_status:
                          type: string
                          enum:
                            - rejected
                            - pending
                          description: How the setting affects the conversions it targets.
                        scrub_rate_percentage:
                          type: integer
                          description: The percentage of conversions affected (0-100).
                        time_created:
                          type: integer
                          example: 1734455015
                          description: Unix timestamp of creation.
                        time_saved:
                          type: integer
                          example: 1734455015
                          description: Unix timestamp of last update.
                        relationship:
                          type: object
                          properties:
                            affiliate:
                              type: object
                              properties:
                                network_affiliate_id:
                                  type: integer
                                network_id:
                                  type: integer
                                name:
                                  type: string
                                account_status:
                                  type: string
                            offer:
                              type: object
                              properties:
                                network_offer_id:
                                  type: integer
                                network_id:
                                  type: integer
                                network_advertiser_id:
                                  type: integer
                                network_offer_group_id:
                                  type: integer
                                name:
                                  type: string
                                offer_status:
                                  type: string
                                network_tracking_domain_id:
                                  type: integer
                                visibility:
                                  type: string
                                currency_id:
                                  type: string
                            ruleset:
                              type: object
                              description: >
                                Targeting ruleset applied to this setting. See the
                                [Ruleset guide](/user-guide/rulesets) for details.
                  paging:
                    $ref: "#/components/schemas/Paging"
      security:
        - API Key: []
  /networks/custom/scrubrate:
    post:
      summary: Create Custom Scrub Rate
      tags:
        - Custom Scrub Rates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomScrubRateInput"
            example:
              name: "Scrub Rate for Affiliate 7"
              custom_setting_status: "active"
              scrub_rate_percentage: 10
              scrub_rate_status: "rejected"
              network_affiliate_id: 7
              network_offer_id: 1
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomScrubRate"
      security:
        - API Key: []
  /networks/custom/scrubrate/{settingId}:
    get:
      summary: Get Custom Scrub Rate by ID
      description: >
        Retrieve a single custom scrub rate setting by its ID.
      tags:
        - Custom Scrub Rates
      parameters:
        - in: path
          name: settingId
          required: true
          schema:
            type: integer
          description: The custom scrub rate setting identifier.
        - in: query
          name: relationship
          schema:
            type: string
            enum:
              - all
          description: Set to `all` to include expanded relationship data (`ruleset`, `variables`) in the response. Without this parameter, only `affiliate` and `offer` are returned.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomScrubRate"
      security:
        - API Key: []
    put:
      summary: Update Custom Scrub Rate
      tags:
        - Custom Scrub Rates
      parameters:
        - in: path
          name: settingId
          required: true
          schema:
            type: integer
          description: The custom scrub rate setting identifier.
      requestBody:
        required: true
        content:
          application/json:
            example:
              custom_setting_status: "active"
              scrub_rate_percentage: 10
              scrub_rate_status: "rejected"
              network_offer_id: 1
              network_affiliate_id: 7
            schema:
              $ref: "#/components/schemas/CustomScrubRateInput"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomScrubRate"
      security:
        - API Key: []
    delete:
      summary: Delete Custom Scrub Rate
      tags:
        - Custom Scrub Rates
      parameters:
        - in: path
          name: settingId
          required: true
          schema:
            type: integer
          description: The custom scrub rate setting identifier.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
      security:
        - API Key: []
components:
  schemas:
    CustomScrubRate:
      type: object
      properties:
        network_custom_scrub_rate_setting_id:
          type: integer
          description: Unique custom scrub rate setting ID.
        network_id:
          type: integer
          description: Network ID.
        network_offer_id:
          type: integer
          description: Associated offer ID.
        network_affiliate_id:
          type: integer
          description: Associated affiliate ID.
        name:
          type: string
          description: Display name for this custom scrub rate setting.
        custom_setting_status:
          type: string
          enum:
            - active
            - inactive
          description: Setting status.
        scrub_rate_percentage:
          type: integer
          description: >
            The percentage of conversions that will be affected by this
            setting (0-100). Note that each conversion has the specified
            percentage chance of being scrubbed, rather than guaranteeing
            that exactly that percentage will be scrubbed.
        scrub_rate_status:
          type: string
          enum:
            - rejected
            - pending
          description: >
            How the setting affects the conversions it targets. `pending`
            marks conversions as pending; `rejected` rejects them
            immediately.
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of creation.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of last update.
        relationship:
          type: object
          properties:
            affiliate:
              type: object
              description: Associated affiliate details.
              properties:
                network_affiliate_id:
                  type: integer
                network_id:
                  type: integer
                name:
                  type: string
                account_status:
                  type: string
                network_employee_id:
                  type: integer
                internal_notes:
                  type: string
                has_notifications:
                  type: boolean
                network_traffic_source_id:
                  type: integer
                account_executive_id:
                  type: integer
                adress_id:
                  type: integer
                default_currency_id:
                  type: string
                is_contact_address_enabled:
                  type: boolean
                enable_media_cost_tracking_links:
                  type: boolean
                time_created:
                  type: integer
                  example: 1734455015
                time_saved:
                  type: integer
                  example: 1734455015
                referrer_id:
                  type: integer
            offer:
              type: object
              description: Associated offer details.
              properties:
                network_offer_id:
                  type: integer
                network_id:
                  type: integer
                network_advertiser_id:
                  type: integer
                network_offer_group_id:
                  type: integer
                name:
                  type: string
                offer_status:
                  type: string
                network_tracking_domain_id:
                  type: integer
                visibility:
                  type: string
                currency_id:
                  type: string
            ruleset:
              type: object
              description: >
                Targeting ruleset applied to this setting. Contains geographic,
                device, browser, and connection targeting rules. See the
                [Ruleset guide](/user-guide/rulesets) for details.
            variables:
              type: object
              description: Variable matching rules associated with this scrub rate setting.
              properties:
                total:
                  type: integer
                  description: Total number of variables.
                entries:
                  type: array
                  description: List of variable conditions.
                  items:
                    type: object
                    properties:
                      network_custom_scrub_rate_setting_variable_id:
                        type: integer
                        description: Unique variable ID.
                      network_custom_scrub_rate_setting_id:
                        type: integer
                        description: The parent custom scrub rate setting ID.
                      comparison_method:
                        type: string
                        description: How to compare the variable against the value.
                      variable:
                        type: string
                        description: The parameter name.
                      variable_value:
                        type: string
                        description: The value to compare against.
                      variable_secondary_value:
                        type: string
                        description: A secondary value used with range-based comparisons.
    CustomScrubRateInput:
      type: object
      required:
        - name
        - custom_setting_status
        - scrub_rate_percentage
        - scrub_rate_status
        - network_affiliate_id
        - network_offer_id
      properties:
        network_offer_id:
          type: integer
          description: The offer ID to create this custom scrub rate for.
        network_affiliate_id:
          type: integer
          description: The affiliate ID to apply this custom scrub rate to.
        name:
          type: string
          description: The custom scrub rate setting name.
        custom_setting_status:
          type: string
          enum:
            - active
            - inactive
          description: >
            The custom setting status. Can be either `active` or `inactive`.
        scrub_rate_percentage:
          type: integer
          description: >
            The percentage of conversions that will be affected by this
            setting (0-100). Note that each conversion has the specified
            percentage chance of being scrubbed, rather than guaranteeing
            that exactly that percentage will be scrubbed.
        scrub_rate_status:
          type: string
          enum:
            - rejected
            - pending
          description: >
            Status to assign to scrubbed conversions. `pending` marks
            them as pending for review; `rejected` rejects them immediately.
        variables:
          type: array
          description: >
            Optional list of variables that control which traffic segments
            the scrub rate applies to. Each variable defines a condition
            that must match for this scrub rate setting to take effect.
          items:
            type: object
            required:
              - variable
              - variable_value
              - comparison_method
            properties:
              variable:
                type: string
                enum:
                  - sub1
                  - sub2
                  - sub3
                  - sub4
                  - sub5
                  - sub6
                  - sub7
                  - sub8
                  - sub9
                  - sub10
                  - source_id
                description: >
                  The scrub rate variable name. Identifies which traffic
                  parameter to evaluate.
              variable_value:
                type: string
                description: The value to use for comparison against the variable.
              variable_secondary_value:
                type: string
                description: A secondary value used with range-based comparison methods.
              comparison_method:
                type: string
                enum:
                  - exact_match
                  - contains
                  - begins_with
                  - ends_with
                  - is_present
                description: >
                  The type of comparison to use when matching the variable
                  against the specified value.
        ruleset:
          type: object
          description: >
            Targeting ruleset for this custom scrub rate setting. Allows you to
            restrict when this scrub rate is applied based on geographic,
            device, browser, and connection criteria. See the
            [Ruleset guide](/user-guide/rulesets) for details.
    SearchRequest:
      type: object
      properties:
        search_terms:
          type: array
          description: >
            Optional search terms used to look for specific words in
            setting names, offers, or affiliates.
          items:
            type: object
            required:
              - search_type
              - value
            properties:
              search_type:
                type: string
                enum:
                  - name
                  - offer
                  - affiliate
                description: The field to search on.
              value:
                type: string
                description: The search value.
        filters:
          type: object
          description: >
            Optional filters to narrow down the set of settings returned.
            They can be used individually or combined in a single request.
          properties:
            custom_setting_status:
              type: string
              enum:
                - active
                - inactive
              description: >
                Filter on the status of the custom scrub rate setting.
            network_affiliate_ids:
              type: array
              items:
                type: integer
              description: >
                Return only the settings associated with the specified
                affiliate IDs.
            network_offer_ids:
              type: array
              items:
                type: integer
              description: >
                Return only the settings associated with the specified
                offer IDs.
            scrub_rate_status:
              type: string
              enum:
                - rejected
                - pending
              description: >
                Filter on how the setting affects the conversions it
                targets.
        sort:
          type: object
          properties:
            field:
              type: string
            direction:
              type: string
              enum:
                - asc
                - desc
    Paging:
      type: object
      properties:
        page:
          type: integer
        page_size:
          type: integer
        total_count:
          type: integer
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey