API ReferencePartner API

Partner API

Platform partners (white-label exchange operators) use these endpoints to manage their supply source (Publisher) and demand source (DSP) ecosystem and retrieve consolidated revenue reports.

Base URL: https://api.praevis.com Auth: X-API-Key: {YOUR_KEY} + X-User-Partner-ID: {PARTNER_UUID}

All partner API endpoints require the X-User-Partner-ID header. Without it, requests are rejected with HTTP 403.

Partner stats

Aggregate revenue

GET /api/partner/stats

Returns consolidated revenue, fill rate, and impression metrics across all supply sources and demand sources under this partner.

Response:

{
  "partner_id": "partner-uuid",
  "partner_name": "Example Exchange",
  "period": "24h",
  "impressions": 892400,
  "fill_rate": 0.834,
  "revenue_cents": 142870,
  "publisher_count": 14,
  "dsp_count": 6,
  "top_publishers": [
    { "id": "pub-uuid", "name": "Top Publisher", "revenue_cents": 38400 }
  ],
  "top_dsps": [
    { "id": "dsp-uuid", "name": "Top DSP", "spend_cents": 52100 }
  ]
}

Supply source management

List partner supply sources

GET /api/partner/publishers

Returns all supply sources registered under this partner account.

Query params: same as GET /api/supply/sources (status, pagination).

Response: Same structure as the supply source list.

Create supply source under partner

POST /api/supply/sources
X-User-Partner-ID: {PARTNER_UUID}

Same body as the standard create supply source endpoint. The new supply source is automatically scoped to the partner.

Demand source management

List partner demand sources

GET /api/partner/dsps

Returns all demand sources registered under this partner account.

Response:

{
  "dsps": [
    {
      "id": "dsp-uuid",
      "name": "Partner DSP",
      "mode": "rtb",
      "status": "active",
      "win_rate_24h": 0.183,
      "spend_cents_24h": 28400
    }
  ]
}

Reporting API

External reporting endpoints for partners. Uses a separate partner API key (not the dashboard key).

Auth: X-API-Key: {PARTNER_API_KEY} (issued per partner, contact support)

Get report

GET /api/partner/report?period={period}

Returns daily breakdown of auction performance for all supply sources under this partner.

Query params:

ParamValuesDescription
period24h, 7d, 14d, 30dReporting period
publisher_idUUIDFilter to a specific supply source

Response:

{
  "partner": "Example Partner",
  "partner_id": "partner-uuid",
  "period": "7d",
  "daily": [
    {
      "date": "2026-05-05",
      "requests": 3062923,
      "wins": 2348,
      "impressions": 658,
      "confirmed_impressions": 658,
      "fill_rate": 0.08,
      "revenue_cents": 281.97,
      "spend_cents": 281.97,
      "avg_cpm": 4.29,
      "avg_latency_ms": 131
    }
  ],
  "totals": {
    "requests": 62628162,
    "wins": 119587,
    "revenue_cents": 14259.94
  }
}

List publishers

GET /api/partner/publishers

Returns all supply sources under this partner with their IDs. Use the id as publisher_id filter in the report endpoint.

Response:

{
  "publishers": [
    {
      "id": "84a75615-...",
      "name": "Example Publisher",
      "status": "active"
    }
  ]
}

VAT rates

Get VAT rates by country

GET /api/vat-rates

Returns current VAT rates used for invoice calculations.

Response:

{
  "rates": [
    { "country": "DE", "rate": 0.19, "name": "Germany" },
    { "country": "GB", "rate": 0.20, "name": "United Kingdom" },
    { "country": "AE", "rate": 0.05, "name": "United Arab Emirates" },
    { "country": "SG", "rate": 0.09, "name": "Singapore" }
  ],
  "updated_at": "2026-02-01T00:00:00Z"
}

Invoicing

Get invoice list

GET /api/partner/invoices

Response:

{
  "invoices": [
    {
      "id": "inv-2026-01",
      "period": "2026-01",
      "status": "paid",
      "revenue_share_cents": 142870,
      "vat_cents": 28574,
      "total_cents": 171444,
      "due_date": "2026-02-28",
      "pdf_url": "https://api.praevis.com/invoices/inv-2026-01.pdf"
    }
  ]
}

Get invoice

GET /api/partner/invoices/{invoice_id}

Returns a single invoice with line-item breakdown.

Revenue share model

Revenue share percentage is set at the contract level. The Metrics API shows your gross revenue (total clearing price going to supply sources). Your net payout is:

net_payout = gross_revenue × (1 - praevis_margin)

Contact [email protected] for your specific revenue share terms.

Metrics APISandbox API