Raw Conversions Report

Operations to fetch raw conversions

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

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


Conversion Report

POST /v1/networks/reporting/conversions

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

If you are only looking to pull a limited set of columns in your response, you must use the Conversion Report Export endpoint documented below.

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)

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 partner 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 conversions for US traffic on offer 883 OR offer 518”.

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

offer, offer_group, affiliate, advertiser, offer_creative, transaction_id, campaign, billing_frequency, business_unit, label, category, sub1, sub2, sub3, sub4, sub5, source_id, country, account_manager, affiliate_manager, status, sales_manager, account_executive, offer_url, currency_id, affiliate_tier, adv1, adv2, adv3, adv4, adv5, browser, carrier, city, coupon_code, dma, device_brand, device_type, isp, language, os_version, platform, region, order_id

Conversion reports support a few more options :

  • show_only_scrub : defaults to false when omitted – can be used to isolate conversions that were throttled
  • show_only_vt : defaults to false when omitted – can be used to isolate view-through conversions
  • show_only_ct : defaults to false when omitted – can be used to isolate click-through events
  • show_only_fail_traffic : defaults to false when omitted – can be used to isolate conversion and events that come from fail traffic
{
  "from": "2021-10-12",
  //...
  "show_only_scrub": true,
  "show_only_vt": false,
  "show_only_ct": false,
  "show_only_fail_traffic": false,
  "query": {
    // ...
  }
}

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/conversions' \
--header 'X-Eflow-API-Key: <INSERT API KEY>' \
--header 'Content-Type: application/json' \
--data '<INSERT PAYLOAD>'

Example 1 : Pull all approved base conversions 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,
    "query":{
        "filters": [
            {
                "filter_id_value": "approved",
                "resource_type": "status"
            }
        ]
    }
}

Conversion status is either approved, pending, rejected or invalid

Example 2 : Pull pending view-through conversions on offer ID 800

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

Example 3 : Pull all conversions 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,
    "query":{
        "filters": [
            {
                "filter_id_value": "e33e03d630a04f499835cfa3d3158baf",
                "resource_type": "transaction_id"
            },
            {
                "filter_id_value": "2718b9f7adeb4d98869767bc1202edf5",
                "resource_type": "transaction_id"
            }
        ]
    }
}

Example 4 : Pull base conversions that were generated from a specific advertiser

{
    "from": "2022-02-01",
    "to": "2022-02-01",
    "timezone_id": 90,
    "show_conversions": true,
    "show_events": true,
    "query":{
        "filters": [
            {
                "filter_id_value": "135",
                "resource_type": "advertiser"
            }
        ]
    }
}

A response from the conversion report endpoint will look like :

{
    "conversions": [
        {
            "conversion_id": "5d6de3955fcd473fa19ddf33ef9a3b8f",
            "conversion_unix_timestamp": 1643691617,
            "sub1": "inapp",
            "sub2": "external",
            "sub3": "",
            "sub4": "",
            "sub5": "facebook",
            "source_id": "1000",
            "status": "approved",
            "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": 50,
        "total_count": 3443
    }
}

Conversion Report Export

POST /v1/networks/reporting/conversions/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, status, conversion_date and origin

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

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

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

}


Conversion By ID

GET /v1/networks/reporting/conversions/:conversionId

Fetch a single conversion by its unique conversion ID.

Path Parameters

Parameter Description
conversionId The ID of the conversion (32 char)

cURL
curl --request GET 'https://api.eflow.team/v1/networks/reporting/conversions/<32 char Conversion ID>' \
--header 'X-Eflow-API-Key: <INSERT API KEY>'
Response
{
    "conversion_id": "4b66e71ab68842698fe51002336ff9f9",
    "conversion_unix_timestamp": 1643692518,
    "sub1": "internal",
    "sub2": "gaming",
    "sub3": "facebook",
    "sub4": "",
    "sub5": "",
    "source_id": "55783",
    "status": "approved",
    "payout_type": "cpa",
    "revenue_type": "rpa",
    "payout": 3.5,
    "revenue": 7,
    "session_user_ip": "208.75.21.101",
    "conversion_user_ip": "184.151.111.228",
    "country": "United States",
    "region": "Michigan",
    "city": "Ann Arbor",
    "dma": 505,
    "carrier": "",
    "platform": "Android",
    "os_version": "5.1",
    "device_type": "Mobile",
    "device_model": "",
    "brand": "LG",
    "browser": "",
    "language": "",
    "http_user_agent": "Dalvik/2.1.0 (Linux; U; Android 5.1.1; LG-K330 Build/LMY47V)",
    "adv1": "",
    "adv2": "",
    "adv3": "",
    "adv4": "",
    "adv5": "",
    "is_event": false,
    "event": "",
    "notes": "",
    "transaction_id": "8595ae3b74e841bc9bbcc1560e61283e",
    "click_unix_timestamp": 1643692502,
    "error_code": 0,
    "error_message": "N/A",
    "sale_amount": 35,
    "is_scrub": false,
    "coupon_code": "",
    "order_id": "",
    "url": "",
    "isp": "synergy broadband",
    "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": 77,
            "network_id": 1,
            "name": "Example Gaming Offer",
            "offer_status": "active"
        },
        "advertiser": {
            "network_advertiser_id": 11,
            "network_id": 1,
            "name": "Advertiser Inc."
        },
        "account_manager": {
            "network_employee_id": 15,
            "network_id": 5,
            "first_name": "John",
            "last_name": "Doe",
            "full_name": "John Doe",
            "account_status": "active"
        },
        "affiliate": {
            "network_affiliate_id": 14,
            "network_id": 1,
            "name": "Affiliate Inc.",
            "account_status": "active"
        },
        "affiliate_manager": {
            "network_employee_id": 87,
            "network_id": 1,
            "first_name": "Jane",
            "last_name": "Doe",
            "full_name": "Jane Doe",
            "account_status": "active"
        },
        "query_parameters": {
            "amount": "3",
            "nid": "1",
            "transaction_id": "8595ae3b74e841bc9bbcc1560e61283e"
        },
        "redirect_url": "https://everflow-example.io/?id=8595ae3b74e841bc9bbcc1560e61283e",
        "snapshots": [ ],
        "attribution_method": "transaction_id",
        "usm_data": null
    },
    "network_offer_payout_revenue_id": 0
}


Conversion By Email

POST /v1/networks/reporting/conversions/email

This endpoint can be used to extract a list of conversions / events associated with an email address. The endpoint will return a maximum of 100 conversions (the most recent 100 ones).

Note that conversions older than 1 year may be archived and will not be returned by this endpoint.

The endpoint doesn’t take any filters, only a single email property in the body of the request.

cURL
curl --request POST \
  --url https://api.eflow.team/v1/networks/reporting/conversions/email \
  --header 'Content-Type: application/json' \
  --header 'X-Eflow-API-Key: <INSERT API KEY>' \
  --data '{
    "email": "test@example.com"
  }'
Response
{
  "conversions": [
    {
      "conversion_id": "1f4a38f373eb12348ba477d3a5b7b65f",
      "conversion_unix_timestamp": 1634568781,
      "sub1": "google",
      "sub2": "facebook",
      "sub3": "",
      "sub4": "",
      "sub5": "",
      "source_id": "",
      "status": "approved",
      "payout_type": "cpa",
      "revenue_type": "rpa",
      "payout": 0,
      "revenue": 0,
      "session_user_ip": "1.2.3.4",
      "conversion_user_ip": "10.11.12.13",
      "country": "United States",
      "region": "Wisconsin",
      "city": "Sister Bay",
      "dma": 658,
      "carrier": "",
      "platform": "Android",
      "os_version": "10.0",
      "device_type": "Mobile",
      "device_model": "",
      "brand": "Samsung",
      "browser": "Chrome",
      "language": "en",
      "http_user_agent": "Mozilla/5.0 (Linux; Android 11; SM-G973U) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.85 Mobile Safari/537.36",
      "adv1": "",
      "adv2": "",
      "adv3": "",
      "adv4": "",
      "adv5": "",
      "is_event": true,
      "event": "Purchase",
      "notes": "",
      "transaction_id": "78ac316a238b59d48f564431008fd481",
      "click_unix_timestamp": 1634568743,
      "error_code": 0,
      "error_message": "N/A",
      "sale_amount": 0,
      "is_scrub": false,
      "coupon_code": "",
      "order_id": "",
      "url": "",
      "isp": "charter communications",
      "referer": "example.org",
      "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": "test@example.com",
      "is_view_through": false,
      "previous_network_offer_id": 0,
      "relationship": {
        "offer": {
          "network_offer_id": 5,
          "network_id": 1,
          "name": "Example Offer",
          "offer_status": "active"
        },
        "advertiser": {
          "network_advertiser_id": 2,
          "network_id": 1,
          "name": "Advertising Revolution"
        },
        "account_manager": {
          "network_employee_id": 1,
          "network_id": 1,
          "first_name": "John",
          "last_name": "Doe",
          "full_name": "John Doe",
          "account_status": "active"
        },
        "affiliate": {
          "network_affiliate_id": 10,
          "network_id": 1,
          "name": "Some Affiliate",
          "account_status": "active"
        },
        "affiliate_manager": {
          "network_employee_id": 1,
          "network_id": 1,
          "first_name": "John",
          "last_name": "Doe",
          "full_name": "John Doe",
          "account_status": "active"
        },
        "query_parameters": {},
        "attribution_method": "unknown",
        "usm_data": null
      },
      "network_offer_payout_revenue_id": 100
    }
  ]
}