> For the complete documentation index, see [llms.txt](https://help.theaffiliateplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.theaffiliateplatform.com/apis-and-configurations/reporting-api.md).

# Reporting API

{% hint style="info" %}
This document describes how to get affiliation metrics via API (commission, balance, registrations, etc.).

It can be used by the Operator - to get metrics for all affiliates.

Or it can be used by the Affiliate - to get only their own metrics.
{% endhint %}

{% hint style="danger" %}
The default API URL is **<https://boapi.smartico.ai/>** but depending on your setup it could be different. Check for the exact URL in the '***Settings***' section.\
\
***If you are an affiliate***, check for the exact URL in '**Account Settings**' section in your profile.
{% endhint %}

TheAffiliatePlatform (TAP) provides API to retrieve configurational, operational, and analytical data. API is provided as a REST over HTTP and uses SSL for data protection.

Reporting API is designed for the high level aggregated reporting (aggregated overview per operation/affiliate and not per individual user).

Affiliates can use API to get reports related to the activities of their own traffic and for the Operator to have access to all affiliates' data.

To get an API key, see [API Keys and URL](https://help.theaffiliateplatform.com/apis-and-configurations/api-keys-and-url.md). Send the key in the `authorization` header of each request.

## **API for the Affiliate**

### Accessing analytical data

The Affiliation system has an API endpoint that provides statistical information about visits, registrations, commissions, etc., aggregated by a specified period or for a lifetime.

Example of the API call using CURL:

{% code overflow="wrap" %}

```bash
curl --location --request GET 'https://boapi.smartico.ai/api/af2_media_report_af?aggregation_period=DAY&group_by=utm_campaign,utm_medium,utm_source,afp&date_from=2022-07-12&date_to=2022-07-14' --header 'authorization: your_api_key'
```

{% endcode %}

Example of API call using NodeJs:

```javascript
var request = require('request');
var options = {
 'method': 'GET',
 'url': 'https://boapi.smartico.ai/api/af2_media_report_af?aggregation_period=DAY',
 'headers': {
   'authorization': 'your_api_key'
 }
};
request(options, function (error, response) {
 if (error) throw new Error(error);
 console.log(response.body);
});

```

Parameters in API call:

* As **aggregation\_period** you can pass DAY, MONTH or YEAR (in capital letters), or keep it empty in order to get aggregate data for the lifetime. In lifetime data, the `dt` field is `all`.
* Optional parameter group\_by could have a comma-separated list of the fields to group results. Possible values are:
  * utm\_campaign
  * utm\_medium
  * utm\_source
  * afp, afp1, afp2.... afp9
  * link\_id
  * brand\_id
  * campaign\_id
  * source\_id
  * registration\_id (requires the "Access Registrations report" permission)
  * ext\_customer\_id (requires the "Access Registrations report" permission)
  * username (requires the "Access Registrations report" permission)
* If group\_by is empty, or has no value from this list, the results are grouped by link\_id and brand\_id. Values that are not in the list are ignored. registration\_id, ext\_customer\_id and username are also ignored when the affiliate does not have the "Access Registrations report" permission.
* Only one afp field (afp, afp1 … afp9) can be used in one request. With two or more, the API returns an error.
* When you group by brand\_id, link\_id or campaign\_id, each row also has brand\_name, link\_name or campaign\_name.
* Optional parameters **date\_from** and **date\_to** could be used to limit results for the defined period. The format of the date is YYYY-MM-DD.
* Optional parameter **brand\_id** limits the results to one brand.

{% hint style="danger" %}
Important note regarding setting date\_from and date\_to parameters.

* date\_from is inclusive
* date\_to is exclusive

This means that for the request with date\_from = 2022-07-12 and date\_to=2022-07-14, API will return data for 12 and 13 July only.<br>

* `date_from` and `date_to` must always be used **together** - either provide both parameters or omit both. Providing only one of them is not supported.
* `date_from` and `date_to` cannot be the same date. To get data for one day, set `date_to` to the next day (for example, date\_from=2022-07-12 and date\_to=2022-07-13).
* `date_to` cannot be earlier than `date_from`.
  {% endhint %}

Example of response:

```json
 
{
   "meta": {
       "affiliate_id": 34598,
       "operator_currency": "EUR",
       "operator_public_name": "Super Affiliate",
       "operator_bo_domain": "https://admin.aff.smartico.ai/",
       "operator_image_url": "https://static.smartico.ai/73a6af827f2162f79c7996-cropped-FBLogo.png"
   },
   "data": [{
       "dt": "2020-08-01T00:00:00.000Z",
       "link_id": "29",
       "link_name": "test redirect",
       "brand_id": "5",
       "brand_name": "XP",
       "visit_count": 4,
       "registration_count": 24,
       "qftd_count": 0,
       "qlead_count": 0,
       "deposit_count": 2,
       "deposit_total": 40,
       "net_deposits": 20,
       "net_pl": 70,
       "netwin": 100,
       "pl": 100,
       "net_pl_sport": 30,
       "net_pl_casino": 40,
       "ftd_count": 2,
       "ftd_total": 40,
       "bonus_amount": 30,
       "withdrawal_count": 1,
       "withdrawal_total": 20,
       "chargback_total": 0,
       "operations": 5,
       "volume": 10,
       "commissions_cpl": 0,
       "commissions_cpa": 0,
       "commissions_rev_share": 5,
       "deductions": 0,
       "sub_commission_from_child": 0,
       "payments": 0,
       "conversion_rate": 0.08333332986111125,
       "net_deposit_total": 20,
       "commissions_total": 5,
       "adjustments": 0,
       "balance": 5
   }, {
       "dt": "2020-07-01T00:00:00.000Z",
       "link_id": "4",
       "link_name": "Test/XPK-Registration",
       "brand_id": "5",
       "brand_name": "XP",
       "visit_count": 7,
       "registration_count": 0,
       "qftd_count": 0,
       "qlead_count": 0,
       "deposit_count": 0,
       "deposit_total": 0,
       "net_deposits": 0,
       "net_pl": 40,
       "netwin": 80,
       "pl": 80,
       "net_pl_sport": 25,
       "net_pl_casino": 15,
       "ftd_count": 0,
       "ftd_total": 0,
       "bonus_amount": 40,
       "withdrawal_count": 0,
       "withdrawal_total": 0,
       "chargback_total": 0,
       "operations": 2,
       "volume": 20,
       "commissions_cpl": 0,
       "commissions_cpa": 0,
       "commissions_rev_share": 0,
       "deductions": 0,
       "sub_commission_from_child": 0,
       "payments": 0,
       "conversion_rate": 0,
       "net_deposit_total": 0,
       "commissions_total": 0,
       "adjustments": 0,
       "balance": 0
   }]
}

```

Use the field names exactly as they come in the response. For example, `chargback_total` is spelled this way.

The affiliate sees the same data in Analytics, Media Report

![Media report in the affiliate portal (Analytics, Media Report)](https://2789002490-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fkbip9hFgRFwIv4mXJPnz%2Fuploads%2FsidbXNgp9BhDZ7REcgv4%2Fmedia-report-0fbde654-d29a0d.jpg?alt=media)

## API for the Operator

### Accessing analytical data

Operator API is similar to the Affiliate API.<br>

Example of the API call using CURL:

{% code overflow="wrap" %}

```bash
curl --location --request GET 'https://boapi.smartico.ai/api/af2_media_report_op?aggregation_period=DAY&group_by=utm_campaign,utm_medium,utm_source,afp&date_from=2022-07-12&date_to=2022-07-14' --header 'authorization: your_api_key'
```

{% endcode %}

The difference between APIs:

<table><thead><tr><th width="188">.</th><th>Affiliate API</th><th>Operator API</th></tr></thead><tbody><tr><td>Method name</td><td>af2_media_report_af</td><td>af2_media_report_op</td></tr><tr><td>Possible values for group_by parameter</td><td>afp(1..9), utm_campaign, utm_medium, utm_source, link_id, brand_id, source_id, campaign_id, registration_id, ext_customer_id, username</td><td>affiliate_id, registration_id, ext_customer_id, username, afp(1..9), utm_campaign, utm_medium, utm_source, link_id, brand_id, campaign_id, source_id, deal_root_original_id, child_affiliate_id, manager_id</td></tr><tr><td>Possible values for filtering data</td><td>date_from, date_to, brand_id (one brand)</td><td>date_from, date_to, affiliate_id, brand_id, manager_id</td></tr></tbody></table>

In the Operator API response, `meta` has `operator_id` instead of `affiliate_id`. When you group by affiliate\_id, child\_affiliate\_id or deal\_root\_original\_id, each row also has affiliate\_name, child\_affiliate\_name or deal\_group\_name.

## **Important to know**

* All amounts are in operator currency
* As TAP is providing an affiliation system as a white-label solution, you can find the name, domain, and image of the “Operator” operating affiliation system in response to API calls.
* In grouping by "day", the report will show the change of commission during this day. It's not a total commission at the end of the day.
* If you are querying aggregated data and there are no activities for a specific period, the record for a specific period will be missing in response.
* If you query for aggregated data, the response will show only changes for a specified period. For example, with aggregation\_period=MONTH:
  * During July, the affiliate had a change of balance “-795.50 EUR”, and because it was his first month, at the end of the month, his balance will be -795.50 EUR
  * During August, he had a positive change, +225 EUR. This means that his balance was “-570.50 EUR at the end of August.”
* In the Operator API, "affiliate\_id", "brand\_id" and "manager\_id" values can be passed as 123 or as 123,456. You can pass up to 500 affiliate IDs.
* The number of API calls per minute can be limited for your account. Above the limit, the API answers "Too many requests to API from the same account, please decrease the query rate or try again later". Wait a minute and try again.
* **Note that not all attributes are available for every affiliate in the Affiliate API. Visibility depends on the Additional Permissions granted to each Affiliate.** The operator sets these permissions in the affiliate's profile: Affiliates → Active Affiliates → the affiliate → Overview → Additional permissions → Edit.

![Additional permissions and the API block in the affiliate's profile](https://2789002490-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fkbip9hFgRFwIv4mXJPnz%2Fuploads%2Fvdg59jlwv1bFe07OUVJ0%2Faffiliate-additional-permissions-b8b77ddc-42c84c.jpg?alt=media)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.theaffiliateplatform.com/apis-and-configurations/reporting-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
