User Level Revenue API Overview

1. Overview

Tapjoy now enables publishers to access their Offerwall user level ad revenue data via a User Level Ad Revenue API, in addition to our existing offer data callbacks. This API makes User Level Ad Revenue reports available directly to Mobile Measurement Partners (MMPs) or Publisher Partners via a CSV file stored in Amazon Web Services (AWS) S3.

In order to make the requests, users will need the relevant Tapjoy App ID (the same one associated with the app for the Tapjoy LTV dashboard) and the date for which data is desired.

To use the API, the MMP or Partner must make a request to the Tapjoy OAuth endpoint with their Marketing API key to receive an access token. With the access token, the user then makes a request to the Tapjoy Report API to receive the pre-signed URLs pointing to the reports in AWS S3. The pre-signed URLs will allow access to the reports for 5 min following retrieval. Lastly, a request to the report URLs in AWS S3 will return the CSV reports containing the User Level Ad Revenue data.

2. Report API

Endpoint

https://api.tapjoy.com/api/client/publisher/apps/<app_id>/user_revenue_report

Accessible via OAuth with your Marketing API key.

Required parameters:

  • Publisher app ID
  • Date in UTC

Acceptable date formats are mm/dd, mm/dd/yyyy, mm/dd/yy, dd-mm yyyy-mm-dd, yy-mm-dd

Returns an array of urls to the static report(s) with a pre-signed authentication token which is valid for 5 min.

Example Request

GET api/client/publisher/apps/<publisher_app_id>/user_revenue_report?date=<date> 
Host: api.tapjoy.com 
Authorization: Bearer <access_token_string> 
Accept: application/json; */* 

Example Response

Success


{
	"urls": [
	"https://tapjoy.amazon.s3.com/data/report.csv.gz&key=secure"
  	  ]
}

Failure


status 404 
{ 
	“reason”: “No publisher app with id <publisher_app_id> found.” 
}

3. S3 API

Data SLA - data for day x to be ready by day x+1 at 01:00 UTC

Retention SLA - reports are available for 14 days (day x + 15)

Returns a CSV file of the User Level Revenue report

Example Request

GET /data/report.csv.gz&key=secure
Host: tapjoy.amazon.s3.com 
Accept: application/json; */* 

Example Response

Success


status 200 
{ 
	CSV File
}

Failure(s)


status 401 
{ 
	“error”: “Unauthorized” 
}

status 404 
{ 
	“error”: “Not Found” 
}

5. FAQ

Does this report include video revenue?

No, this report includes Offerwall ad revenue only. If user level ad revenue data is desired, then Partners should contact their mediator on accessing an applicable API or report.

How far back does this report look?

Reports are accessible for Publisher Partners to access for 14 days and each day at 1:00 AM UTC the previous day’s report will be available.

Why do some user level entries have zero values in the impression column but non-zero values for revenue?

For the MR-CPE product, there is often a delay (days or even weeks) between when the impression was shown and when the event conversions happen later in the multi-reward funnel.

What currency is my publisher revenue amount shown in?

It’s shown in United States Dollars (USD)

Which MMPs are currently supporting the API?

Appsflyer.