BirdseyePost Customer Reporting API

Version: v1

API locations

Paths below are relative to your BirdseyePost app’s origin:

Quick start

1. Sign in to the correct account and open Settings → Reporting API. An account administrator creates the key.
2. Name your key, choose its expiry, and enable campaign spend if needed. Save the key when it appears; it is shown once.
3. Set BIRDSEYEPOST_URL to your BirdseyePost app’s HTTPS origin and store BIRDSEYEPOST_API_KEY as a server-side secret.

curl "$BIRDSEYEPOST_URL/api/v1/reporting/campaigns?limit=25&include=spend" \
  -H "Authorization: Bearer $BIRDSEYEPOST_API_KEY"

All reporting requests use GET and JSON responses. The API reads the dashboard campaigns in the account bound to your key. Agent-ordering drafts use the separate ordering API. Sandbox keys cannot read account reporting.

Endpoints

Base path: /api/v1/reporting

Use a dashboard campaign ID returned by the campaign list in place of {id}.

Add include=spend to the campaign list or detail endpoint to retrieve campaigns and spend together. This requires both permissions. Without it, the response omits prices and payment data. The spend endpoint accepts no query parameters.

Campaign metrics

Metrics are lifetime totals:

Recipient details, artwork files and internal billing notes are excluded.

Filters and pagination

The campaign list supports these query parameters:

Results are ordered by ascending campaign ID. Keep filters unchanged between pages and stop when pagination.hasMore is false. Deleted campaigns are excluded. Pagination is a live view, so changes during an export can affect results.

Creation filters select campaigns. Spend remains the campaign’s lifetime recorded spend, not spend during the selected dates.

Detail requests only accept include=spend. Unknown or repeated parameters return 400.

Python pagination example

This example requires the requests package. Add retry handling for 429 and transient 503 responses in production integrations.

import os
import requests

url = os.environ["BIRDSEYEPOST_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["BIRDSEYEPOST_API_KEY"]}
params = {"limit": 100, "include": "spend"}

while True:
    response = requests.get(url + "/api/v1/reporting/campaigns",
                            headers=headers, params=params, timeout=30)
    response.raise_for_status()
    page = response.json()
    for campaign in page["data"]:
        print(campaign["id"], campaign["spend"])
    if not page["pagination"]["hasMore"]:
        break
    params["after"] = page["pagination"]["nextCursor"]

Understanding spend

All amounts use integer cents: 175000 means $1,750.00 in the returned currency. Keep USD and CAD separate; the API performs no currency conversion.

Spend comes from the same recorded campaign charges used by account billing. It is not a live Stripe reconciliation or an external invoice ledger. Payments and refunds appear after they have been recorded in BirdseyePost. No separate taxes, fees or unrecorded historical invoices are inferred.

Response example

Illustrative campaign list response with include=spend:

{
  "data": [
    {
      "id": "campaign_example",
      "name": "Autumn win-back",
      "type": "Retention",
      "format": "Postcard",
      "mailPieceType": "Postcard 6x9",
      "status": "Completed",
      "frequency": "One-time",
      "launchDate": "2026-10-01T00:00:00+00:00",
      "createdAt": "2026-09-20T12:00:00+00:00",
      "updatedAt": "2026-10-15T12:00:00+00:00",
      "metrics": {
        "mailpieces": 2500,
        "mailedMailpieces": 2500,
        "scans": 124
      },
      "spend": {
        "source": "recorded_campaign_charges",
        "availability": "recorded",
        "quote": {
          "amountCents": 175000,
          "currency": "USD"
        },
        "chargeCount": 1,
        "totalsByCurrency": [
          {
            "currency": "USD",
            "grossPaidCents": 175000,
            "refundedCents": 0,
            "netPaidCents": 175000,
            "pendingCents": 0,
            "failedCents": 0,
            "voidedCents": 0,
            "refundStatus": "none_recorded",
            "lastPaidAt": "2026-10-01T12:00:00+00:00"
          }
        ]
      }
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

Errors and limits

Each account can make 60 reporting requests per UTC minute, shared across keys. A 429 response includes Retry-After: 60. Use exponential backoff for transient 503 errors.

Every reporting response includes X-Request-Id; include it when contacting support.

Example error response:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This connection needs spend:read."
  },
  "requestId": "example-request-id"
}

Security

Keys are tied to one account, expire automatically and can be revoked in Settings. BirdseyePost stores a hash of each key.

API requests must use the Authorization header over HTTPS; browser cookies do not grant reporting access. Keep keys in a server-side secret manager. Cross-origin browser access is not enabled.

To rotate a key:

1. Create a replacement.
2. Update your integration.
3. Verify a request.
4. Revoke the old key.

To integrate another account, use a separate key created by that account’s administrator.