openapi: 3.0.3
info:
  title: Everflow Network API - Traffic Controls
  description: >
    Endpoints for managing network-level traffic controls. Traffic controls
    are rules that filter incoming traffic based on variables like device
    type, geo, or referrer — they help block fraudulent or low-quality
    traffic before it reaches your offers. For a full overview, see the
    [Traffic Controls guide](https://helpdesk.everflow.io/customer/traffic-controls).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Traffic Controls
paths:
  /networks/trafficcontrols:
    get:
      summary: List Traffic Controls
      tags:
        - Traffic Controls
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                traffic_controls:
                  - network_traffic_control_id: 1
                    network_id: 1
                    name: "Block Bad Sources"
                    status: "active"
                    is_apply_all_affiliates: true
                    is_apply_all_offers: true
                    control_type: "blacklist"
                    targeting_action: "block"
                    date_valid_from: ""
                    date_valid_to: ""
                    comparison_method: "exact_match"
                    variables: []
                    time_created: 1774721611
                    time_saved: 1774721611
                    relationship:
                      network_offer_ids: null
                      network_affiliate_ids: null
                      network_advertiser_ids: null
                paging:
                  page: 1
                  page_size: 500
                  total_count: 1
              schema:
                type: object
                properties:
                  traffic_controls:
                    type: array
                    items:
                      $ref: "#/components/schemas/TrafficControl"
                  paging:
                    $ref: "#/components/schemas/Paging"
      security:
        - API Key: []
    post:
      summary: Create Traffic Control
      tags:
        - Traffic Controls
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: "Block Bad Sources"
              status: "active"
              control_type: "blacklist"
              targeting_action: "block"
              comparison_method: "exact_match"
              is_apply_all_affiliates: false
              is_apply_all_offers: false
              variables:
                - "source_id"
                - "sub3"
              network_offer_ids:
                - 5
              network_affiliate_ids:
                - 7
                - 14
                - 21
              network_advertiser_ids: []
              values:
                - "bad_source_1"
                - "bad_source_2"
            schema:
              type: object
              required:
                - name
                - status
                - control_type
                - targeting_action
                - comparison_method
                - is_apply_all_affiliates
                - is_apply_all_offers
                - variables
                - values
              properties:
                name:
                  type: string
                  description: Name of the traffic control.
                status:
                  type: string
                  enum:
                    - active
                    - inactive
                  description: Status of the traffic control.
                control_type:
                  type: string
                  enum:
                    - blacklist
                    - whitelist
                  description: Traffic controls can be either whitelist or blacklist.
                targeting_action:
                  type: string
                  enum:
                    - block
                    - fail_traffic
                  description: The targeting action can be either block or fail_traffic.
                comparison_method:
                  type: string
                  enum:
                    - exact_match
                    - contains
                    - begins_with
                    - ends_with
                    - does_not_contain
                    - does_not_match
                    - is_empty
                  description: Defines how the variables will be compared.
                is_apply_all_affiliates:
                  type: boolean
                  description: >
                    When this is false, the network_affiliate_ids array must be filled.
                is_apply_all_offers:
                  type: boolean
                  description: >
                    When this is false, the network_offer_ids or network_advertiser_ids
                    array must be filled.
                variables:
                  type: array
                  items:
                    type: string
                    enum:
                      - sub1
                      - sub2
                      - sub3
                      - sub4
                      - sub5
                      - sub6
                      - sub7
                      - sub8
                      - sub9
                      - sub10
                      - source_id
                      - referrer
                      - isp
                      - ip
                      - user_agent
                      - country
                      - tracking_domain
                  description: >
                    The click variable that will be looked up and compared to the values supplied.
                    Can be one or multiple values among: `sub1`, `sub2`, `sub3`, `sub4`, `sub5`,
                    `sub6`, `sub7`, `sub8`, `sub9`, `sub10`,
                    `source_id`, `referrer`, `isp`, `ip`, `user_agent`, `country`, `tracking_domain`.
                values:
                  type: array
                  items:
                    type: string
                  description: >
                    The values that the traffic control will filter. Limited to 3000
                    values when using `exact_match` and 100 values otherwise. Please note
                    that when using a whitelist, all values besides the ones specified here
                    will be blocked / sent to fail traffic.
                network_offer_ids:
                  type: array
                  items:
                    type: integer
                  description: >
                    The offers IDs that will be affected by the traffic control (only
                    relevant when `is_apply_all_offers` is set to false).
                network_affiliate_ids:
                  type: array
                  items:
                    type: integer
                  description: >
                    The affiliate IDs that will be affected by the traffic control
                    (only relevant when `is_apply_all_affiliates` is set to false).
                network_advertiser_ids:
                  type: array
                  items:
                    type: integer
                  description: >
                    The advertiser IDs that will be affected by the traffic control
                    (only relevant when `is_apply_all_offers` is set to false). All offers
                    for the specified advertiser IDs will be affected.
                date_valid_from:
                  type: string
                  description: >
                    An optional start date after which the traffic control will be
                    enforced. Use the YYYY-MM-DD format.
                date_valid_to:
                  type: string
                  description: >
                    An optional end date after which the traffic control will no longer
                    be enforced. Use the YYYY-MM-DD format.
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                network_traffic_control_id: 1
                network_id: 1
                name: "Block Bad Sources"
                status: "active"
                is_apply_all_affiliates: true
                is_apply_all_offers: true
                control_type: "blacklist"
                targeting_action: "block"
                date_valid_from: ""
                date_valid_to: ""
                comparison_method: "exact_match"
                variables:
                  - "source_id"
                  - "sub3"
                time_created: 1774721611
                time_saved: 1774721611
                relationship:
                  network_offer_ids: null
                  network_affiliate_ids: null
                  network_advertiser_ids: null
                  values:
                    - "bad_source_1"
                    - "bad_source_2"
              schema:
                $ref: "#/components/schemas/TrafficControl"
      security:
        - API Key: []
  /networks/trafficcontrols/{controlId}:
    get:
      summary: Get Traffic Control
      description: >
        Retrieve a single traffic control by its ID.
      tags:
        - Traffic Controls
      parameters:
        - in: path
          name: controlId
          required: true
          schema:
            type: integer
          description: The unique traffic control ID.
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                network_traffic_control_id: 1
                network_id: 1
                name: "Block Bad Sources"
                status: "active"
                is_apply_all_affiliates: true
                is_apply_all_offers: true
                control_type: "blacklist"
                targeting_action: "block"
                date_valid_from: ""
                date_valid_to: ""
                comparison_method: "exact_match"
                variables:
                  - "source_id"
                  - "sub3"
                time_created: 1774721611
                time_saved: 1774721611
                relationship:
                  network_offer_ids: null
                  network_affiliate_ids: null
                  network_advertiser_ids: null
                  values:
                    - "bad_source_1"
                    - "bad_source_2"
              schema:
                $ref: "#/components/schemas/TrafficControl"
        "404":
          description: Traffic control not found.
      security:
        - API Key: []
    put:
      summary: Update Traffic Control
      description: >
        Update an existing traffic control. This is a full object replacement.
      tags:
        - Traffic Controls
      parameters:
        - in: path
          name: controlId
          required: true
          schema:
            type: integer
          description: The unique traffic control ID to update.
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_traffic_control_id: 1
              name: "Block Bad Sources"
              status: "active"
              control_type: "blacklist"
              targeting_action: "block"
              comparison_method: "exact_match"
              is_apply_all_affiliates: false
              is_apply_all_offers: false
              variables:
                - "source_id"
                - "sub3"
              network_offer_ids:
                - 5
              network_affiliate_ids:
                - 7
                - 14
                - 21
              network_advertiser_ids: []
              values:
                - "bad_source_1"
                - "bad_source_2"
            schema:
              type: object
              required:
                - network_traffic_control_id
                - name
                - status
                - control_type
                - targeting_action
                - comparison_method
                - is_apply_all_affiliates
                - is_apply_all_offers
                - variables
                - values
              properties:
                network_traffic_control_id:
                  type: integer
                  description: The ID of the traffic control to update.
                name:
                  type: string
                  description: Name of the traffic control.
                status:
                  type: string
                  enum:
                    - active
                    - inactive
                  description: >
                    Status of the traffic control. Can be one of the following
                    values: active or inactive.
                control_type:
                  type: string
                  enum:
                    - blacklist
                    - whitelist
                  description: Traffic controls can be either `whitelist` or `blacklist`.
                targeting_action:
                  type: string
                  enum:
                    - block
                    - fail_traffic
                  description: The targeting action can be either `block` or `fail_traffic`.
                comparison_method:
                  type: string
                  enum:
                    - exact_match
                    - contains
                    - begins_with
                    - ends_with
                    - does_not_contain
                    - does_not_match
                    - is_empty
                  description: Defines how the variables will be compared.
                is_apply_all_affiliates:
                  type: boolean
                  description: >
                    When this is false, the `network_affiliate_ids` array must be filled.
                is_apply_all_offers:
                  type: boolean
                  description: >
                    When this is false, the `network_offer_ids` or `network_advertiser_ids`
                    array must be filled.
                variables:
                  type: array
                  items:
                    type: string
                    enum:
                      - sub1
                      - sub2
                      - sub3
                      - sub4
                      - sub5
                      - sub6
                      - sub7
                      - sub8
                      - sub9
                      - sub10
                      - source_id
                      - referrer
                      - isp
                      - ip
                      - user_agent
                      - country
                      - tracking_domain
                  description: >
                    The click variable that will be looked up and compared to the values supplied.
                    Can be one or multiple values among: `sub1`, `sub2`, `sub3`, `sub4`, `sub5`,
                    `sub6`, `sub7`, `sub8`, `sub9`, `sub10`,
                    `source_id`, `referrer`, `isp`, `ip`, `user_agent`, `country`, `tracking_domain`.
                values:
                  type: array
                  items:
                    type: string
                  description: >
                    The values that the traffic control will filter. Limited to 3000
                    values when using `exact_match` and 100 values otherwise. Please note
                    that when using a whitelist, all values besides the ones specified here
                    will be blocked / sent to fail traffic.
                network_offer_ids:
                  type: array
                  items:
                    type: integer
                  description: >
                    The offers IDs that will be affected by the traffic control (only
                    relevant when `is_apply_all_offers` is set to false).
                network_affiliate_ids:
                  type: array
                  items:
                    type: integer
                  description: >
                    The affiliate IDs that will be affected by the traffic control
                    (only relevant when `is_apply_all_affiliates` is set to false).
                network_advertiser_ids:
                  type: array
                  items:
                    type: integer
                  description: >
                    The advertiser IDs that will be affected by the traffic control
                    (only relevant when `is_apply_all_offers` is set to false). All offers
                    for the specified advertiser IDs will be affected.
                date_valid_from:
                  type: string
                  description: >
                    An optional start date after which the traffic control will be
                    enforced. Use the YYYY-MM-DD format.
                date_valid_to:
                  type: string
                  description: >
                    An optional end date after which the traffic control will no longer
                    be enforced. Use the YYYY-MM-DD format.
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                network_traffic_control_id: 1
                network_id: 1
                name: "Block Bad Sources"
                status: "active"
                is_apply_all_affiliates: false
                is_apply_all_offers: false
                control_type: "blacklist"
                targeting_action: "block"
                date_valid_from: ""
                date_valid_to: ""
                comparison_method: "exact_match"
                variables:
                  - "source_id"
                  - "sub3"
                time_created: 1774721611
                time_saved: 1774721633
                relationship:
                  network_offer_ids:
                    - 5
                  network_affiliate_ids:
                    - 7
                    - 14
                    - 21
                  network_advertiser_ids: null
                  values:
                    - "bad_source_1"
                    - "bad_source_2"
              schema:
                $ref: "#/components/schemas/TrafficControl"
        "404":
          description: Traffic control not found.
      security:
        - API Key: []
    delete:
      summary: Delete Traffic Control
      description: >
        Delete an existing traffic control.
      tags:
        - Traffic Controls
      parameters:
        - in: path
          name: controlId
          required: true
          schema:
            type: integer
          description: The unique traffic control ID to delete.
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                success: true
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the deletion was successful.
      security:
        - API Key: []
  /networks/trafficcontrolstable:
    post:
      summary: Find Traffic Controls (Advanced)
      tags:
        - Traffic Controls
      parameters:
        - in: query
          name: page
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: The page of results to retrieve.
        - in: query
          name: page_size
          required: false
          schema:
            type: integer
            minimum: 1
            default: 50
          description: The number of results to return per page.
      requestBody:
        required: true
        content:
          application/json:
            example:
              search_terms:
                - search_type: "name"
                  value: "search query"
              filters:
                status: "active"
                network_offer_ids: [1]
            schema:
              type: object
              properties:
                search_terms:
                  type: array
                  description: Text search filters.
                  items:
                    type: object
                    required:
                      - search_type
                      - value
                    properties:
                      search_type:
                        type: string
                        enum:
                          - name
                        description: >
                          The name of the field used for search. Currently only
                          supports "name".
                      value:
                        type: string
                        description: The value to search.
                filters:
                  type: object
                  description: Filters to narrow down the set of traffic controls returned.
                  properties:
                    status:
                      type: string
                      enum:
                        - active
                        - inactive
                      description: Status of the traffic controls.
                    network_offer_ids:
                      type: array
                      items:
                        type: integer
                      description: >
                        IDs of the offers affected by the traffic controls (traffic
                        controls that apply to all offers will be included).
                    network_affiliate_ids:
                      type: array
                      items:
                        type: integer
                      description: >
                        IDs of the affiliates affected by the traffic controls (traffic
                        controls that apply to all affiliates will be included).
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                controls:
                  - network_traffic_control_id: 1
                    network_id: 1
                    name: "Block Bad Sources"
                    status: "active"
                    is_apply_all_affiliates: true
                    is_apply_all_offers: true
                    control_type: "blacklist"
                    time_created: 1774721611
                    time_saved: 1774721611
                    network_offer_ids: null
                    network_affiliate_ids: null
                    network_advertiser_ids: null
                paging:
                  page: 1
                  page_size: 50
                  total_count: 1
              schema:
                type: object
                properties:
                  controls:
                    type: array
                    items:
                      type: object
                      properties:
                        network_traffic_control_id:
                          type: integer
                        network_id:
                          type: integer
                        name:
                          type: string
                        status:
                          type: string
                        is_apply_all_affiliates:
                          type: boolean
                        is_apply_all_offers:
                          type: boolean
                        control_type:
                          type: string
                        time_created:
                          type: integer
                          example: 1734455015
                        time_saved:
                          type: integer
                          example: 1734455015
                        network_offer_ids:
                          type: array
                          nullable: true
                          items:
                            type: integer
                        network_affiliate_ids:
                          type: array
                          nullable: true
                          items:
                            type: integer
                        network_advertiser_ids:
                          type: array
                          nullable: true
                          items:
                            type: integer
                  paging:
                    $ref: "#/components/schemas/Paging"
      security:
        - API Key: []
components:
  schemas:
    TrafficControl:
      type: object
      properties:
        network_traffic_control_id:
          type: integer
          description: Unique traffic control ID.
        network_id:
          type: integer
          description: Network ID.
        name:
          type: string
          description: Name of the traffic control.
        status:
          type: string
          enum:
            - active
            - inactive
          description: Status of the traffic control.
        control_type:
          type: string
          enum:
            - blacklist
            - whitelist
          description: Traffic controls can be either whitelist or blacklist.
        targeting_action:
          type: string
          enum:
            - block
            - fail_traffic
          description: The targeting action.
        is_apply_all_offers:
          type: boolean
          description: Whether this control applies to all offers.
        is_apply_all_affiliates:
          type: boolean
          description: Whether this control applies to all affiliates.
        comparison_method:
          type: string
          enum:
            - exact_match
            - contains
            - begins_with
            - ends_with
            - does_not_contain
            - does_not_match
            - is_empty
          description: Defines how the variables are compared.
        variables:
          type: array
          items:
            type: string
            enum:
              - sub1
              - sub2
              - sub3
              - sub4
              - sub5
              - sub6
              - sub7
              - sub8
              - sub9
              - sub10
              - source_id
              - referrer
              - isp
              - ip
              - user_agent
              - country
              - tracking_domain
          description: >
            The click variable that will be looked up and compared to the values supplied.
            Can be one or multiple values among: `sub1`, `sub2`, `sub3`, `sub4`, `sub5`,
            `sub6`, `sub7`, `sub8`, `sub9`, `sub10`,
            `source_id`, `referrer`, `isp`, `ip`, `user_agent`, `country`, `tracking_domain`.
            Note: `variables` and `values` are only populated by the Get by ID endpoint.
        relationship:
          type: object
          description: Related entities associated with this traffic control.
          properties:
            network_offer_ids:
              type: array
              items:
                type: integer
              nullable: true
              description: Offer IDs this control applies to.
            network_affiliate_ids:
              type: array
              items:
                type: integer
              nullable: true
              description: Affiliate IDs this control applies to.
            network_advertiser_ids:
              type: array
              items:
                type: integer
              nullable: true
              description: Advertiser IDs this control applies to.
            values:
              type: array
              items:
                type: string
              description: >
                The blocked/allowed values. Only returned by the Find by ID endpoint.
        date_valid_from:
          type: string
          description: Start date for the control's validity period (YYYY-MM-DD).
        date_valid_to:
          type: string
          description: End date for the control's validity period (YYYY-MM-DD).
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of creation.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of last update.
    Paging:
      type: object
      properties:
        page:
          type: integer
          description: Current page number.
        page_size:
          type: integer
          description: Number of items per page.
        total_count:
          type: integer
          description: Total number of items.
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey