DT FairBid User Level Reporting API

The DT FairBid User Level Reporting API enables you to access reporting data to measure all revenue generated from individual users. This information can be used to optimize retargeting campaigns and accurately measure user lifetime value.

You can query revenue and impression metrics across the available dimensions. For all supported metrics and dimensions for the User Level Reporting API, click the Metrics and Dimensions tab above.

Some programmatic networks do not disclose their exact CPM bids to publishers for the purpose of calculating user-level revenues. In such cases, DT uses approved methods to base the user-level revenue calculations on close estimates. When a non-disclosing network wins an impression we calculate the price of the impression based on the second-highest bid of every auction and perform a revenue aggregation on a user level. This value is close to the actual revenue generated for impressions and therefore for the users, too.

Naturally, when estimates are being used, gaps in total revenues are formed. Therefore, in every report that includes non-disclosing networks, we will add a row called "aggregated masked user level revenue". This row, not representing a real user, accounts for any gap in total daily revenues that may be formed. That way, when you compare the total revenue generated from the user-level reporting APIs to those generated from less granular reporting APIs, the sum of revenues will be equal.

The User Level Reporting API is disabled by default for any new app onboarding. To enable it, contact your Account Manager. Once enabled, data is aggregated from six days prior to the activation date.

Reporting API Workflow

The publisher makes a POST request using the Client ID and Client Secret to receive the Access Token, as described in Step 1.

Once the request is successful and the Access Token is received, an API Request is made to create a custom report as described in Step 2. A successful response will contain a URL leading to a file containing the custom report. More details can be found in Step 3.

Step 1: Obtaining the Access Token

DT's Reporting API uses Access Tokens for authentication purposes. To obtain your Access Token, you must first get your Client ID and Client Secret. See Obtaining Verification Keys.

Make a POST request

The base End Point for the entire process is: https://reporting.fyber.com

Authentication Token

POST /auth/v1/token

Headers

Content-Type    application/json

Sample Request

https://reporting.fyber.com/auth/v1/token

Params

format  csv

Body: raw (application/json)

JSON

{
    "grant_type": "client_credentials",
    "client_id": "3ce66d885XXXXXXXXXXa3b752bb9058",
    "client_secret": "YtMvC7VYTQMQ7w9UCUaFTRGJnwVZnQqqN02XNyt8IIh2h8XFDuXXXXXXXXSS6XTrFWW4TkebCcMLJkrXSw5IurkearTJIDzUxsbiMXv8hb4T23MwN6eE7DDIthRFqDnhnuhiDlY2oPeaOjsMbzE8joZ5cs6tsySJz6uZXwJ-x3lcYaYbgXXXXXXXX3_hFeuXm-C7-me2V1MMs-ftJxTd5QbHoUhG3Q5anCWCW_pg8x3CL4yPGCbpWUDZfpdNPyyCT4rxCEb-VC0Bdqwe8N2GGn_VSFOwQYxa-yap2JuNSGJfl_ZURXXXXXXXXFe1GpHDn8pk7yYwQYIGAg"
}

Grant Type must be "client_credentials". The credentials are sent according to the OAuth 2.0 protocol.

Sample Authentication Responses

When an authentication request is successful, you receive the following response in JSON format:

Successful Response

JSON

{
  "accessToken": "eyJhbGciXXXXXXXXXXIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1NzAwMTY5MDAsImV4cCI6MTU3MDAyMDUwMCwiYXVkIjoic3BlZWRiYWxsIiwic3ViIjoiMjEwMjYzIn0.hDo1waTytSys_oRhFNUPqZPom26bL05rxgtSt3XYHqI",
  "tokenType": "bearer",
  "expiresIn": 3600
}

accessToken: The token required to continue the process

tokenType: Bearer

expiresIn: 3600 seconds (1 hour)

When a request is unsuccessful, you receive the following response:

Unsuccessful Response

JSON

{
  "error": "internal_server_error"
}

Possible Authentication Errors

Set out in the table is a list of possible errors which resulted in an unsuccessful response.

HTTP Status Code	Error	Scenario
400	unsupported_grant_type	N/A
400	invalid_request	When there are missing credentials
400	invalid_client	When the credentials are incorrect or cannot be recognized. Can also occur when your account has been disabled or when the credentials have been revoked.
500	internal_server_error	Unexpected errors in DT's servers

Step 2: Reporting API Request

Use the access token you received in Step 1 to request your custom report.

The two dimensions that you can query in your request are:

• Date

• App ID

All other dimensions always appear in the report.

Request Example

Below is presented a POST request to receive a User Level report for the following criteria:

• Date: 2020-02-16

• AppID: 123

URL

https://reporting.fyber.com/api/v1/report/user-level-data

Headers

Content-Type:   application/json
Authorization: Bearer <Access Token from Authentication Response>

Body. raw (application/json)

JSON

{
    “date”: “2020-01-01",
    “appId”: “123"
}

Responses

Set out below are examples of both successful and unsuccessful responses.

Response: Successful

JSON

{
  "id": "XXXXXXXX-25db-4af0-8988-1e7d8e6d90bc",
  "url": "https://fyber-async-reports.s3.amazonaws.com/group%3D210263/XXXXXXXX-25db-4af0-8988-1e7d8e6d90bc.csv?AWSAccessKeyId=AKIAQBQNZ5FYXXXXXXXX&Expires=1570020564&Signature=LbhE5uljlPEKQRTbepDqmDXXXXXXXX",
}

• The "id" field holds an identifier of the request for later troubleshooting, if required.

• The "url" field holds the URL to be polled (GET request) until the body response (file) is populated.

Response: Unsuccessful

JSON

{
  "error": "invalid_token"
}

Possible Errors

The table below shows the main errors indicating an unsuccessful response.

HTTP Status Code	Error	Description (optional)	Scenario
401	invalid_token	N/A	Authorization header is empty Authorization header not sent or token is not present in the header Unrecognized token Disabled account
400	invalid_query	For example: Invalid value undefined supplied to : Query/dateRange: DateRange -or- Invalid value "XXXXX" supplied to : Query/dateRange: DateRange/end: Date	If the query sent is not in the expected schema Date range is not sent in the ISO 8601 format
500	internal_server_error	N/A	Error in DT's servers

Step 3: Receiving the Custom Report

To obtain the Custom Report, follow the steps below:

1. Receive the URL from the successful response in Step 2.

2. Click the link. You are redirected to a folder which contains your report.

The URL is valid for three hours.

Additional Information and Restrictions

It is important to take note of the information, restrictions and rules to ensure the reports provided to ensure a successful response.

General

• All reports are presented in US dollars

• The time zone used is UTC

• The data in the folder is available by 1200 UTC (noon) for the previous 10 days.

Query Restrictions

• All dimensions are mandatory.

Date Information

There are a number of rules that must be observed with regard to the date:

• The date must be in the format of ISO 8601. For example, 2019-10-03

• The date is included in the report

• The date is relevant from 16 February 2020

Supported Metrics and Dimensions

You must specify in the API Request the metrics and dimensions you want to include in your custom report. Set out in the tables below are the supported metrics and dimensions available in the User Level Reporting API.

Metrics

Source	Supported Metrics	Description
User Level	Impressions	Number of times the ad is displayed to the users
	Revenue	The total revenue of the publisher in USD

Dimensions

Source	Supported Dimensions	Description
User Level	Ad Network Name	For mediation, we use the network name and for DT Exchange networks we use 'DT Exchange'
	Ad Unit ID	The ad unit identifier in the DT system relating to the placement.
	Advertising ID	The Advertising ID for either Apple or Google
	IDFV	An alphanumeric string that uniquely identifies a device to the app’s vendor. (This dimension is relevant to DT FairBid customers only).
	User ID	The identifier of the user supplied by the publisher. (This dimension is relevant to DT FairBid customers only).
	Instance ID	The Instance ID as generated by the demand network. Note: This is referred to differently, by various demand networks.
	Placement ID	A Placement's identifier in the DT system
	Placement Type	Placement type describes how ads appear in your app and where ads are located. Placement types can be either banner, interstitial or rewarded.