Raw On Hold Conversions Report

Operations to fetch raw on hold conversions

The endpoints documented in this section allow you to pull on hold conversions and post-conversion events from the API. Each on hold conversion / event will be a “row” in the response as the data is not aggregated.

Note that currency conversion is not supported on raw on hold conversion endpoints. On hold conversions are always stored in the currency of the offer they belong to and this is how the endpoints return raw on hold conversions.

Requested intervals are limited to a maximum duration of one year. For example, requests with "from": "2022-01-01", "to": "2023-12-31" are considered invalid and will return an error.


On Hold Conversion Report

POST /v1/networks/reporting/onhold

The on hold conversion report is the most flexible way to extract a list of on hold conversions and post-conversion events. It allows you to fetch a list of on hold conversions and post-conversion events while specifying filters to narrow down the scope of the set of data you are pulling.

Each request must contain :

  • from and to dates (format can be YYYY-mm-DD or YYYY-mm-DD hh:mm:ss)
  • The timezone_id used for the request. Find all timezones here
  • A show_conversions boolean value that determines whether base conversions are returned (true / false)
  • A show_events boolean value that determines whether post-conversion events are returned (true / false)
  • The on_hold_status_filter used to filter on hold conversions based on their status. It can take the following values : on_hold, approved, rejected. It can be left empty if all on hold conversions need to be returned ("on_hold_status_filter": "").

Please note that the on hold conversion report is limited to the prior 365 days only. Requests outside of this range will result in an error.

Optional query filters can be added to the call

Paging

This endpoint supports paging. Refer to our User Guide for usage.

Query filters allow you to limit the scope of the report returned by the API. You could create a filter to limit the reporting data to a single offer for example. You can use multiple filters in a request.

Filters that apply to the same resource_type will act as OR operator. Different resource_type work with an AND operator. The following filters :

{
  //...
  "query": {
    "filters": [
      {
          "filter_id_value": "883",
          "resource_type": "offer"
      },
      {
          "filter_id_value": "518",
          "resource_type": "offer"
      },
      {
          "filter_id_value": "United States",
          "resource_type": "country"
      }
    ]
  }
}

translate to “Pull on hold conversions for US traffic on offer 883 OR offer 518”.

The resource-type used in the query filters can take the following values :

offer, transaction_id, campaign, adv1, adv2, adv3, adv4, adv5, offer_creative, coupon_code, dma, date, isp, carrier, sub1, sub2, sub3, sub4, sub5, source_id, language, device_brand, month, browser, country, platform, region, device_type, offer_url, os_version, city, week, country_code

Here are a few variations of what you can pass as a payload in ithe following call :

curl --request POST 'https://api.eflow.team/v1/networks/reporting/onhold' \
--header 'X-Eflow-API-Key: <INSERT API KEY>' \
--header 'Content-Type: application/json' \
--data '<INSERT PAYLOAD>'

Example 1 : Pull all on hold conversions (but no events) over a 1 hour period

{
    "from": "2022-02-08 13:00:00",
    "to": "2022-02-08 14:00:00",
    "timezone_id": 67,
    "show_conversions": true,
    "show_events": false,
    "on_hold_status_filter": "",
    "query":{
        "filters": []
    }
}

Example 2 : Pull pending on hold conversions and events on offer ID 800

{
    "from": "2022-02-07",
    "to": "2022-02-10",
    "timezone_id": 80,
    "show_conversions": true,
    "show_events": true,
    "on_hold_status_filter": "on_hold",
    "query":{
        "filters": [
            {
                "filter_id_value": "800",
                "resource_type": "offer"
            }
        ]
    }
}

Example 3 : Pull all on hold onversions and events that were generated from either of these 2 transaction IDs

{
    "from": "2022-02-01",
    "to": "2022-02-10",
    "timezone_id": 80,
    "show_conversions": true,
    "show_events": true,
    "on_hold_status_filter": "",
    "query":{
        "filters": [
            {
                "filter_id_value": "e33e03d630a04f499835cfa3d3158baf",
                "resource_type": "transaction_id"
            },
            {
                "filter_id_value": "2718b9f7adeb4d98869767bc1202edf5",
                "resource_type": "transaction_id"
            }
        ]
    }
}

A response from the on hold conversion report endpoint will look like :

{
	"conversions": [
		{
			"on_hold_conversion_id": "f9d3fa7e86d241afbec4a6c6c3fe2580",
            "network_id": 1,
            "holding_period_end": 1661980244,
            "status": "on_hold",
            "conversion": {
                "conversion_id": "",
                "conversion_unix_timestamp": 1643691617,
                "sub1": "inapp",
                "sub2": "external",
                "sub3": "",
                "sub4": "",
                "sub5": "facebook",
                "source_id": "1000",
                "status": "",
                "payout_type": "cpa",
                "revenue_type": "rpa",
                "payout": 0.8,
                "revenue": 1,
                "session_user_ip": "80.21.15.xxx",
                "conversion_user_ip": "1.2.3.4",
                "country": "Italy",
                "region": "Milano",
                "city": "Arluno",
                "dma": 0,
                "carrier": "",
                "platform": "iOS",
                "os_version": "10.3",
                "device_type": "Mobile",
                "device_model": "",
                "brand": "Apple",
                "browser": "Facebook for iOS",
                "language": "en",
                "http_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_3 like Mac OS X) AppleWebKit/603.3.8 (KHTML, like Gecko) Mobile/14G60 [FBAN/FBIOS;FBAV/141.0.0.51.91;FBBV/71695290;FBDV/iPhone9,2;FBMD/iPhone;FBSN/iOS;FBSV/10.3.3;FBSS/3;FBCR/AT&T;FBID/phone;FBLC/es_LA;FBOP/5;FBRV/0]",
                "adv1": "",
                "adv2": "",
                "adv3": "",
                "adv4": "",
                "adv5": "",
                "is_event": false,
                "event": "Example Event",
                "notes": "",
                "transaction_id": "042760c2eee8473fb17eec59dfe9de75",
                "click_unix_timestamp": 1643691604,
                "error_code": 0,
                "error_message": "N/A",
                "sale_amount": 96,
                "is_scrub": false,
                "coupon_code": "",
                "order_id": "",
                "url": "",
                "isp": "telecom italia s.p.a.",
                "referer": "",
                "app_id": "",
                "idfa": "",
                "idfa_md5": "",
                "idfa_sha1": "",
                "google_ad_id": "",
                "google_ad_id_md5": "",
                "google_ad_id_sha1": "",
                "android_id": "",
                "android_id_md5": "",
                "android_id_sha1": "",
                "currency_id": "USD",
                "email": "",
                "is_view_through": false,
                "previous_network_offer_id": 0,
                "relationship": {
                    "offer": {
                        "network_offer_id": 882,
                        "network_id": 1,
                        "name": "Example Offer",
                        "offer_status": "active"
                    },
                    "advertiser": {
                        "network_advertiser_id": 135,
                        "network_id": 1,
                        "name": "Advertiser Inc."
                    },
                    "account_manager": {
                        "network_employee_id": 15,
                        "network_id": 1,
                        "first_name": "John",
                        "last_name": "Doe",
                        "full_name": "John Doe",
                        "account_status": "active"
                    },
                    "affiliate": {
                        "network_affiliate_id": 102,
                        "network_id": 1,
                        "name": "Affiliate Inc.",
                        "account_status": "active"
                    },
                    "affiliate_manager": {
                        "network_employee_id": 8,
                        "network_id": 1,
                        "first_name": "Jane",
                        "last_name": "Doe",
                        "full_name": "Jane Doe",
                        "account_status": "active"
                    },
                    "query_parameters": {},
                    "attribution_method": "cookie",
                    "usm_data": null
                },
                "network_offer_payout_revenue_id": 0
            }
		},
		// ...
	],
	"paging": {
		"page": 1,
		"page_size": 2000,
		"total_count": 2
	}
}

On Hold Conversion Report Export

POST /v1/networks/reporting/onhold/export

The export endpoint is very similar to the report endpoint documented above but adds 2 possibilities :

  • It lets you “export” the data in CSV or JSON format
  • It optionally lets your specify the columns you want included in your report

Please note that when using the JSON format, the results will be newlined delimited JSON.

You must add the format properly to the payloads from the regular table endpoint for requests to work on this endpoint. The format can be either :

  • csv
  • json

The columns that will be included in the response can also be specified. The possible values are : offer, affiliate, advertiser, offer_group, campaign, affiliate_manager, creative, offer_url, category, previous_offer, source_id, sub1, sub2, sub3, sub4, sub5, adv1, adv2, adv3, adv4, adv5, country, region, city, platform, os_version, isp, account_manager, android_id, android_id_md5, android_id_sha1, app_id, brand, browser, carrier, click_date, conversion_id, conversion_user_ip, coupon_code, currency, delta_hours, device, email, error_message, event_name, google_ad_id, google_ad_id_md5, google_ad_id_sha1, http_user_agent, idfa, idfa_md5, idfa_sha1, language, notes, order_id, order_line_items, order_number, payout, payout_type, referrer, revenue, revenue_type, sale_amount, session_ip, transaction_id, type, conversion_status, conversion_date, origin, network_id, payout_revenue_id, project_id, dma, is_cookie_based, previous_transaction_id, is_event_protected, is_fired_pixel, is_scrub, is_view_through, attribution_method, country_code, on_hold_conversion_id, holding_period_end, and on_hold_status

cURL
curl --request POST 'https://api.eflow.team/v1/networks/reporting/onhold/export' \
--header 'X-Eflow-API-Key: <INSERT API KEY>' \
--header 'Content-Type: application/json' \
--data '<INSERT PAYLOAD>'

Example : Export approved on hold conversions on offer 800 in JSON format. Only include 5 specific columns.

{
    "from": "2022-02-07",
    "to": "2022-02-10",
    "timezone_id": 80,
    "show_conversions": true,
    "show_events": true,
    "on_hold_status_filter": "approved",
    "query":{
        "filters": [
            {
                "filter_id_value": "800",
                "resource_type": "offer"
            }
        ]
    },
    "columns": [
        "on_hold_conversion_id", "offer", "affiliate", "transaction_id", "conversion_id"
    ],
    "format": "json"

}


On Hold Conversion By ID

GET /v1/networks/reporting/onhold/:onHoldId

Fetch a single on hold conversion by its unique on hold conversion ID.

Path Parameters

Parameter Description
onHoldId The ID of the on hold conversion (32 char)

cURL
curl --request GET 'https://api.eflow.team/v1/networks/reporting/onhold/<32 char On Hold Conversion ID>' \
--header 'X-Eflow-API-Key: <INSERT API KEY>'
Response
{
	"on_hold_conversion_id": "f9d3fa7e86d241afbec4a6c6c3fe2580",
    "network_id": 1,
    "holding_period_end": 1661980244,
    "status": "on_hold",
    "conversion": {
        "conversion_id": "",
        "conversion_unix_timestamp": 1643691617,
        "sub1": "inapp",
        "sub2": "external",
        "sub3": "",
        "sub4": "",
        "sub5": "facebook",
        "source_id": "1000",
        "status": "",
        "payout_type": "cpa",
        "revenue_type": "rpa",
        "payout": 0.8,
        "revenue": 1,
        "session_user_ip": "80.21.15.xxx",
        "conversion_user_ip": "1.2.3.4",
        "country": "Italy",
        "region": "Milano",
        "city": "Arluno",
        "dma": 0,
        "carrier": "",
        "platform": "iOS",
        "os_version": "10.3",
        "device_type": "Mobile",
        "device_model": "",
        "brand": "Apple",
        "browser": "Facebook for iOS",
        "language": "en",
        "http_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_3 like Mac OS X) AppleWebKit/603.3.8 (KHTML, like Gecko) Mobile/14G60 [FBAN/FBIOS;FBAV/141.0.0.51.91;FBBV/71695290;FBDV/iPhone9,2;FBMD/iPhone;FBSN/iOS;FBSV/10.3.3;FBSS/3;FBCR/AT&T;FBID/phone;FBLC/es_LA;FBOP/5;FBRV/0]",
        "adv1": "",
        "adv2": "",
        "adv3": "",
        "adv4": "",
        "adv5": "",
        "is_event": false,
        "event": "Example Event",
        "notes": "",
        "transaction_id": "042760c2eee8473fb17eec59dfe9de75",
        "click_unix_timestamp": 1643691604,
        "error_code": 0,
        "error_message": "N/A",
        "sale_amount": 96,
        "is_scrub": false,
        "coupon_code": "",
        "order_id": "",
        "url": "",
        "isp": "telecom italia s.p.a.",
        "referer": "",
        "app_id": "",
        "idfa": "",
        "idfa_md5": "",
        "idfa_sha1": "",
        "google_ad_id": "",
        "google_ad_id_md5": "",
        "google_ad_id_sha1": "",
        "android_id": "",
        "android_id_md5": "",
        "android_id_sha1": "",
        "currency_id": "USD",
        "email": "",
        "is_view_through": false,
        "previous_network_offer_id": 0,
        "relationship": {
            "offer": {
                "network_offer_id": 882,
                "network_id": 1,
                "name": "Example Offer",
                "offer_status": "active"
            },
            "advertiser": {
                "network_advertiser_id": 135,
                "network_id": 1,
                "name": "Advertiser Inc."
            },
            "account_manager": {
                "network_employee_id": 15,
                "network_id": 1,
                "first_name": "John",
                "last_name": "Doe",
                "full_name": "John Doe",
                "account_status": "active"
            },
            "affiliate": {
                "network_affiliate_id": 102,
                "network_id": 1,
                "name": "Affiliate Inc.",
                "account_status": "active"
            },
            "affiliate_manager": {
                "network_employee_id": 8,
                "network_id": 1,
                "first_name": "Jane",
                "last_name": "Doe",
                "full_name": "Jane Doe",
                "account_status": "active"
            },
            "query_parameters": {},
            "attribution_method": "cookie",
            "usm_data": null
        },
        "network_offer_payout_revenue_id": 0
    }
}