openapi: 3.0.3
info:
  title: Everflow Network API - Traffic Sources
  description: >
    Endpoints for managing traffic sources in the Everflow network.
    Traffic sources are a powerful way of appending parameters and values to links
    for partners. For setup details, see the [Traffic Sources guide](https://helpdesk.everflow.io/customer/how-to-create-link-templates-with-traffic-sources).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Traffic Sources
paths:
  /networks/trafficsource:
    get:
      summary: List Traffic Sources
      description: >
        Retrieve all active traffic sources for the network. Filterable by
        time_created and time_saved.
      tags:
        - Traffic Sources
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                traffic_sources:
                  - network_traffic_source_id: 1
                    network_id: 1
                    name: "test"
                    postback_url: "https://www.testpostback.com"
                    time_created: 1774721376
                    time_saved: 1774721376
                    relationship:
                      parameters:
                        total: 2
                        entries:
                          - network_traffic_source_id: 1
                            network_id: 1
                            tracking_parameter: "param1"
                            tracking_value: "value1"
                          - network_traffic_source_id: 1
                            network_id: 1
                            tracking_parameter: "param2"
                            tracking_value: "value2"
                    is_public: false
              schema:
                type: object
                properties:
                  traffic_sources:
                    type: array
                    items:
                      $ref: "#/components/schemas/TrafficSource"
      security:
        - API Key: []
    post:
      summary: Create Traffic Source
      tags:
        - Traffic Sources
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: "traffic source 3"
              postback_url: "https://www.postbackurl.com"
              is_public: false
              parameters:
                - tracking_parameter: "param1"
                  tracking_value: "value1"
                - tracking_parameter: "param2"
                  tracking_value: "value2"
            schema:
              $ref: "#/components/schemas/TrafficSourceInput"
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                network_traffic_source_id: 1
                network_id: 1
                name: "traffic source 3"
                postback_url: "https://www.testpostback.com"
                time_created: 1774721376
                time_saved: 1774721376
                relationship:
                  parameters:
                    total: 2
                    entries:
                      - network_traffic_source_id: 1
                        network_id: 1
                        tracking_parameter: "param1"
                        tracking_value: "value1"
                      - network_traffic_source_id: 1
                        network_id: 1
                        tracking_parameter: "param2"
                        tracking_value: "value2"
                is_public: false
              schema:
                $ref: "#/components/schemas/TrafficSource"
      security:
        - API Key: []
    put:
      summary: Update Traffic Source
      description: >
        Update an existing traffic source.
        Any omitted non-required fields will be reset to defaults.
      tags:
        - Traffic Sources
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_traffic_source_id: 3
              name: "traffic source 3"
              postback_url: "https://www.postbackurl.com"
              is_public: false
              parameters:
                - tracking_parameter: "param1"
                  tracking_value: "value1"
                - tracking_parameter: "param2"
                  tracking_value: "value2"
            schema:
              type: object
              required:
                - network_traffic_source_id
                - name
                - is_public
                - parameters
              properties:
                network_traffic_source_id:
                  type: integer
                  description: The ID of the traffic source to update.
                name:
                  type: string
                  description: Name of the traffic source.
                postback_url:
                  type: string
                  description: An optional postback URL for this traffic source.
                is_public:
                  type: boolean
                  description: >
                    When true, affiliates will be able to select this traffic source
                    when generating tracking links.
                parameters:
                  type: array
                  description: >
                    An array of parameter/value pairs that define the tracking parameters
                    for this traffic source. At least one entry is required.
                  items:
                    type: object
                    required:
                      - tracking_parameter
                      - tracking_value
                    properties:
                      tracking_parameter:
                        type: string
                        description: Parameter to be added to the traffic source.
                      tracking_value:
                        type: string
                        description: Value that will be added to the parameter.
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                network_traffic_source_id: 3
                network_id: 1
                name: "traffic source 3"
                postback_url: "https://www.testpostback.com"
                time_created: 1774721376
                time_saved: 1774721421
                relationship:
                  parameters:
                    total: 2
                    entries:
                      - network_traffic_source_id: 3
                        network_id: 1
                        tracking_parameter: "param1"
                        tracking_value: "value1"
                      - network_traffic_source_id: 3
                        network_id: 1
                        tracking_parameter: "param2"
                        tracking_value: "value2"
                is_public: false
              schema:
                $ref: "#/components/schemas/TrafficSource"
      security:
        - API Key: []
  /networks/trafficsource/{trafficSourceId}:
    get:
      summary: Get Traffic Source by ID
      description: >
        Retrieve a single traffic source by its ID.
      tags:
        - Traffic Sources
      parameters:
        - in: path
          name: trafficSourceId
          required: true
          schema:
            type: integer
          description: The ID of the traffic source.
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                network_traffic_source_id: 1
                network_id: 1
                name: "test"
                postback_url: "https://www.testpostback.com"
                time_created: 1774721376
                time_saved: 1774721376
                relationship:
                  parameters:
                    total: 2
                    entries:
                      - network_traffic_source_id: 1
                        network_id: 1
                        tracking_parameter: "param1"
                        tracking_value: "value1"
                      - network_traffic_source_id: 1
                        network_id: 1
                        tracking_parameter: "param2"
                        tracking_value: "value2"
                is_public: false
              schema:
                $ref: "#/components/schemas/TrafficSource"
      security:
        - API Key: []
    delete:
      summary: Delete Traffic Source
      description: >
        Delete an existing traffic source.
      tags:
        - Traffic Sources
      parameters:
        - in: path
          name: trafficSourceId
          required: true
          schema:
            type: integer
          description: The ID of the traffic source to delete.
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                result: true
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                    description: Whether the deletion was successful.
      security:
        - API Key: []
components:
  schemas:
    TrafficSource:
      type: object
      properties:
        network_traffic_source_id:
          type: integer
          description: Unique traffic source ID.
        network_id:
          type: integer
          description: Network ID.
        name:
          type: string
          description: Name of the traffic source.
        postback_url:
          type: string
          description: Postback URL for this traffic source.
        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:
            parameters:
              type: object
              properties:
                total:
                  type: integer
                  description: Total number of parameters.
                entries:
                  type: array
                  items:
                    type: object
                    properties:
                      network_traffic_source_id:
                        type: integer
                      network_id:
                        type: integer
                      tracking_parameter:
                        type: string
                        description: The tracking parameter name.
                      tracking_value:
                        type: string
                        description: The tracking parameter value.
        is_public:
          type: boolean
          description: >
            When true, affiliates can select this traffic source when
            generating tracking links.
    TrafficSourceInput:
      type: object
      required:
        - name
        - is_public
        - parameters
      properties:
        name:
          type: string
          description: Name of the traffic source.
        postback_url:
          type: string
          description: An optional postback URL for this traffic source.
        is_public:
          type: boolean
          description: >
            When true, affiliates will be able to select this traffic source
            when generating tracking links.
        parameters:
          type: array
          description: >
            An array of parameter/value pairs that define the tracking parameters
            for this traffic source. At least one entry is required.
          items:
            type: object
            required:
              - tracking_parameter
              - tracking_value
            properties:
              tracking_parameter:
                type: string
                description: Parameter to be added to the traffic source.
              tracking_value:
                type: string
                description: Value that will be added to the parameter.
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey