openapi: 3.0.3 info: title: Everflow Advertiser API - Reporting description: > Reporting endpoints for the Everflow Advertiser API. These endpoints are accessed by advertiser users using their own API key and return data scoped to the authenticated advertiser's account only. version: 1.0.0 servers: - description: Production Server url: https://api.eflow.team/v1 tags: - name: Advertiser Reporting description: Reporting endpoints available to advertiser users. paths: /advertisers/reporting/entity: post: summary: Entity Reporting tags: - Advertiser Reporting requestBody: required: true content: application/json: example: from: "2024-01-01" to: "2024-01-31" timezone_id: 67 currency_id: "USD" columns: - column: "offer" query: filters: [] schema: type: object required: - from - to - timezone_id - currency_id - columns properties: from: type: string description: Start date for the reporting period. Format `YYYY-MM-DD`. to: type: string description: End date for the reporting period. Format `YYYY-MM-DD`. timezone_id: type: integer description: Timezone identifier for the request. currency_id: type: string description: Currency code for monetary values (e.g. "USD"). columns: type: array minItems: 1 maxItems: 10 description: > Columns to group/pivot data by. Minimum 1, maximum 10. Only one time column (hour, date, week, month, year) is allowed per request. items: type: object required: - column properties: column: type: string enum: - offer - affiliate - creative - offer_url - country - country_code - region - city - dma - carrier - platform - isp - os_version - device_type - device_model - device_make - browser - language - sub1 - sub2 - sub3 - sub4 - sub5 - sub6 - sub7 - sub8 - sub9 - sub10 - source_id - connection_type - advertiser_campaign_name - app_identifier - bundle_id - meta_platform - score_rating - total_rating - size - developer - version - hour - date - week - month - year description: > The dimension to group by. Time columns (hour, date, week, month, year) are mutually exclusive — only one allowed at a time. query: type: object description: Query configuration for filtering, metric filtering, and exclusions. properties: filters: type: array description: > Filters to narrow results. Same resource_type filters use OR logic; different resource_type filters use AND logic. items: type: object required: - filter_id_value - resource_type properties: filter_id_value: type: string description: The value to filter on (e.g. offer ID, country name). resource_type: type: string enum: - offer - affiliate - creative - country - country_code - sub1 - sub2 - sub3 - sub4 - sub5 - sub6 - sub7 - sub8 - sub9 - sub10 - carrier - device_platform - device_type - device_make - browser - language - connection_type - source_id - offer_url - device_model - os_version - coupon_code - adv1 - adv2 - adv3 - adv4 - adv5 - adv6 - adv7 - adv8 - adv9 - adv10 description: The resource type / dimension to filter on. metric_filters: type: array description: >- Filters rows based on aggregated metric thresholds (e.g. return only rows where cost > 0). Applied after aggregation, before the row limit. items: type: object properties: metric_type: type: string enum: - impression - total_click - unique_click - cv - event - revenue - gross_sales description: >- The metric to filter on. Note: an advertiser's "cost" is the `revenue` metric — use `metric_type: revenue` to filter on cost. metric_value: type: number description: Threshold value. operator: type: string enum: - less_than - less_than_or_equal - greater_than - greater_than_or_equal description: Comparison operator. exclusions: type: array description: Exclusion filters to remove specific dimension values from results. items: type: object properties: filter_id_value: type: string description: The value to exclude. resource_type: type: string description: The resource type / dimension to exclude on. responses: "200": description: "" content: application/json: schema: type: object properties: table: type: array description: Array of reporting data rows grouped by the requested columns. items: type: object properties: columns: type: array description: Dimension values for this row. items: type: object properties: column_type: type: string description: The column/dimension type (matches the requested column value). id: type: string description: Dimension value identifier (e.g. offer ID, country name). label: type: string description: Human-readable label for the dimension value. reporting: $ref: "#/components/schemas/ReportingMetrics" performance: type: array description: Time-series performance data points. items: type: object properties: unix: type: integer description: Unix timestamp for the time period. reporting: $ref: "#/components/schemas/ReportingMetrics" summary: description: Aggregated summary across all rows. A flat object with the same metric keys as ReportingMetrics. $ref: "#/components/schemas/ReportingMetrics" security: - API Key: [] /advertisers/reporting/conversions: post: summary: Search Conversions tags: - Advertiser Reporting 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: example: show_conversions: true show_events: false show_only_vt: false show_only_ct: false from: "2024-01-01" to: "2024-01-31" timezone_id: 67 currency_id: "USD" query: filters: [] search_terms: [] schema: type: object required: - show_conversions - show_events - from - to - timezone_id - currency_id properties: show_conversions: type: boolean description: Whether to include base conversions in the results. show_events: type: boolean description: Whether to include post-conversion events in the results. show_only_vt: type: boolean description: When true, only return view-through conversions. show_only_ct: type: boolean description: When true, only return click-through conversions. from: type: string description: Start date. Format `YYYY-MM-DD` or `YYYY-MM-DD hh:mm:ss`. to: type: string description: End date. Format `YYYY-MM-DD` or `YYYY-MM-DD hh:mm:ss`. timezone_id: type: integer description: Timezone identifier for the request. currency_id: type: string description: Currency code for monetary values (e.g. "USD"). query: type: object description: Query configuration for filtering. properties: filters: type: array description: Filters to narrow results. items: type: object properties: filter_id_value: type: string description: The value to filter on. resource_type: type: string description: The resource type to filter on. search_terms: type: array description: Text-based search filters. items: type: object properties: search_type: type: string description: The field to search on. value: type: string description: The search term. responses: "200": description: "" content: application/json: schema: type: object properties: conversions: type: array description: Array of conversion objects. items: $ref: "#/components/schemas/Conversion" paging: type: object properties: page: type: integer description: Current page number. page_size: type: integer description: Number of results per page. total_count: type: integer description: Total number of matching conversions. security: - API Key: [] /advertisers/reporting/conversions/export: post: summary: Export Conversions tags: - Advertiser Reporting requestBody: required: true content: application/json: example: show_conversions: true show_events: false from: "2024-01-01" to: "2024-01-31" timezone_id: 67 currency_id: "USD" format: "csv" query: filters: [] schema: type: object required: - show_conversions - show_events - from - to - timezone_id - currency_id - format properties: show_conversions: type: boolean description: Whether to include base conversions in the export. show_events: type: boolean description: Whether to include post-conversion events in the export. show_only_vt: type: boolean description: When true, only export view-through conversions. show_only_ct: type: boolean description: When true, only export click-through conversions. from: type: string description: Start date. Format `YYYY-MM-DD` or `YYYY-MM-DD hh:mm:ss`. to: type: string description: End date. Format `YYYY-MM-DD` or `YYYY-MM-DD hh:mm:ss`. timezone_id: type: integer description: Timezone identifier for the request. currency_id: type: string description: Currency code for monetary values (e.g. "USD"). format: type: string enum: - csv - json description: Export format. `csv` for comma-separated values, `json` for newline-delimited JSON. query: type: object description: Query configuration for filtering. properties: filters: type: array description: Filters to narrow results. items: type: object properties: filter_id_value: type: string description: The value to filter on. resource_type: type: string description: The resource type to filter on. responses: "200": description: OK — Returns the exported data in the requested format. content: text/csv: schema: type: string description: CSV-formatted conversion data. application/json: schema: type: string description: Newline-delimited JSON conversion data. security: - API Key: [] /advertisers/reporting/conversions/{conversionId}: get: summary: Get Conversion By ID tags: - Advertiser Reporting parameters: - in: path name: conversionId required: true schema: type: string description: The unique conversion ID (UUID string, e.g. `ed113548268141de8b4c4ad4a1d812a7`). responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Conversion" "404": description: Conversion not found. security: - API Key: [] /advertisers/dashboard/summary: post: summary: Dashboard Summary tags: - Advertiser Reporting requestBody: required: true content: application/json: example: timezone_id: 67 schema: type: object required: - timezone_id properties: timezone_id: type: integer description: Timezone identifier for computing period boundaries. from: type: string description: Start date for the reporting period. Format `YYYY-MM-DD`. to: type: string description: End date for the reporting period. Format `YYYY-MM-DD`. currency_id: type: string description: Currency code for monetary values (e.g. "USD"). compare_from: type: string description: Start date for the comparison period. Format `YYYY-MM-DD`. compare_to: type: string description: End date for the comparison period. Format `YYYY-MM-DD`. responses: "200": description: "" content: application/json: schema: type: object properties: click: $ref: "#/components/schemas/DashboardMetric" conversion: $ref: "#/components/schemas/DashboardMetric" cost: $ref: "#/components/schemas/DashboardMetric" cvr: $ref: "#/components/schemas/DashboardMetricNoTrend" events: $ref: "#/components/schemas/DashboardMetric" evr: $ref: "#/components/schemas/DashboardMetric" imp: $ref: "#/components/schemas/DashboardMetric" gross_sales: $ref: "#/components/schemas/DashboardMetric" security: - API Key: [] /advertisers/reporting/entity/table: post: summary: Get Entity Report (Table) tags: - Advertiser Reporting requestBody: required: true content: application/json: example: from: "2024-01-01" to: "2024-01-31" timezone_id: 67 currency_id: "USD" columns: - column: "offer" query: filters: [] schema: type: object required: - from - to - timezone_id - currency_id - columns properties: from: type: string description: Start date for the reporting period. Format `YYYY-MM-DD`. to: type: string description: End date for the reporting period. Format `YYYY-MM-DD`. timezone_id: type: integer description: Timezone identifier for the request. currency_id: type: string description: Currency code for monetary values (e.g. "USD"). columns: type: array minItems: 1 maxItems: 10 description: > Columns to group/pivot data by. Minimum 1, maximum 10. Only one time column (hour, date, week, month, year) is allowed per request. items: type: object required: - column properties: column: type: string enum: - offer - affiliate - creative - offer_url - country - country_code - region - city - dma - carrier - platform - isp - os_version - device_type - device_model - device_make - browser - language - sub1 - sub2 - sub3 - sub4 - sub5 - sub6 - sub7 - sub8 - sub9 - sub10 - source_id - connection_type - advertiser_campaign_name - app_identifier - bundle_id - meta_platform - score_rating - total_rating - size - developer - version - hour - date - week - month - year description: > The dimension to group by. Time columns (hour, date, week, month, year) are mutually exclusive — only one allowed at a time. query: type: object description: Query configuration for filtering, metric filtering, and exclusions. properties: filters: type: array description: > Filters to narrow results. Same resource_type filters use OR logic; different resource_type filters use AND logic. items: type: object required: - filter_id_value - resource_type properties: filter_id_value: type: string description: The value to filter on (e.g. offer ID, country name). resource_type: type: string description: The resource type / dimension to filter on. metric_filters: type: array description: >- Filters rows based on aggregated metric thresholds (e.g. return only rows where cost > 0). Applied after aggregation, before the row limit. items: type: object properties: metric_type: type: string enum: - impression - total_click - unique_click - cv - event - revenue - gross_sales description: >- The metric to filter on. Note: an advertiser's "cost" is the `revenue` metric — use `metric_type: revenue` to filter on cost. metric_value: type: number description: Threshold value. operator: type: string enum: - less_than - less_than_or_equal - greater_than - greater_than_or_equal description: Comparison operator. responses: "200": description: "" content: application/json: schema: type: object properties: table: type: array description: Array of reporting data rows grouped by the requested columns. items: type: object properties: columns: type: array description: Dimension values for this row. items: type: object properties: column_type: type: string description: The column/dimension type (matches the requested column value). id: type: string description: Dimension value identifier (e.g. offer ID, country name). label: type: string description: Human-readable label for the dimension value. reporting: $ref: "#/components/schemas/ReportingMetrics" security: - API Key: [] /advertisers/reporting/clicks/{transactionId}: get: summary: Get Click tags: - Advertiser Reporting parameters: - in: path name: transactionId required: true schema: type: string description: The click transaction ID. responses: "200": description: "" content: application/json: schema: type: object properties: transaction_id: type: string description: The click transaction ID. unix_timestamp: type: integer description: Unix timestamp of when the click occurred. user_ip: type: string description: IP address of the clicking user. is_unique: type: integer description: Whether this click is unique (1 = unique, 0 = not unique). is_view_through: type: boolean description: Whether this is a view-through click. has_conversion: type: boolean description: Whether this click resulted in a conversion. cost: type: number description: Cost amount for this click. cost_type: type: string description: Cost type for this click (e.g. cpa, cpc). currency_id: type: string description: Currency code (e.g. "USD"). tracking_url: type: string description: The tracking URL used for this click. url: type: string description: The destination URL. server_side_url: type: string description: Server-side tracking URL. coupon_code: type: string description: Coupon code associated with this click. project_id: type: integer description: Project ID. idfa: type: string description: Apple Identifier for Advertisers. idfa_md5: type: string description: MD5 hash of IDFA. idfa_sha1: type: string description: SHA1 hash of IDFA. google_ad_id: type: string description: Google Advertising ID. google_ad_id_md5: type: string description: MD5 hash of Google Advertising ID. google_ad_id_sha1: type: string description: SHA1 hash of Google Advertising ID. android_id: type: string description: Android device ID. android_id_md5: type: string description: MD5 hash of Android ID. android_id_sha1: type: string description: SHA1 hash of Android ID. relationship: type: object description: Related entities for this click. properties: offer: type: object properties: network_offer_id: type: integer description: Offer ID. network_id: type: integer description: Network ID. network_advertiser_id: type: integer description: Advertiser ID. name: type: string description: Offer name. offer_status: type: string description: Current status of the offer. network_tracking_domain_id: type: integer description: Tracking domain ID. affiliate: type: object properties: network_affiliate_id: type: integer description: Affiliate ID. network_id: type: integer description: Network ID. name: type: string description: Affiliate name. account_status: type: string description: Affiliate account status. geolocation: type: object description: Geolocation data for the click. properties: country_code: type: string description: ISO country code. country_name: type: string description: Country name. region_code: type: string description: Region/state code. region_name: type: string description: Region/state name. city_name: type: string description: City name. dma: type: integer description: Designated Market Area code. dma_name: type: string description: DMA name. timezone: type: string description: Timezone. carrier_name: type: string description: Mobile carrier name. carrier_code: type: string description: Mobile carrier code. organization: type: string description: Organization name. isp_name: type: string description: Internet service provider name. is_mobile: type: boolean description: Whether the connection is mobile. is_proxy: type: boolean description: Whether the connection is via proxy. postal_code: type: string description: Postal/ZIP code. device_information: type: object description: Device and browser information. properties: is_mobile: type: boolean description: Whether the device is mobile. platform_name: type: string description: Operating system platform name. os_version: type: string description: Operating system version. brand: type: string description: Device brand/manufacturer. model: type: string description: Device model name. is_tablet: type: boolean description: Whether the device is a tablet. browser_name: type: string description: Browser name. browser_version: type: string description: Browser version. device_type: type: string description: Device type classification. language: type: string description: Browser language. http_accept_language: type: string description: HTTP Accept-Language header value. is_robot: type: boolean description: Whether the user agent is a robot/bot. is_filter: type: boolean description: Whether the click was filtered. sub1: type: string description: Sub-placement value 1. sub2: type: string description: Sub-placement value 2. sub3: type: string description: Sub-placement value 3. sub4: type: string description: Sub-placement value 4. sub5: type: string description: Sub-placement value 5. sub6: type: string description: Sub-placement value 6. sub7: type: string description: Sub-placement value 7. sub8: type: string description: Sub-placement value 8. sub9: type: string description: Sub-placement value 9. sub10: type: string description: Sub-placement value 10. source_id: type: string description: Source ID. affiliate_id: type: integer description: Affiliate ID. "404": description: Click not found. security: - API Key: [] components: securitySchemes: API Key: description: > The advertiser's API key generated from the Advertiser Portal. Uses the same X-Eflow-Api-Key header as other Everflow APIs, but the key belongs to the advertiser user rather than the network admin. in: header name: X-Eflow-Api-Key type: apiKey schemas: ReportingMetrics: type: object description: Aggregated performance metrics. properties: imp: type: integer description: Impression count. total_click: type: integer description: Total click count. unique_click: type: integer description: Unique click count. invalid_click: type: integer description: Invalid/filtered click count. cv: type: integer description: Conversion count. event: type: integer description: Post-conversion event count. cvr: type: number description: Conversion rate (percentage). evr: type: number description: Event rate. ctr: type: number description: Click-through rate (impressions to clicks). cost: type: number description: Total cost (advertiser spend). cpc: type: number description: Cost per click. cpm: type: number description: Cost per mille (per 1,000 impressions). gross_sales: type: number description: Total gross sales amount. Conversion: type: object description: A single conversion record with full details. properties: conversion_id: type: string description: Unique conversion ID (UUID string). conversion_unix_timestamp: type: integer description: Unix timestamp of when the conversion occurred. cost_type: type: string description: Cost type for this conversion (e.g. cpa, cpc). cost: type: number description: Cost amount for this conversion. sale_amount: type: number description: Sale amount associated with this conversion. conversion_user_ip: type: string description: IP address of the converting user. session_user_ip: type: string description: IP address at time of the original click session. http_user_agent: type: string description: HTTP user agent string of the converting user. country: type: string description: Country of the converting user. region: type: string description: Region/state of the converting user. city: type: string description: City of the converting user. dma: type: integer description: Designated Market Area code. carrier: type: string description: Mobile carrier name. platform: type: string description: Operating system platform. os_version: type: string description: Operating system version. device_type: type: string description: Device type (e.g. desktop, mobile, tablet). browser: type: string description: Browser name. language: type: string description: Browser language. isp: type: string description: Internet service provider. adv1: type: string description: Advertiser sub-parameter 1. adv2: type: string description: Advertiser sub-parameter 2. adv3: type: string description: Advertiser sub-parameter 3. adv4: type: string description: Advertiser sub-parameter 4. adv5: type: string description: Advertiser sub-parameter 5. adv6: type: string description: Advertiser sub-parameter 6. adv7: type: string description: Advertiser sub-parameter 7. adv8: type: string description: Advertiser sub-parameter 8. adv9: type: string description: Advertiser sub-parameter 9. adv10: type: string description: Advertiser sub-parameter 10. transaction_id: type: string description: Click transaction ID associated with this conversion. is_event: type: boolean description: Whether this is a post-conversion event (true) or base conversion (false). event: type: string description: Event identifier string. click_unix_timestamp: type: integer description: Unix timestamp of the original click. currency_id: type: string description: Currency code (e.g. "USD"). order_id: type: string description: Order ID associated with this conversion. brand: type: string description: Device brand/manufacturer. coupon_code: type: string description: Coupon code used for this conversion. relationship: type: object description: Related entities for this conversion. properties: offer: type: object description: The offer associated with this conversion. properties: network_offer_id: type: integer description: Offer ID. network_id: type: integer description: Network ID. name: type: string description: Offer name. offer_status: type: string description: Current status of the offer. affiliate: type: object description: The affiliate associated with this conversion. properties: network_affiliate_id: type: integer description: Affiliate ID. network_id: type: integer description: Network ID. name: type: string description: Affiliate name. account_status: type: string description: Affiliate account status. events_count: type: integer description: Number of events associated with this conversion. offer_url: type: object description: The offer URL associated with this conversion. source_id: type: string description: Source ID. affiliate_id: type: integer description: Affiliate ID. sub1: type: string description: Sub-placement value 1. sub2: type: string description: Sub-placement value 2. sub3: type: string description: Sub-placement value 3. sub4: type: string description: Sub-placement value 4. sub5: type: string description: Sub-placement value 5. sub6: type: string description: Sub-placement value 6. sub7: type: string description: Sub-placement value 7. sub8: type: string description: Sub-placement value 8. sub9: type: string description: Sub-placement value 9. sub10: type: string description: Sub-placement value 10. DashboardMetric: type: object description: A dashboard metric with period comparisons and trending data. properties: current_month: type: number description: Value for the current month to date. last_month: type: number description: Value for the entire previous month. today: type: number description: Value for the current day so far. yesterday: type: number description: Value for the full previous day. trending_percentage: type: number description: Month-over-month trending percentage. DashboardMetricNoTrend: type: object description: A dashboard metric with period comparisons but no trending percentage (used for CVR). properties: current_month: type: number description: Value for the current month to date. last_month: type: number description: Value for the entire previous month. today: type: number description: Value for the current day so far. yesterday: type: number description: Value for the full previous day.