# Reporting API {% hint style="info" %} This guide is intended for Advertisers using DT Offer Wall Reporting API. {% endhint %} This Reporting API enables you to access all the reporting data related to monetization of your DT Offer Wall. You can query multiple metrics such as revenue and impressions across the available dimensions and even implement filters. For supported metrics and dimensions for Advertisers, see [DT Offer Wall Report Dimensions for Advertisers](https://docs.digitalturbine.com/dt-offer-wall/publishers/reporting/dt-offer-wall-report-for-publishers#offer-wall-report-dimensions-for-publishers). ## DT Offer Wall 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](#h_01hgb71v3shmvfh8838an5fng7). 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](#h_01hgb71v3ttvmpj39867je9dvf). A successful response will contain a URL leading to a file that will be populated with the custom report. More details can be found in [Step 3](#h_01hgb71v3xnfj78thywfyzy6zt). ## 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. Obtaining your Client ID and Client Secret 1. Sign in to the [DT Console](https://console.fyber.com/login). 2. On the left menu bar, click **Users.**

3. Click User Profile to display the Reporting API Keys.

4. Click User Profile to display the Reporting API Keys.

If necessary, you can click **Revoke** to delete the current credentials.\ You are returned to the API Keys window. 5. Click **Generate New Keys** to receive new credential.

Keep your Client ID and Client Secret safe, as they can be reused in the future. Using your Client ID and Client Secret make a POST request to receive your Access Token. 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)** ``` { "grant_type": "client_credentials", "client_id": "3ce44d885XXXXXXXXXXa3b752cc9128", "client_secret": "YtMvC7VYTQMQ7w9UCUaFTRGJnwVZnQqqN02XNyt8IIh2h8XFDuXXXXXXXXSS6XTrFWW4TkebCcMLJkrXSw5IurkearTJIDzUxsbiMXv8hb4T55MwN6eE7DDIthRFqDnhnuhiDlY2oPeaOjsMbzE8joZ5cs6tsySJz6uZXwJ-x3lcYaYbgXXXXXXXX3_hFeuXm-C7-me2V1MMs-ftJxTd5QbHoUhG3Q5anCWCW_pg8x3CL4yPGCbpWYYZfpdNPyyCT4rxCEb-VC0Bdqwe8N2GGn_VSFOwQYxa-yap2JuNSGJfl_ZURXXXXXXXXFe1GpHDn8pk7yYwQYIGAg" } ``` {% hint style="info" %} **Grant Type** must be "client\_credentials". The credentials are sent according to the **OAuth 2.0 protocol** {% endhint %} ### Sample Authentication Response When an authentication request is successful, you receive the following response in JSON format: Successful Response ``` { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpABCiOjE1NzAwMTY5MDAsImV4cCI6MTU3MDAyMDUwMCwiYXVkIjoic3BlZWRiYWxsIiwic3ViIjoiMjEwMjYzIn0.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** ``` { "error": "internal_server_error" } ``` ### Possible Authentication Errors Set out in the table are a list of possible errors which resulted in an unsuccessful response. | HTTP Status Code | Error | Scenario | | ---------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | unsupported\_grant\_type | Invalid grant type | | 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](#h_01hgb71v3shmvfh8838an5fng7) to request your custom report. The request is made up of five individual sections: * Source * Date Range * Metrics * Splits * Filters (include) #### Request Example **Source** The below is an example from the DT Offer Wall report. The source can either "performance" or "event" - depending on the view you want to see. **Performance** based view. Every action/revenue metric, is attributed to the time of the click and impression. This view allows a clear understanding of how your manipulations impact performance. **Event** based view (Billing). Every action/revenue metric is attributed to the time it happened. This view allows a clear understanding of the periodical revenues conversions and other events, as they happened. **This data pulled from this view matches your monthly billed invoice.** * Source must be in lower case. Date Range Start date: 2019-01-06\ End date: 2019-09-25 Metrics * Advertiser Spend * Advertiser ARPU * Offer Impressions * Offer Clicks Splits (dimensions) * Country Filters * Dimension filtered is the country * Values filtered are US, CA and RU For a full list of supported Metrics and Dimensions per report, see [Supported Metrics and Dimensions](https://docs.digitalturbine.com/dt-offer-wall/advertisers/reporting/reporting-api/supported-metrics-and-dimensions). For further descriptions about the terms used in this article, see [Using the Reports](https://app.gitbook.com/s/LbREhkP3WlLtP6TNVZ2Q/reports/using-the-reports). URL ``` POST https://reporting.fyber.com/api/v1/report/offerwall?format=csv ``` Headers ``` Content-Type: application/json Authorization: Bearer ``` Params ``` format csv ``` Body. raw (application/json) ```json { "source": "event", "dateRange": { "start": "2019-11-01", "end": "2019-12-01" }, "metrics": [ "Advertiser Spend", "Advertiser ARPU", "Offer Impressions", "Offer Clicks" ], "splits": [ "Country" ], "filters": [ { "dimension": "Country", "values": [ "GB", "US", "DE" ] } ] } ``` If no splits or filters are required, their value should be an empty array. However, source, dateRange and metrics must include a value. For example: ```json { "source": "event", "dateRange": { "start": "2019-06-01", "end": "2019-09-25" }, "metrics": [ "Bid Requests" ], "splits": [], "filters": [] } ``` ### Responses Set out below are examples of both successful and unsuccessful responses. Response: Successful> ```json { "id": "QQQ", "url": "https://fyber-async-offerwall-reports.s3.eu-west-1.amazonaws.com/group%AAA/QQQ.csv?AWSAccessKeyId=KKK&Expires=TTTT&Signature=SSS%3D" } ``` * 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	Scenario
401	invalid_token	Invalid authorization token	Authorization header is empty Authorization header not sent or token is not present in the header Unrecognized token Disabled account
400	invalid_format	Invalid file format requested	Format is not supported - currently only csv format is supported
400	invalid_query	For example: Invalid value undefined supplied to : Query/dateRange: DateRange -or- Invalid value "XXXXX" supplied to : Query/dateRange: DateRange/end: Date -or- Invalid dimensions: A,B,C -or- Invalid metrics: A,B,C	If the query sent is not in the expected schema Date range is not sent in the ISO 8601 format. -or- Invalid dimensions You do not have the user permission to query a dimension. -or- Invalid metrics You do not have the user permission to query a metric.
400	invalid_source	Invalid source: XXXXX	Unsupported source type
500	internal_server_error	Unexpected errors in DT's servers	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](#h_01hgb71v3ttvmpj39867je9dvf). 2. Perform polling on the URL to access the file containing the custom report. The empty file is populated within one hour, depending on the size of the query. 3. If the file is not populated with data after one hour, resend the request. 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 Reporting APIs are available on a daily level, with a delay of up to 12 hours from the end of day UTC. ### Query Restrictions * All fields are mandatory. Splits and Filters can have an empty array. See example in [Step 2](#h_01hgb71v3ttvmpj39867je9dvf). * The time range for a report query is limited to 90 days. * Queries are limited to a maximum of 50 per day, per API. * You can query each one of the [defined dimensions](https://docs.digitalturbine.com/dt-offer-wall/advertisers/reporting/supported-metrics-and-dimensions#h_01hgb71v3x59j0sfxvn29dxck2) in the Reporting API calls by up to 5 dimensions in a single query. * To receive a breakdown by date, it must exist in the "splits" array. ### Date Range Restrictions There are a number of rules that must be observed with regard to the date range: * The start date and end date must be in the format of ISO 8601. For example, 2019-10-03. * The interval between the start and end date should not exceed 90 days. * The start date must be earlier or equal to the end date. * The start date must be no later than the previous 18 months. * The end date can not be a date beyond the current date. * The start and end dates are from midnight to midnight. {% hint style="info" %} Data for DT Offer Wall Reports is available from 10 June 2019 onwards. Queries with the current day's date or dates prior to the above time periods result in an HTTP 400 status code (invalid\_query). {% endhint %}