Reporting API Documentation

This documentation provides details on how to use the Reporting API to generate reports for the OCM Dashboard.

Base URL

https://app.orangeclickmedia.com/api/v1

Authentication

The API uses token-based authentication. To access protected routes, you must include a Bearer token in your request headers.

To obtain a Bearer token, please contact us at [email protected] and ask for API token generation permissions.

Header Example:

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
Content-Type: application/json

Rate Limiting

To ensure stability, the reporting API is rate-limited to:

• 5 requests per minute per user.

If you exceed this limit, the API will return a 429 Too Many Requests status code. The response will also include a Retry-After header indicating the number of seconds to wait before making another request.

Example 429 Response Header:

HTTP/1.1 429 Too Many Requests
Retry-After: 45

---

Generate Report

Generates a report based on the provided dimensions, metrics, and filters.

• Endpoint: POST /reports/generate
• Authentication Required: Yes

Request Body Parameters

Parameter	Type	Required	Description
dimensions	array	Yes	List of dimensions to group data by (e.g., ['day', 'product']).
metrics	array	Yes	List of metrics to include in the report (e.g., ['impressions', 'earnings']).
currency	string	Yes	Currency code. Supported: EUR, USD.
selectedDate	array	No	Date range [startDate, endDate] (e.g., ["2026-01-01", "2026-01-31"]). Defaults to today if omitted. Max range: 3 months.
filters	array	No	List of filter objects to refine the results.

Dimensions

List of available dimensions:

• day: Group by date.
• month: Group by month.
• year: Group by year.
• product: Product type (Standard Display, Instream Video, etc.).
• domain: Website domain.
• subdomain: Website subdomain.
• media_type: Media type (display, video, native).
• device: Device type (desktop, mobile, tablet, etc.).
• os: Operating system (iOS, Android, Windows, etc.).
• ad_unit: Ad unit identifier.
• country: Country code.
• deal_id: Deal identifier.
• deal_name: Deal name.
• deal_type: Deal type (Open auction, Deal, Proposal).

Metrics

List of available metrics:

• impressions: Number of ad impressions.
• earnings: Net earnings.
• ecpm: Effective Cost Per Mille.
• viewable: Viewable impressions.
• first_quartile: Video first quartile completes.
• midpoint: Video midpoint completes.
• third_quartile: Video third quartile completes.
• complete: Video full completes.

Filters

Filters allow you to narrow down your report results. Each filter object must contain:

• value: The dimension or metric key to filter by.
• type: Either dimension or metric.
• comparator: (For dimensions) in, nin (Not In), is_any_of, etc.
• selectedValues: (For dimensions) An array of values.
• comparison: (For metrics) gte (>=), lte (<=), eq (==), neq (!=).
• selectedValue: (For metrics) The value to compare against.

---

Request Examples

Basic Report

{
    "dimensions": ["day"],
    "metrics": ["impressions", "earnings"],
    "currency": "EUR",
    "selectedDate": ["2026-01-01", "2026-01-07"]
}

Report with Dimension Filter (Domain)

{
    "dimensions": ["product"],
    "metrics": ["impressions"],
    "currency": "USD",
    "selectedDate": ["2026-01-01", "2026-01-01"],
    "filters": [
        {
            "value": "domain",
            "type": "dimension",
            "comparator": "in",
            "selectedValues": ["example.com", "another-domain.net"]
        }
    ]
}

Report with Metric Filter (Impressions)

{
    "dimensions": ["day"],
    "metrics": ["impressions", "ecpm"],
    "currency": "EUR",
    "selectedDate": ["2026-01-01", "2026-01-07"],
    "filters": [
        {
            "value": "impressions",
            "type": "metric",
            "comparison": "gte",
            "selectedValue": 1000
        }
    ]
}

Response Format

Success Response (200 OK)

{
    "status": "success",
    "data": [
        {
            "day": "2026-01-01",
            "impressions": 50000,
            "earnings": 150.25
        }
    ],
    "meta": {
        "count": 1,
        "start_date": "2026-01-01",
        "end_date": "2026-01-01",
        "currency": "EUR"
    }
}

Error Response (422 Unprocessable Entity)

{
    "status": "error",
    "message": "Validation failed",
    "errors": {
        "dimensions.0": ["One or more selected dimensions are invalid."]
    }
}