openapi: 3.0.3
info:
  title: Everflow Network API - Partner Postbacks
  description: >
    Endpoints for managing partner postbacks in the Everflow network.


    **Terminology note:** the API uses **`pixel`** for the same entity the
    platform UI calls a **postback** — `pixel_id` (API) and `postback_id` (UI)
    refer to the same record. URL paths use `/networks/pixels/...`.


    For postback setup and testing, see the [Postbacks guide](https://helpdesk.everflow.io/customer/introduction-to-partner-advertiser-postbacks).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Partner Postbacks
paths:
  /networks/pixelstable:
    post:
      summary: Find Partner Postbacks (Advanced)
      tags:
        - Partner Postbacks
      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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  $ref: "#/components/schemas/SearchQuery"
            examples:
              active_conversion_postbacks:
                summary: "Fetch active conversion postbacks for an offer"
                value:
                  query:
                    search_terms: []
                    filters:
                      pixel_type: "conversion"
                      network_offer_ids: [11]
              event_postbacks_by_method:
                summary: "Fetch event postbacks filtered by delivery method"
                value:
                  query:
                    search_terms: []
                    filters:
                      delivery_methods: ["postback"]
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  pixels:
                    type: array
                    items:
                      $ref: "#/components/schemas/PartnerPostbackTable"
                  paging:
                    $ref: "#/components/schemas/Paging"
      security:
        - API Key: []
  /networks/pixels/{pixelId}:
    get:
      summary: Get Partner Postback by ID
      tags:
        - Partner Postbacks
      parameters:
        - in: path
          name: pixelId
          required: true
          schema:
            type: integer
          description: The partner postback (pixel) identifier.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PartnerPostback"
      security:
        - API Key: []
    put:
      summary: Update Partner Postback
      description: >
        Update an existing partner postback.
      tags:
        - Partner Postbacks
      parameters:
        - in: path
          name: pixelId
          required: true
          schema:
            type: integer
          description: The partner postback (pixel) identifier.
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_offer_id: 11
              network_affiliate_id: 7
              delivery_method: "postback"
              pixel_level: "specific"
              pixel_status: "active"
              pixel_type: "conversion"
              postback_url: "https://example.com/postback?tid={transaction_id}"
              description: "Conversion postback for affiliate 7"
            schema:
              $ref: "#/components/schemas/PartnerPostbackInput"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PartnerPostback"
      security:
        - API Key: []
  /networks/pixels:
    get:
      summary: List All Partner Postbacks
      description: >
        Retrieve all partner postbacks without table search or pagination.
        For filtered and paginated results, use the List Partner Postbacks endpoint.
      tags:
        - Partner Postbacks
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PartnerPostback"
      security:
        - API Key: []
    post:
      summary: Create Partner Postback
      tags:
        - Partner Postbacks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PartnerPostbackInput"
            example:
              network_offer_id: 11
              network_affiliate_id: 7
              delivery_method: "postback"
              pixel_level: "specific"
              pixel_status: "active"
              pixel_type: "conversion"
              postback_url: "https://example.com/postback?tid={transaction_id}"
              description: "Conversion postback for affiliate 7"
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PartnerPostback"
      security:
        - API Key: []
components:
  schemas:
    PartnerPostback:
      type: object
      properties:
        network_pixel_id:
          type: integer
          description: Unique partner postback (pixel) ID.
        network_id:
          type: integer
          description: Network ID.
        network_affiliate_id:
          type: integer
          description: Associated affiliate ID (0 for all affiliates).
        network_offer_id:
          type: integer
          description: >
            Associated offer ID. Only relevant if `pixel_level` is `specific` or `global_offer`.
            Set to 0 when `pixel_level` is `global`.
        network_offer_payout_revenue_id:
          type: integer
          description: >
            ID of the offer payout and revenue entry associated with this
            postback, also known as the event ID. Only relevant when
            `pixel_type` is `event` and `pixel_level` is `specific`
            or `global_offer`. A value of `0` selects all payout and
            revenue / event IDs on the offer.
        delivery_method:
          type: string
          enum:
            - postback
            - html
            - facebook
            - tiktok
            - snapchat
            - rumble
          description: >
            Determines how the postback will be fired. `postback` fires server-to-server (S2S).
            `html` fires from an HTML tag/pixel. `facebook`, `tiktok`, `snapchat`, and `rumble`
            fire through their respective integrations.
        pixel_level:
          type: string
          enum:
            - global
            - specific
            - global_offer
          description: >
            Determines if the postback should be used for all offers (`global`), a specific
            offer/affiliate combination (`specific`), or all affiliates on a specific offer
            (`global_offer`).
        pixel_status:
          type: string
          enum:
            - active
            - inactive
          description: "Postback status. Can be `active` or `inactive`."
        pixel_type:
          type: string
          enum:
            - conversion
            - cpc
            - event
          description: >
            `conversion` fires for the base conversion action. `event` fires for any
            post-conversion events. `cpc` is used specifically for offers with CPC payouts and
            fires on every unique payable click action.
        postback_url:
          type: string
          description: >
            The postback URL (used when delivery_method is `postback`). The URL requires the
            `http://` or `https://` protocol prefix.
        html_code:
          type: string
          description: HTML/iframe/image/JavaScript pixel code (when delivery_method is html).
        description:
          type: string
          description: Description of this postback.
        delay_ms:
          type: integer
          description: >
            Optional delay in milliseconds that the system will wait before firing the postback.
            Only relevant when delivery method is `postback`. Maximum delay is 5 minutes
            (300000 milliseconds).
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of creation.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of last update.
        facebook_pixel:
          type: object
          nullable: true
          description: Meta (Facebook) pixel configuration. Present when `delivery_method` is `facebook`.
          properties:
            network_affiliate_integration_facebook_business_id:
              type: integer
              description: Meta Business integration ID.
            pixel_id:
              type: string
              description: Meta Pixel ID.
            event_name:
              type: string
              description: Meta event name.
            event_id:
              type: string
              description: Meta Event ID for deduplication.
            action_source:
              type: string
              description: Where the conversion occurred.
            event_source_url:
              type: string
              description: The URL where the conversion event occurred.
            user_data:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    enum:
                      - email
                      - phone
                      - gender
                      - date_of_birth
                      - last_name
                      - first_name
                      - city
                      - state
                      - zipcode
                      - country_code
                      - external_id
                      - fbc
                      - fbp
                      - subscription_id
                      - fb_login_id
                  value:
                    type: string
            custom_data:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    enum:
                      - value
                      - currency
                      - order_id
                      - predicted_ltv
                      - num_items
                      - status
                      - search_string
                  value:
                    type: string
        tiktok_pixel:
          type: object
          nullable: true
          description: TikTok pixel configuration. Present when `delivery_method` is `tiktok`.
          properties:
            network_affiliate_integration_tiktok_id:
              type: integer
              description: TikTok integration ID.
            pixel_code:
              type: string
              description: TikTok Pixel Code.
            event_name:
              type: string
              description: TikTok event name.
            url:
              type: string
              description: Page URL.
            email:
              type: string
              description: User email.
            phone:
              type: string
              description: User phone number.
            properties:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    enum:
                      - price
                      - quantity
                      - content_type
                      - content_id
                      - content_category
                      - content_name
                      - currency
                      - value
                      - description
                      - query
                      - status
                  value:
                    type: string
        snapchat_pixel:
          type: object
          nullable: true
          description: Snapchat pixel configuration. Present when `delivery_method` is `snapchat`.
          properties:
            network_affiliate_integration_snapchat_id:
              type: integer
              description: Snapchat integration ID.
            asset_id:
              type: string
              description: Snapchat App/Pixel ID.
            event_name:
              type: string
              description: Snapchat Event Name.
            event_id:
              type: string
              description: Snapchat Event ID.
            action_source:
              type: string
              description: Where the conversion occurred.
            event_source_url:
              type: string
              description: Event Source URL.
            user_data:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    enum:
                      - email
                      - phone
                      - first_name
                      - last_name
                      - gender
                      - city
                      - state
                      - zipcode
                      - country_code
                      - idfv
                      - sc_cid
                  value:
                    type: string
            custom_data:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    enum:
                      - value
                      - currency
                      - order_id
                      - num_items
                      - status
                      - search_string
                  value:
                    type: string
        rumble_pixel:
          type: object
          nullable: true
          description: Rumble pixel configuration. Present when `delivery_method` is `rumble`.
          properties:
            network_affiliate_integration_rumble_id:
              type: integer
              description: Rumble integration ID.
            conversion_action_id:
              type: integer
              description: Rumble Conversion Action ID.
            conversion_action_name:
              type: string
              description: Rumble Conversion Action name.
        relationship:
          type: object
          description: >
            Related entities. Contains `offer` when `pixel_level` is `specific`
            or `global_offer`, and `affiliate` when `pixel_level` is `specific`
            or `global`.
          properties:
            offer:
              type: object
              description: Associated offer details. Present when `pixel_level` is `specific` or `global_offer`.
              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
            affiliate:
              type: object
              description: Associated affiliate details. Present when `pixel_level` is `specific` or `global`.
              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
                  description: Address ID (note the field name uses a single 'd').
                default_currency_id:
                  type: string
                is_contact_address_enabled:
                  type: boolean
                enable_media_cost_tracking_links:
                  type: boolean
                referrer_id:
                  type: integer
                time_created:
                  type: integer
                  example: 1734455015
                time_saved:
                  type: integer
                  example: 1734455015
    PartnerPostbackInput:
      type: object
      required:
        - pixel_status
        - pixel_type
        - pixel_level
        - delivery_method
      properties:
        network_offer_id:
          type: integer
          description: >
            Associated offer ID. Required when `pixel_level` is `specific` or `global_offer`.
            Set to 0 when `pixel_level` is `global`.
        network_affiliate_id:
          type: integer
          description: >
            Associated affiliate ID. Required when `pixel_level` is `specific` or `global`.
            Set to 0 when `pixel_level` is `global_offer`.
        delivery_method:
          type: string
          enum:
            - postback
            - html
            - facebook
            - tiktok
            - snapchat
            - rumble
          description: >
            Determines how the postback will be fired. `postback` fires server-to-server (S2S).
            `html` fires from an HTML tag/pixel. `facebook` (Meta), `tiktok`, `snapchat`, and
            `rumble` fire through their respective integrations.
        pixel_level:
          type: string
          enum:
            - global
            - specific
            - global_offer
          description: >
            Scope of the postback. `global` fires for a specific partner across all offers
            (set `network_affiliate_id`, `network_offer_id` to 0). `specific` fires for a
            specific offer/affiliate combination (set both IDs). `global_offer` fires for
            all affiliates on a specific offer (set `network_offer_id`, `network_affiliate_id`
            to 0). Not available when `pixel_type` is `cpc`.
        pixel_status:
          type: string
          enum:
            - active
            - inactive
          description: Postback status.
        pixel_type:
          type: string
          enum:
            - conversion
            - cpc
            - event
          description: >
            `conversion` fires for the base conversion action. `event` fires for any
            post-conversion events. `cpc` is used specifically for offers with CPC payouts and
            fires on every unique payable click action. When `cpc` is selected, `pixel_level`
            cannot be changed.
        postback_url:
          type: string
          description: >
            The postback URL. Required when `delivery_method` is `postback`. Supports
            macros like `{transaction_id}`. The URL requires the `http://` or `https://`
            protocol prefix.
        html_code:
          type: string
          description: >
            HTML/iframe/image/JavaScript pixel code. Required when `delivery_method` is `html`.
        description:
          type: string
          description: Optional description for this postback.
        delay_ms:
          type: integer
          description: >
            Delay in milliseconds before firing the postback. Only applicable when
            `delivery_method` is `postback`. Maximum 5 minutes (300000 ms).
        network_offer_payout_revenue_id:
          type: integer
          description: >
            ID of the offer payout/revenue entry (event ID). Only relevant when `pixel_type`
            is `event` and `pixel_level` is `specific` or `global_offer`. Use `0` to fire
            for all events on the offer.
        facebook_pixel:
          type: object
          description: >
            Meta (Facebook) pixel configuration. Required when `delivery_method` is `facebook`.
          properties:
            network_affiliate_integration_facebook_business_id:
              type: integer
              description: Meta Business integration ID.
            pixel_id:
              type: string
              description: Meta Pixel ID.
            event_name:
              type: string
              description: >
                Meta event name. Use a standard event (e.g. Purchase, Lead, CompleteRegistration)
                or enable custom event name for a custom value.
            event_id:
              type: string
              description: >
                Optional Meta Event ID for deduplication. Supports macros.
            action_source:
              type: string
              description: >
                Where the conversion occurred (e.g. website, app, email, phone_call).
            event_source_url:
              type: string
              description: The URL where the conversion event occurred.
            user_data:
              type: array
              description: Meta User Data parameters for matching.
              items:
                type: object
                properties:
                  field:
                    type: string
                    enum:
                      - email
                      - phone
                      - gender
                      - date_of_birth
                      - last_name
                      - first_name
                      - city
                      - state
                      - zipcode
                      - country_code
                      - external_id
                      - fbc
                      - fbp
                      - subscription_id
                      - fb_login_id
                  value:
                    type: string
                    description: Value or macro (e.g. `{email}`).
            custom_data:
              type: array
              description: Meta Custom Data parameters.
              items:
                type: object
                properties:
                  field:
                    type: string
                    enum:
                      - value
                      - currency
                      - order_id
                      - predicted_ltv
                      - num_items
                      - status
                      - search_string
                  value:
                    type: string
                    description: Value or macro.
        tiktok_pixel:
          type: object
          description: >
            TikTok pixel configuration. Required when `delivery_method` is `tiktok`.
          properties:
            network_affiliate_integration_tiktok_id:
              type: integer
              description: TikTok integration ID.
            pixel_code:
              type: string
              description: TikTok Pixel Code.
            event_name:
              type: string
              enum:
                - view_content
                - click_button
                - search
                - add_to_wishlist
                - add_to_cart
                - initiate_checkout
                - add_payment_info
                - complete_payment
                - place_order
                - contact
                - download
                - submit_form
                - complete_registration
                - subscribe
              description: >
                TikTok event name. Use a standard event or enable custom event name
                for a custom value.
            url:
              type: string
              description: Page URL. Supports macros.
            email:
              type: string
              description: User email. Supports macros.
            phone:
              type: string
              description: User phone number. Supports macros.
            properties:
              type: array
              description: TikTok Properties for additional event data.
              items:
                type: object
                properties:
                  field:
                    type: string
                    enum:
                      - price
                      - quantity
                      - content_type
                      - content_id
                      - content_category
                      - content_name
                      - currency
                      - value
                      - description
                      - query
                      - status
                  value:
                    type: string
                    description: Value or macro.
        snapchat_pixel:
          type: object
          description: >
            Snapchat pixel configuration. Required when `delivery_method` is `snapchat`.
          properties:
            network_affiliate_integration_snapchat_id:
              type: integer
              description: Snapchat integration ID.
            asset_id:
              type: string
              description: Snapchat App/Pixel ID.
            event_name:
              type: string
              description: Snapchat Event Name.
            event_id:
              type: string
              description: Optional Snapchat Event ID. Supports macros.
            action_source:
              type: string
              description: Where the conversion occurred (e.g. WEB, APP).
            event_source_url:
              type: string
              description: Event Source URL.
            user_data:
              type: array
              description: Snapchat User Data parameters for matching.
              items:
                type: object
                properties:
                  field:
                    type: string
                    enum:
                      - email
                      - phone
                      - first_name
                      - last_name
                      - gender
                      - city
                      - state
                      - zipcode
                      - country_code
                      - idfv
                      - sc_cid
                  value:
                    type: string
                    description: Value or macro.
            custom_data:
              type: array
              description: Snapchat Custom Data parameters.
              items:
                type: object
                properties:
                  field:
                    type: string
                    enum:
                      - value
                      - currency
                      - order_id
                      - num_items
                      - status
                      - search_string
                  value:
                    type: string
                    description: Value or macro.
        rumble_pixel:
          type: object
          description: >
            Rumble pixel configuration. Required when `delivery_method` is `rumble`.
          properties:
            network_affiliate_integration_rumble_id:
              type: integer
              description: Rumble integration ID.
            conversion_action_id:
              type: integer
              description: Rumble Conversion Action ID.
    SearchQuery:
      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
                  - offer
                  - affiliate
                description: "The field to search on."
              value:
                type: string
                description: The search value.
        filters:
          type: object
          description: Filter criteria for searching postbacks.
          properties:
            status:
              type: string
              enum:
                - active
                - inactive
              description: Filter by postback status.
            pixel_type:
              type: string
              enum:
                - conversion
                - cpc
                - event
              description: Filter by pixel type (firing trigger).
            network_offer_ids:
              type: array
              items:
                type: integer
              description: >
                Filter by offer IDs. Note that `global` postbacks (that target all offers) will
                also be returned when this filter is used.
            network_affiliate_ids:
              type: array
              items:
                type: integer
              description: >
                Filter by affiliate IDs. Note that global offer postbacks (that fire regardless
                of the partner) will also be returned when this filter is used.
            delivery_methods:
              type: array
              items:
                type: string
                enum:
                  - postback
                  - html
                  - facebook
                  - tiktok
                  - snapchat
                  - rumble
              description: Filter by delivery methods.
    PartnerPostbackTable:
      type: object
      description: A partner postback record from the table endpoint (flattened).
      properties:
        network_pixel_id:
          type: integer
          description: Unique partner postback (pixel) ID.
        network_id:
          type: integer
          description: Network ID.
        network_offer_payout_revenue_id:
          type: integer
          description: Event ID (0 for all events).
        delivery_method:
          type: string
          enum:
            - postback
            - html
            - facebook
            - tiktok
            - snapchat
            - rumble
          description: Delivery method.
        pixel_level:
          type: string
          enum:
            - global
            - specific
            - global_offer
          description: Postback scope.
        pixel_status:
          type: string
          enum:
            - active
            - inactive
          description: Postback status.
        pixel_type:
          type: string
          enum:
            - conversion
            - cpc
            - event
          description: Postback type.
        postback_url:
          type: string
          description: Postback URL.
        html_code:
          type: string
          description: HTML pixel code.
        network_affiliate_id:
          type: integer
          description: Associated affiliate ID.
        network_affiliate_name:
          type: string
          description: Associated affiliate name.
        network_offer_id:
          type: integer
          description: Associated offer ID.
        network_offer_name:
          type: string
          description: Associated offer name.
        description:
          type: string
          description: Description.
        delay_ms:
          type: integer
          description: Delay in milliseconds before firing.
        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
          description: Related entities (currently empty for table results).
    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