Everflow – User Guide

Docs: Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Summary

The Everflow API is organized around REST and uses built-in HTTP features (Verbs, Error Codes, etc.)

The host for all requests is https://api.eflow.team/v1^[1]. All requests must be made over HTTPS.

The JSON format is returned by all API responses, including errors.

[1]: A very small subset of Everflow accounts are hosted on EU servers only. For these accounts the host is `https://api-eu.eflow.team/v1`. Please speak to your account manager if you are unsure if this applies to you.

Making Requests

The Accept header is not required, though you can specify it using Accept : application/json

All requests must be authentified using your API Key (see Authentication section for more details). Requests made without authentication will fail.

Request Body

When submitting data to a resource via POST, PUT or PATCH, you must submit your payload in JSON.

{ "property" : "value" }

Authentication

All requests to the Everflow API must be authenticated using an API key.

To authenticate add a X-Eflow-API-Key header to your request that contains your API Key.

For example :

# Network API
curl -H "X-Eflow-API-Key: --your-api-key--" --url https://api.eflow.team/v1/networks

# Affiliate API
curl -H "X-Eflow-API-Key: --your-api-key--" --url https://api.eflow.team/v1/affiliates/affiliate

# Advertiser API
curl -H "X-Eflow-API-Key: --your-api-key--" --url https://api.eflow.team/v1/advertisers/advertiser

# Marketplace API
curl -H "X-Eflow-API-Key: --your-api-key--" --url https://api.eflow.team/v1/partners

Please note that using an API key for the wrong portal (e.g. using the Affiliate API key to access an Advertiser API endpoint) will result in a 403 error with the error message Out of realm.

API Keys

API Keys are generated directly in the Everflow UI.

Network API Keys

Network API keys are created from the “Security” section of the Control Center.

Each key has its own set of permissions, independant of the user it is associated with :

Note that while the API key name and permissions can be modified after the creation, the API key itself will only be shown once upon its creation and never again. Make sure to keep it somewhere safe and revoke it immediately if you suspect it has been compromised.

Affiliate API Keys

Affiliate API keys are created and managed by the network users. Affiliate users cannot create keys themselves and must rely on a network user to create the key and hand it over. API keys are created under the “API” tab in the Manage Affiliate section :

Advertiser API Keys

Advertiser API keys are also created and managed by the network users. Advertiser users cannot create keys themselves and must rely on a network user to create the key and hand it over. API keys are created under the “API Keys” tab in the Managed Advertiser section :

Marketplace API Keys

Marketplace API keys do not exist by default and must be requested to your account manager.

When a key does exist, it will appear under the API tab of the My Account section :

Docs: Rate Limiting

Mon, 01 Jan 0001 00:00:00 +0000

The Everflow API is subject to per entity rate limits

Quotas

Our system enforces rate limits according to the user type interacting with our services, and these limits are shared among all users within the same organization. For example, both Publisher A and Publisher B would be allocated 5 queries per second when accessing the API for the same Everflow client.

User	Queries per second
Network	20
Affiliate	5
Advertiser	5
Partner	5

Rate Limiting

Rate limiting resets every 30 seconds. Every request contains the following headers:

Header	Purpose
X-RateLimit-Limit	The number of requests you can make each 30 seconds
X-RateLimit-Remaining	The number of requests you can still make for the current 30 seconds window

Once you reach your limit, requests will all return a 429 error code until your 30 seconds window resets.

Concurrent Requests

On top of the rate limits, the number of concurrent requests is capped on reporting endpoints.

There can only be up to 10 concurrent requests made to the /v1/networks/reporting/* endpoints. Subsequence concurrent requests will return an error.

Granular Reports (BigQuery) Quotas

Most of the reporting endpoints in Everflow gets data in MySQL, but some data are only available in BigQuery. Calls using BigQuery are limited by hour. Please note that the Affiliate and Advertiser quotas is applicable to all activities at the network level, not per affiliate / advertiser.

User	Queries per hour
Network	1000
Affiliate	1000
Advertiser	1000

Important : The number of queries is rate limited per period of 60 minutes but doesn’t necessarily match the start and end of the hour. Rate limiting will kick in whenever the number of requests exceeds the limit over any rolling period of 60 minutes.

If a call contains at least one of the following columns, it is made in BigQuery.

Geolocation:

Country, Region, City, DMA, Carrier, ISP, Connection Type, Postal Code, Is Proxy

Device:

Platform, OS Version, Device Type, Browser, Device Brand, Language, Device Model, Device Make

Offer :

Offer Group, Offer URL, Event name, Advertiser Event Name, Payout Type, Payout Amount, Revenue Type, Revenue Amount, Custom Payout Revenue

Misc:

Adv1, Avd2, Adv3, Adv4, Adv5, Sub1, Sub2, Sub3, Sub4, Sub5, Source ID, Project ID, Referrer, Coupon Code, Tracking Domain, Order ID, Attribution Method, Account Referred By

Docs: Errors

Mon, 01 Jan 0001 00:00:00 +0000

All responses are returned in JSON format as specified in the Content-Type header.

Conventional HTTP response codes are used by the API to indicate the success or failure of an API request. Codes in the 2xx range indicate success whereas codes in the 4xx or 5xx range indicate failure.

Common Error Codes

Code	Description
400	Bad Request : The request could not be handled correctly, usually because of missing or malformed parameters
401	Unauthorized / No Authentication Method Found : The request could not be accepted, can be because the API Key is missing from the request
403	Forbidden / Out Of Realm : An API key was used, but it doesn’t allow access to the resource requested. Can be because the wrong API is being used (e.g. an Affiliate API key used on a Network API endpoint)
404	Not Found : The resource could not be found
429	Too Many Requests : The request could not be served as the API rate limiting restriction was enforced
500	Internal Server Error : Something went wrong on the Everflow end

Docs: Paging

Mon, 01 Jan 0001 00:00:00 +0000

Certain endpoints on the Everflow API return paginated responses. When that’s the case, the body of the response will include a paging object

Paging Object

"paging": {
    "page": 2,
    "page_size": 50,
    "total_count": 150
}

The page is a 1-based index (the first page is 1, not 0).

When paging information is not specified in the request, the first page is returned with a page_size of 50. The maximum page size is typically 2000 although some endpoints enforce a smaller maximum.

To request a specific page / page size, you must use the page and page_size in the query string of your request.

For example :

# Network API
curl -H "X-Eflow-API-Key: --your-api-key--" --url "https://api.eflow.team/v1/networks/offers?page=2&page_size=10"

# Affiliate API
curl -H "X-Eflow-API-Key: --your-api-key--" --url "https://api.eflow.team/v1/affiliates/offers?page=2&page_size=10"

Endpoints that return paginated responses are explicitly identified as such in the documentation.

Docs: API Filters

Mon, 01 Jan 0001 00:00:00 +0000

API filters can be used on certain “Find” endpoints. When available, the list of fields on which filtering is supported will be supplied in the endpoint’s description.

Usage

Enable a filter by supplying the filter query parameter. The format is the following: ?filter=<field><operator><value>.

Parameter	Description
field	The field to apply the filter on, varies based on endpoint
operator	The operator to apply. Supported operators are listed below
value	The value used by the filter

Operators

Operators are not URL safe so please use the encoded values unless you’re using an URL sanitizer.

Operator	Encoded Value
=	%3D
>	%3E
<	%3C

Code Example

This example demonstrates how to fetch affiliates whose status is active.

curl --request GET 'https://api.eflow.team/v1/networks/affiliates?filter=account_status%3Dactive' \
--header 'X-Eflow-API-Key: <INSERT API KEY>'

Docs: Relationships

Mon, 01 Jan 0001 00:00:00 +0000

Endpoints used to fetch information on the Everflow API return objects with a predefined structure. For example, when fetching an affiliate via the Find Affiliate By ID endpoint, only the Affiliate object is returned by default.

{
  "network_affiliate_id": 5,
  "network_id": 1,
  "name": "Google",
  "account_status": "active",
  "...": "..."
}

Relationships are used to extract additional information related to the object being queried. For example, when fetching an affiliate via the Find Affiliate By ID endpoint, requesting the users relationship would allow you to extract the affiliate users on top of the Affiliate object normally returned by the endpoint. The response would then look like :

{
  "network_affiliate_id": 5,
  "network_id": 1,
  "name": "Google",
  "account_status": "active",
  "...": "...",
  "relationship": {
    "users": {
      "total": 1,
      "entries": [
        {
          "network_affiliate_user_id": 12,
          "network_id": 1,
          "network_affiliate_id": 1,
          "first_name": "John",
          "last_name": "Doe",
          "...": "..."
        }
      ]
    }
  }
}

Requesting Relationships

You can ask for them using the relationship query parameter.

For example, fetching the affiliate ID 5 in the example above is done by making a GET call to /v1/networks/affiliates/5.

To modify the call and request the users relationship in the example above, the following URL would be queried instead : GET /v1/networks/affiliates/5?relationship=users

Note that multiple relationships can be requested at the same time. For example requesting both the users and signup relationships would be done by calling : GET /v1/networks/affiliates/5?relationship=users&relationship=signup

Availability

Relationships are not available on all endpoints. Endpoints where relationships are offered will be explicitly identified as such on the endpoint documentation.

Docs: Rulesets

Mon, 01 Jan 0001 00:00:00 +0000

A ruleset describes restrictions required for an action to happen, in the case of an offer, the ruleset is used to describe the offer’s targeting settings Offers and some offer related resources containing rules have a relationship key called ruleset.

The ruleset entity contains the following fields:

Geotargeting Rules

countries (find possible values here)
regions (find possible values here)
cities (find possible values here)
dmas (find possible values here)
postal_codes
mobile_carriers (find possible values here)

Device Characteristics Rules

browsers (find possible values here)
device_types (find possible values here)
brands (find possible values here)
os_versions (find possible values here)
platforms (find possible values here)

Connection Information Rules

isp
connection_types (find possible values here)

Matches

Each set of rule have two common fields:

targeting_type : include or exclude
match_type : exact, minimum, maximum or range depending on the type of rule
- exact : supported on countries, regions, cities, dmas, postal_codes, mobile_carriers, browsers, device_types, brands, platforms, ips
- maximum : supported on os_versions
- minimum : supported on os_versions
- range : supported on ips

Order of Precedence

Some rules precede others in the Geotargeting set of rules. The order is based on the specificity of the rule.

The specificity goes City > DMA > ZIP / Postal Code > Region > Country and the matching logic is the following:

As soon as we hit an “Include” for a rule more specific than the following then we don’t need to continue as even Excludes further down the chain are not enough to justify exclusion.

For example, including New York (City) and excluding United States (Country) is the same as just including New York (City).

Day Parting

The ruleset entity also contains fields related to Day Parting. Day Parting allows you to configure windows in which an action can happen.

The fields are the following:

is_use_day_parting
day_parting_apply_to
day_parting_timezone_id
days_parting

is_use_day_parting is a simple boolean flag enabling the day parting

day_parting_apply_to is an optional field, if is_use_day_parting is on, used to specify whether the day parting applies to the user timezone or a specific timezone. Supported values are user_timezone and selected_timezone

day_parting_timezone_id is an optional field, if day_parting_apply_to is set to specific_timezone, used to specify which timezone the day parting is applied to.

days_parting is an optional array field, if is_use_day_parting is on, used to specify rules. There is one entry per window, and there can be multiple windows per day.

For example, the following days_parting entry allows traffic on Tuesdays between 8 AM and 5PM

{
  "day_of_week": 2,
  "start_hour": 8,
  "start_minute": 0,
  "end_hour": 17,
  "end_minute": 0
}

The Ruleset Object

Rulesets are represented by a single json object. It’s the same format that will be used, whether you’re dealing with offer targeting or with custom payout revenue settings targeting.

Below are some examples :

Empty Ruleset

The simplest of all ruleset if one that allows for all traffic to come through. To create an empty ruleset, simply pass an empty json object :

"ruleset": {

}

Simple Rules

Not all types of rules need to be included. You can, for example, only target one type of rule. The following example is for a ruleset that allows traffic from the United States only.

"ruleset": {
  "countries": [
    {
      "country_id": 227,
      "match_type": "exact",
      "targeting_type": "include"
    }
  ]
}

You could target 2 countries at the same time :

"ruleset": {
  "countries": [
    {
      "country_id": 227,
      "match_type": "exact",
      "targeting_type": "include"
    },
    {
      "country_id": 36,
      "match_type": "exact",
      "targeting_type": "include"
    }
  ]
}

Please note that an include rule for "United States" mixed with an exclude rule for "Canada" is redundant as per the explanation in the section above. include "United States" is enough to exclude all other traffic.

Combining Rules

Rules of different types can be used at the same time. Here’s a more complex ruleset that must match ALL the following :

Comes from a device running iOS from version 9.0 to 11.4
Comes from New York City
Is on a mobile connection (as opposed to Wifi)
Is not from a known proxy

"ruleset": {
  "os_versions": [
    {
      "os_version_id": 16,
      "match_type": "minimum",
      "targeting_type": "include",
      "platform_id": 2
    },
    {
      "os_version_id": 33,
      "match_type": "maximum",
      "targeting_type": "include",
      "platform_id": 2
    }
  ],
  "cities": [
    {
      "city_id": 479,
      "match_type": "exact",
      "targeting_type": "include"
    }
  ],
  "connection_types": [
    {
      "match_type": "exact",
      "connection_type_id": 2,
      "targeting_type": "include"
    }
  ],
  "is_block_proxy": true
}

Specific Example : Day Parting

The following ruleset only accepts traffic from Monday to Thursday, 9 AM - 6 PM based on the device user’s timezone :

"ruleset": {
  "is_use_day_parting": true,
  "day_parting_apply_to": "user_timezone",
  "days_parting": [
    {
      "day_of_week": 1,
      "start_hour": 9,
      "end_hour": 18
    },
    {
      "day_of_week": 2,
      "start_hour": 9,
      "end_hour": 18
    },
    {
      "day_of_week": 3,
      "start_hour": 9,
      "end_hour": 18
    },
    {
      "day_of_week": 4,
      "start_hour": 9,
      "end_hour": 18
    }
  ]
}

Only on Saturday from noon until 2 PM UTC (regardless of the device user’s timezone) :

"ruleset": {
  "is_use_day_parting": true,
  "day_parting_apply_to": "selected_timezone",
  "day_parting_timezone_id": 67,
  "days_parting": [
    {
      "day_of_week": 6,
      "start_hour": 12,
      "end_hour": 14
    }
  ]
}

Specific Example : IP Ranges

The following ruleset will exclude all IPs in the [10.11.12.13 to 10.11.12.100] range as well as the 1.2.3.4 address

"ruleset": {
  "ips": [
    {
      "match_type": "range",
      "targeting_type": "exclude",
      "ip_from": "10.11.12.13",
      "ip_to": "10.11.12.100"
    },
    {
      "match_type": "exact",
      "targeting_type": "exclude",
      "ip_from": "1.2.3.4",
      "ip_to": "1.2.3.4"
    }
  ]
}

Specific Example : OS Versions

The following ruleset will allow all traffic from iOS version 12.0 and up

"ruleset": {
  "os_versions": [
    {
      "os_version_id": 34,
      "match_type": "minimum",
      "targeting_type": "include",
      "platform_id": 2
    }
  ]
}

Exclude all traffic Android for versions 7.0 and below

"ruleset": {
  "os_versions": [
    {
      "os_version_id": 7,
      "match_type": "maximum",
      "targeting_type": "exclude",
      "platform_id": 1
    }
  ]
}

Complete Ruleset

Although it’s very unlikely that you would ever want to use a ruleset like this, here is an example of a ruleset that combines every type of rule available :

"ruleset": {
    "platforms": [
        {
            "platform_id": 1,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "device_types": [
        {
            "device_type_id": 3,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "os_versions": [
        {
            "os_version_id": 32,
            "match_type": "minimum",
            "targeting_type": "include",
            "platform_id": 1
        },
        {
            "os_version_id": 45,
            "match_type": "maximum",
            "targeting_type": "include",
            "platform_id": 1
        }
    ],
    "browsers": [
        {
            "browser_id": 2,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "brands": [
        {
            "brand_id": 23,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "postal_codes": [
        {
          "postal_code": "90210",
          "targeting_type": "include",
          "match_type": "exact"
        },
        {
          "postal_code": "90211",
          "targeting_type": "include",
          "match_type": "exact"
        }
    ],
    "languages": [
        {
            "browser_language_id": 10,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "countries": [
        {
            "country_id": 227,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "regions": [
        {
            "region_id": 1140,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "cities": [
        {
            "city_id": 555,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "dmas": [
        {
            "dma_code": 807,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "isps": [
        {
            "isp_id": 3827,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "mobile_carriers": [
        {
            "mobile_carrier_id": 32,
            "match_type": "exact",
            "targeting_type": "include"
        }
    ],
    "connection_types": [
        {
            "match_type": "exact",
            "connection_type_id": 2,
            "targeting_type": "include"
        }
    ],
    "ips": [
        {
            "match_type": "range",
            "targeting_type": "exclude",
            "ip_from": "100.100.100.100",
            "ip_to": "100.100.100.255"
        }
    ],
    "is_use_day_parting": true,
    "is_block_proxy": true,
    "day_parting_apply_to": "selected_timezone",
    "day_parting_timezone_id": 90,
    "days_parting": [
        {
            "day_of_week": 1,
            "start_hour": 8,
            "end_hour": 17
        },
        {
            "day_of_week": 2,
            "start_hour": 8,
            "end_hour": 17
        }
    ]
}