openapi: 3.0.3
info:
  title: Everflow Network API - Smart Links
  description: >
    Endpoints for managing smart links (campaigns) in the Everflow network.
    Smart links bundle multiple offers into a single tracking link and
    automatically route traffic to the best-matching offer, ensuring
    efficient distribution across your offer portfolio. For concepts and
    setup, see the [Smart Links guide](https://helpdesk.everflow.io/customer/smart-links-kpi-optimization).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Smart Links
paths:
  /networks/campaigns:
    get:
      summary: List Smart Links
      tags:
        - Smart Links
      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:
              - reporting
              - redirects
              - offers
              - catch_all_offer_basic
          description: Include related data. Repeat for multiple relationships.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    type: array
                    items:
                      $ref: "#/components/schemas/SmartLink"
      security:
        - API Key: []
    post:
      summary: Create Smart Link
      tags:
        - Smart Links
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/SmartLinkInput"
                - required:
                    - campaign_name
                    - campaign_status
                    - network_tracking_domain_id
                    - is_use_secure_link
                    - redirect_routing_type
                    - is_open_to_affiliates
                    - redirects
                    - labels
            example:
              campaign_status: "active"
              redirect_routing_type: "priority"
              campaign_name: "My Smart Link"
              catch_all_network_offer_id: 1
              network_tracking_domain_id: 1
              redirects:
                - redirect_network_offer_id: 1
                  redirect_network_offer_url_id: 0
                  routing_value: 1
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SmartLink"
      security:
        - API Key: []
  /networks/campaigns/{campaignId}:
    get:
      summary: Get Smart Link by ID
      tags:
        - Smart Links
      parameters:
        - in: path
          name: campaignId
          required: true
          schema:
            type: integer
          description: The smart link (campaign) identifier.
        - in: query
          name: relationship
          schema:
            type: string
            enum:
              - reporting
              - redirects
              - offers
              - catch_all_offer_basic
          description: Include related data. Repeat for multiple relationships.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SmartLink"
      security:
        - API Key: []
    put:
      summary: Update Smart Link
      tags:
        - Smart Links
      parameters:
        - in: path
          name: campaignId
          required: true
          schema:
            type: integer
          description: The smart link (campaign) identifier.
      requestBody:
        required: true
        content:
          application/json:
            example:
              campaign_status: "active"
              redirect_routing_type: "priority"
              campaign_name: "My Smart Link"
              catch_all_network_offer_id: 1
              network_tracking_domain_id: 1
              is_use_secure_link: false
              is_open_to_affiliates: true
              redirects:
                - redirect_network_offer_id: 1
                  redirect_network_offer_url_id: 0
                  routing_value: 1
            schema:
              allOf:
                - $ref: "#/components/schemas/SmartLinkInput"
                - required:
                    - campaign_name
                    - campaign_status
                    - network_tracking_domain_id
                    - is_use_secure_link
                    - redirect_routing_type
                    - is_open_to_affiliates
                    - redirects
                    - labels
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SmartLink"
      security:
        - API Key: []
components:
  schemas:
    SmartLink:
      type: object
      properties:
        network_campaign_id:
          type: integer
          example: 1
          description: Unique smart link (campaign) ID.
        network_id:
          type: integer
          example: 1
          description: Network ID.
        campaign_name:
          type: string
          example: "My Smart Link"
          description: The displayed name of the smart link.
        campaign_status:
          type: string
          example: "active"
          enum:
            - active
            - paused
            - deleted
          description: Status of the smart link.
        network_tracking_domain_id:
          type: integer
          example: 1
          description: The ID of the domain used in the affiliate tracking link.
        is_use_secure_link:
          type: boolean
          example: false
          description: Whether SSL is forced on tracking links.
        redirect_routing_type:
          type: string
          example: "weight"
          enum:
            - priority
            - weight
            - kpi
          description: >
            Determines how the Smart Link traffic is distributed between the listed offers.
            `kpi` automatically delivers traffic ranked by the best performing offers for your set KPI.
            `priority` checks the first position and continues downward if the user doesn't match targeting/cap.
            `weight` delivers traffic with a percentage split between eligible offers.
        catch_all_network_offer_id:
          type: integer
          example: 57
          description: >
            The ID of the offer to use as the catch-all offer. The Catch-All Offer will be considered
            only if the partner has access to the offer and the click can't be matched with any of the
            offers in the redirect tree.
        is_open_to_affiliates:
          type: boolean
          example: false
          description: >
            Whether the smart link is visible to affiliates. If enabled, the Smart Link will be visible
            to the partner only if all the offers in the redirect tree are runnable by the partner.
        run_frequency:
          type: string
          example: "unknown"
          enum:
            - unknown
            - 1_hours
            - 3_hours
            - 6_hours
            - 12_hours
            - 24_hours
          description: >
            Determines how often your offers are re-ranked based on the best performing offers towards
            your KPI. Required if `redirect_routing_type` is set to `kpi`.
        metric:
          type: string
          example: "unknown"
          enum:
            - unknown
            - profit
            - cvr
            - evr
            - conversions
            - payout
            - revenue
            - rpc
            - cpc
            - epc
          description: >
            The metric used with the KPI campaign. The highest performing offers for your selected metric
            will be re-ranked towards receiving the majority of the Smart Link traffic. Required if
            `redirect_routing_type` is set to `kpi`.
        optimization_goal:
          type: number
          example: 0
          description: >
            Optimizes ranking towards the offers that are closest to your set Specific Goal.
            Required if `redirect_routing_type` is set to `kpi`.
        data_lookback_window:
          type: string
          example: "unknown"
          enum:
            - unknown
            - 12_hours
            - 24_hours
            - 48_hours
          description: >
            Determines the period of data used for evaluating how offers are performing at your set Metric.
            Can be `12_hours`, `24_hours`, or `48_hours`. Required if `redirect_routing_type` is set to `kpi`.
        data_collection_threshold:
          type: integer
          example: 0
          description: >
            The amount of data (in clicks) required before the KPI-based Smart Link starts determining the initial
            rankings for the best performing offers. Required if `redirect_routing_type` is set to `kpi`.
        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:
            redirects:
              type: object
              description: Paginated list of redirects (offers) in this smart link.
              properties:
                total:
                  type: integer
                entries:
                  type: array
                  items:
                    $ref: "#/components/schemas/Redirect"
            labels:
              type: object
              description: Paginated list of labels for this smart link.
              properties:
                total:
                  type: integer
                entries:
                  type: array
                  items:
                    type: string
            catch_all_offer_basic:
              type: object
              description: Basic info about the catch-all offer, if set.
              properties:
                network_offer_id:
                  type: integer
                network_id:
                  type: integer
                name:
                  type: string
                offer_status:
                  type: string
            encoded_value:
              type: string
              description: Encoded tracking value.
    SmartLinkInput:
      type: object
      properties:
        campaign_name:
          type: string
          description: The displayed name of the smart link.
        campaign_status:
          type: string
          enum:
            - active
            - paused
            - deleted
          description: Status of the smart link.
        network_tracking_domain_id:
          type: integer
          description: The ID of the domain to be used in the affiliate tracking link.
        is_use_secure_link:
          type: boolean
          description: >
            Whether to force SSL. Improves tracking and security by setting tracking
            links to always use HTTPS instead of HTTP.
        redirect_routing_type:
          type: string
          enum:
            - priority
            - weight
            - kpi
          description: >
            The redirect mechanism of the campaign. Determines how the Smart Link
            traffic is distributed between the listed offers. KPI automatically
            delivers traffic ranked by the best performing offers for your set KPI.
            Priority checks the first position and continues downward if the user
            doesn't match targeting/cap. Weight delivers traffic with a percentage
            split between eligible offers.
        catch_all_network_offer_id:
          type: integer
          description: >
            The ID of the offer to use as the catch-all offer. The Catch-All Offer
            will be considered only if the partner has access to the offer and the
            click can't be matched with any of the offers in the redirect tree.
        is_open_to_affiliates:
          type: boolean
          description: >
            Whether to make the campaign visible to affiliates. If enabled, the
            Smart Link will be visible to the partner only if all the offers are
            runnable by the partner.
        run_frequency:
          type: string
          enum:
            - unknown
            - 12_hours
            - 24_hours
            - 6_hours
            - 3_hours
            - 1_hours
          description: >
            Determines how often your offers are re-ranked based on the best performing offers towards
            your KPI. Required if `redirect_routing_type` is set to `kpi`.
        metric:
          type: string
          enum:
            - unknown
            - profit
            - cvr
            - evr
            - conversions
            - payout
            - revenue
            - rpc
            - cpc
            - epc
          description: >
            The metric used with the KPI campaign. The highest performing offers for your selected metric
            will be re-ranked towards receiving the majority of the Smart Link traffic. Required if
            `redirect_routing_type` is set to `kpi`.
        optimization_goal:
          type: number
          description: >
            Optimizes ranking towards the offers that are closest to your set Specific Goal.
            Required if `redirect_routing_type` is set to `kpi`.
        data_lookback_window:
          type: string
          enum:
            - unknown
            - 12_hours
            - 24_hours
            - 48_hours
          description: >
            Determines the period of data used for evaluating how offers are performing at your set Metric.
            Can be `12_hours`, `24_hours`, or `48_hours`. Required if `redirect_routing_type` is set to `kpi`.
        data_collection_threshold:
          type: integer
          description: >
            The amount of data required before the KPI-based Smart Link starts determining the initial
            rankings for the best performing offers. Required if `redirect_routing_type` is set to `kpi`.
        redirects:
          type: array
          items:
            $ref: "#/components/schemas/RedirectInput"
        conversion_method:
          type: string
          enum:
            - server_postback
            - pixel_tracking
          description: Conversion tracking method for the smart link.
        is_whitelist_check_enabled:
          type: boolean
          description: Whether to enforce whitelist checking for affiliates on this smart link.
        labels:
          type: array
          items:
            type: string
          description: Labels to associate with the smart link.
    Redirect:
      type: object
      properties:
        network_campaign_redirect_id:
          type: integer
          example: 6
          description: Unique redirect ID.
        network_campaign_id:
          type: integer
          example: 1
          description: The smart link (campaign) ID this redirect belongs to.
        redirect_network_offer_id:
          type: integer
          example: 11
          description: The ID of the offer.
        redirect_network_offer_url_id:
          type: integer
          example: 0
          description: >
            The ID of an offer URL. Use `0` to default to the Base Destination URL.
        routing_value:
          type: integer
          example: 1
          description: >
            The value used to determine the priority or the weight of the
            offer in the list. For `priority`, the evaluation order starting at 1.
            For `weight`, the offer's share of traffic relative to the sum of all
            redirect weights (weights 99 and 1 split traffic 99% / 1%); `0` keeps
            the offer on the smart link without sending it traffic. For `kpi`, the
            optimizer assigns this value after each run.
        ruleset:
          type: object
          description: >
            Targeting rules for this redirect. When empty, no targeting
            restrictions apply. See the [Ruleset guide](/user-guide/rulesets) for details.
    RedirectInput:
      type: object
      required:
        - redirect_network_offer_id
        - redirect_network_offer_url_id
        - routing_value
      properties:
        redirect_network_offer_id:
          type: integer
          description: The ID of the offer.
        redirect_network_offer_url_id:
          type: integer
          description: The ID of an offer URL. Defaults to the Base Destination URL (use 0).
        routing_value:
          type: integer
          minimum: 0
          description: >
            The value used to determine the priority or the weight of the offer in
            the list. Required if redirect_routing_type is priority or weight.
            For `priority`, the evaluation order starting at 1. For `weight`, a
            non-negative integer giving the offer's share of traffic relative to the
            sum of all redirect weights (weights 99 and 1 split traffic 99% / 1%);
            the platform UI accepts 0 to 99, and `0` keeps the offer on the smart
            link without sending it traffic. Non-integer values are rejected.
            For `kpi`, send `0`; the optimizer assigns the value after each run.
        ruleset:
          type: object
          description: >
            List of rules for which the redirect applies. See the
            [Ruleset guide](/user-guide/rulesets) for details.
    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