openapi: 3.0.3
info:
  title: Everflow Network API - Offer URLs
  description: >
    Endpoints for managing offer URLs in the Everflow network. Offer URLs
    let you add additional landing page destinations inside an offer — use
    them for A/B testing, seasonal pages, or directing traffic to specific
    product pages while maintaining tracking consistency. For details, see
    the [Offer URLs guide](https://helpdesk.everflow.io/customer/how-to-use-offer-urls).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Offer URLs
paths:
  /networks/offerurls:
    get:
      summary: List Offer URLs
      tags:
        - Offer URLs
      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
            maximum: 2000
          description: Number of results per page (max 2000).
        - in: query
          name: filter
          schema:
            type: string
          description: >
            Filter results by a field. The format is `filter={field}={value}`.
            Supported fields: `network_offer_id` (filter by offer ID),
            `url_status` (`active`, `paused`, or `deleted`),
            `time_created` (creation timestamp),
            `time_saved` (last modified timestamp).
          example: "network_offer_id=178"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  urls:
                    type: array
                    items:
                      $ref: "#/components/schemas/OfferUrl"
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total_count:
                        type: integer
      security:
        - API Key: []
    post:
      summary: Create Offer URL
      tags:
        - Offer URLs
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_offer_id: 6
              name: "Offer URL Name"
              destination_url: "https://example.com/lp2?tid={transaction_id}"
              preview_url: "https://example.com/preview"
              url_status: "active"
              is_apply_specific_affiliates: true
              network_affiliate_ids: [7, 14]
              is_hidden_affiliate: true
            schema:
              type: object
              required:
                - network_offer_id
                - name
                - destination_url
                - is_apply_specific_affiliates
                - is_hidden_affiliate
              properties:
                network_offer_id:
                  type: integer
                  description: The ID of the offer to which this offer URL is associated.
                name:
                  type: string
                  description: The name of the offer URL.
                destination_url:
                  type: string
                  description: The URL the offer URL will redirect to.
                preview_url:
                  type: string
                  description: A preview URL, if it exists.
                url_status:
                  type: string
                  enum:
                    - active
                    - paused
                    - deleted
                  description: Status of the offer URL setting.
                is_apply_specific_affiliates:
                  type: boolean
                  description: >
                    Determines whether this offer URL applies to all affiliates or only
                    to a select few. When true, the network_affiliate_ids array must be filled.
                network_affiliate_ids:
                  type: array
                  nullable: true
                  items:
                    type: integer
                  description: >
                    The IDs of the affiliates that are to be affected by the offer URL.
                    Only relevant when is_apply_specific_affiliates is true.
                is_hidden_affiliate:
                  type: boolean
                  description: >
                    Determines whether affiliates will see this offer URL or not in the
                    affiliate UI / API.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OfferUrl"
      security:
        - API Key: []
  /networks/offerurls/bulk:
    post:
      summary: Bulk Create Offer URLs
      tags:
        - Offer URLs
      requestBody:
        required: true
        content:
          application/json:
            example:
              - network_offer_id: 6
                name: "Landing Page A"
                destination_url: "https://example.com/a?tid={transaction_id}"
                preview_url: "https://example.com/a"
                url_status: "active"
                is_apply_specific_affiliates: false
                is_hidden_affiliate: false
              - network_offer_id: 6
                name: "Landing Page B"
                destination_url: "https://example.com/b?tid={transaction_id}"
                preview_url: "https://example.com/b"
                url_status: "active"
                is_apply_specific_affiliates: false
                is_hidden_affiliate: false
            schema:
              type: array
              items:
                type: object
                required:
                  - network_offer_id
                  - name
                  - destination_url
                  - is_apply_specific_affiliates
                  - is_hidden_affiliate
                properties:
                  network_offer_id:
                    type: integer
                    description: The ID of the offer to which this offer URL is associated.
                  name:
                    type: string
                    description: The name of the offer URL.
                  destination_url:
                    type: string
                    description: The URL the offer URL will redirect to.
                  preview_url:
                    type: string
                    description: A preview URL, if it exists.
                  url_status:
                    type: string
                    enum:
                      - active
                      - paused
                      - deleted
                    description: Status of the offer URL setting.
                  is_apply_specific_affiliates:
                    type: boolean
                    description: >
                      Determines whether this offer URL applies to all affiliates or only
                      to a select few. When true, the network_affiliate_ids array must be filled.
                  network_affiliate_ids:
                    type: array
                    items:
                      type: integer
                    description: >
                      The IDs of the affiliates that are to be affected by the offer URL.
                      Only relevant when is_apply_specific_affiliates is true.
                  is_hidden_affiliate:
                    type: boolean
                    description: >
                      Determines whether affiliates will see this offer URL or not in the
                      affiliate UI / API.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  urls:
                    type: array
                    items:
                      $ref: "#/components/schemas/OfferUrl"
      security:
        - API Key: []
  /networks/offerurls/table:
    post:
      summary: Find Offer URLs (Advanced)
      tags:
        - Offer URLs
      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: order_field
          schema:
            type: string
            enum:
              - network_offer_url_id
              - time_saved
              - time_created
              - url_status
          description: The field to sort by.
        - in: query
          name: order_direction
          schema:
            type: string
            enum:
              - asc
              - desc
          description: Sort direction.
      requestBody:
        required: true
        content:
          application/json:
            example:
              filters:
                network_offer_ids:
                  - 6
                url_status: "active"
              search_terms:
                - search_type: "name"
                  value: "landing"
            schema:
              type: object
              properties:
                filters:
                  type: object
                  properties:
                    network_offer_ids:
                      type: array
                      items:
                        type: integer
                      description: Filter by one or more offer IDs.
                    url_status:
                      type: string
                      enum:
                        - active
                        - paused
                        - deleted
                      description: Filter by URL status.
                search_terms:
                  type: array
                  items:
                    type: object
                    properties:
                      search_type:
                        type: string
                        enum:
                          - name
                          - destination_url
                        description: >
                          The field to search. `name` searches both the URL
                          name and the offer URL ID.
                      value:
                        type: string
                        description: The search value (partial match).
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  urls:
                    type: array
                    items:
                      $ref: "#/components/schemas/OfferUrl"
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total_count:
                        type: integer
      security:
        - API Key: []
  /networks/offerurls/{offerUrlId}:
    get:
      summary: Get Offer URL by ID
      tags:
        - Offer URLs
      parameters:
        - in: path
          name: offerUrlId
          required: true
          schema:
            type: integer
          description: The offer URL ID.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OfferUrl"
      security:
        - API Key: []
    put:
      summary: Update Offer URL
      tags:
        - Offer URLs
      parameters:
        - in: path
          name: offerUrlId
          required: true
          schema:
            type: integer
          description: The offer URL ID.
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_offer_url_id: 1
              network_offer_id: 6
              name: "Offer URL Name"
              destination_url: "https://destination-url.com/?tid={transaction_id}"
              preview_url: "https://preview-url.com"
              url_status: "active"
              network_affiliate_ids: [7, 14]
              is_apply_specific_affiliates: true
              is_hidden_affiliate: true
            schema:
              type: object
              required:
                - network_offer_url_id
                - network_offer_id
                - name
                - destination_url
                - is_apply_specific_affiliates
                - is_hidden_affiliate
              properties:
                network_offer_url_id:
                  type: integer
                  description: The unique ID of the offer URL.
                network_offer_id:
                  type: integer
                  description: The ID of the offer to which this offer URL is associated.
                name:
                  type: string
                  description: The name of the offer URL.
                destination_url:
                  type: string
                  description: The URL the offer URL will redirect to.
                preview_url:
                  type: string
                  description: A preview URL, if it exists.
                url_status:
                  type: string
                  enum:
                    - active
                    - paused
                    - deleted
                  description: Status of the offer URL setting.
                is_apply_specific_affiliates:
                  type: boolean
                  description: >
                    Determines whether this offer URL applies to all affiliates or only
                    to a select few. When true, the network_affiliate_ids array must be filled.
                network_affiliate_ids:
                  type: array
                  nullable: true
                  items:
                    type: integer
                  description: >
                    The IDs of the affiliates that are to be affected by the offer URL.
                    Only relevant when is_apply_specific_affiliates is true.
                is_hidden_affiliate:
                  type: boolean
                  description: >
                    Determines whether affiliates will see this offer URL or not in the
                    affiliate UI / API.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OfferUrl"
      security:
        - API Key: []
  /networks/patch/offerurls/apply:
    patch:
      summary: Apply Offer URL Bulk Edit
      tags:
        - Offer URLs
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_offer_id: 1
              network_offer_url_ids: [10, 11, 12]
              fields:
                - field_type: "url_status"
                  field_value: "paused"
                  operator: "overwrite"
            schema:
              type: object
              required:
                - network_offer_id
                - network_offer_url_ids
                - fields
              properties:
                network_offer_id:
                  type: integer
                  description: The ID of the offer to which the offer URLs are associated.
                network_offer_url_ids:
                  type: array
                  items:
                    type: integer
                  description: The unique IDs of the offer URLs that will be modified.
                fields:
                  type: array
                  description: A list of the fields that will be modified.
                  items:
                    type: object
                    required:
                      - field_type
                      - field_value
                      - operator
                    properties:
                      field_type:
                        type: string
                        enum:
                          - url_status
                          - is_apply_specific_affiliates
                          - network_affiliate_ids
                          - destination_url_replace
                          - name
                          - is_hidden_affiliate
                        description: >
                          The name of the field that will be modified. For
                          destination_url_replace, the field_value should be an object
                          with find and replace strings.
                      field_value:
                        description: The new value of the field (type varies by field_type).
                      operator:
                        type: string
                        enum:
                          - overwrite
                          - append
                          - delete
                          - clear
                        description: >
                          How the field will be modified. Not all options are possible for
                          every field — append, delete, and clear only apply for fields
                          that contain multiple values like network_affiliate_ids.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                    description: Whether the bulk edit was successful.
      security:
        - API Key: []
components:
  schemas:
    OfferUrl:
      type: object
      properties:
        network_offer_url_id:
          type: integer
          description: Unique offer URL ID.
        network_id:
          type: integer
          description: Network ID.
        network_offer_id:
          type: integer
          description: The ID of the offer to which this offer URL is associated.
        name:
          type: string
          description: The name of the offer URL.
        destination_url:
          type: string
          description: The URL the offer URL will redirect to.
        preview_url:
          type: string
          description: A preview URL, if it exists.
        url_status:
          type: string
          enum:
            - active
            - paused
            - deleted
          description: Status of the offer URL setting.
        network_affiliate_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: >
            The IDs of the affiliates that are to be affected by the offer URL.
            Only relevant when is_apply_specific_affiliates is true.
        is_apply_specific_affiliates:
          type: boolean
          description: >
            Determines whether this offer URL applies to all affiliates or only
            to a select few. When true, the network_affiliate_ids array must be filled.
        is_hidden_affiliate:
          type: boolean
          description: >
            Determines whether affiliates will see this offer URL or not in the
            affiliate UI / API.
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of creation.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of last update.
        remote_offer_resource:
          type: object
          description: Remote offer resource configuration.
          properties:
            network_offer_id:
              type: integer
            network_id:
              type: integer
            resource_type:
              type: string
            remote_resource_id:
              type: string
            resource_id:
              type: integer
            last_value_md5:
              type: string
            json_config:
              type: string
            json_data:
              type: string
            time_created:
              type: integer
              example: 1734455015
            time_saved:
              type: integer
              example: 1734455015
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey