Partner Reporting API Guide

1. Overview

The DigiBid Partner Reporting API provides daily delivery totals for customers integrating with DigiBid as an SSP or DSP. The authenticated credential determines the partner type and customer account; callers cannot query another customer's data by supplying an ID.

2. Endpoint

3. Quick Start

Load the credential supplied by DigiBid into DIGIBID_API_KEY using your environment's secret-safe mechanism. The same request format is used for SSP and DSP credentials.

curlprintf 'header = "X-API-Key: %s"\n' "$DIGIBID_API_KEY" | \
curl --config - --fail-with-body \
  --request GET \
  --header 'Accept: application/json' \
  'https://api.digibid.com/partner/v1/report?from=2026-08-01&to=2026-08-04'

The API key is supplied to curl through standard input instead of being expanded into the process argument list.

4. Authentication

Pass the API key in the X-API-Key HTTP request header. DigiBid validates the key, checks that it is active and unexpired, and resolves it to one customer identity. A server-managed reconcile_ratio may also be attached to the token; clients cannot set or override it.

Do not send customer_id, publisher_id, dsp_id, or partner_type. These values are derived from the credential and cannot be overridden by request parameters.

5. Query Parameters

• The date range may not exceed 31 days.
• Use ISO calendar dates only; timestamps and timezone offsets are not accepted.
• Rows are grouped by UTC date and currency.

6. SSP & DSP Metrics

The response schema is identical for both partner types. The credential changes the account scope and business meaning of the metrics.

7. Response Fields

200 OK · SSP example{
  "data": [
    {
      "date": "2026-08-01",
      "currency": "USD",
      "impressions": 54504,
      "spend": 114.992499
    }
  ],
  "meta": {
    "from": "2026-08-01",
    "to": "2026-08-04",
    "timezone": "UTC",
    "partner_type": "ssp"
  }
}

If one date contains multiple currencies, the API returns one row per currency and never combines different currencies into one total.

8. Examples

Request with URL-encoded parameters

curlprintf 'header = "X-API-Key: %s"\n' "$DIGIBID_API_KEY" | \
curl --config - --fail-with-body --get \
  'https://api.digibid.com/partner/v1/report' \
  --header 'Accept: application/json' \
  --data-urlencode 'from=2026-08-01' \
  --data-urlencode 'to=2026-08-04'

Empty result

200 OK{
  "data": [],
  "meta": {
    "from": "2026-07-01",
    "to": "2026-07-01",
    "timezone": "UTC",
    "partner_type": "dsp"
  }
}

9. Error Handling

Error responses use a consistent JSON envelope:

Error response{
  "error": {
    "code": "invalid_date_range",
    "message": "..."
  }
}

Clients should primarily branch on the HTTP status. Additional machine-readable error codes may be introduced while preserving the response envelope.

10. Rate Limits

The service applies request-rate and concurrency controls to protect reporting availability. Limits are associated with the authenticated partner credential; contact your DigiBid account manager for the limits assigned to your integration.

• Treat 429 Too Many Requests as a transient response.
• Honor the Retry-After response header before sending another request.
• Use exponential backoff with random jitter and cap the maximum retry interval.
• Do not run parallel requests for overlapping date ranges unless explicitly required.

11. Integration Best Practices

1. Pull incrementally: retrieve one UTC day at a time for predictable retries and reconciliation.
2. Refresh recent data: reload the current and previous UTC day because delayed events may update totals.
3. Handle floating point: parse spend as a double/float64, reconcile each currency independently, and round both values to six decimal places before comparing them.
4. Make ingestion idempotent: replace or upsert rows using date, currency, account, and partner type as the logical key.
5. Protect credentials: keep keys in a server-side secret manager, restrict access, rotate them, and redact them from logs.
6. Track requests: retain X-Request-Id with job metadata for troubleshooting.

12. FAQ

Can I query a different customer ID?

No. Customer scope and partner type are derived exclusively from the API key.

Why did a successful request return no rows?

No matching finalized events were found for the credential and date range. This is represented by 200 OK with an empty data array.

What numeric type should I use for spend?

spend is a JSON number. Decode it as a double or Go float64; trailing zeros are not part of the API contract. Round both sides to six decimal places for reconciliation.

Can totals change after I retrieve them?

Yes. Delayed events can update recent UTC dates. Refresh at least the current and previous day.

What should I send to support?

Send the X-Request-Id, UTC request time, requested date range, HTTP status, and error code. Never send your API key.