Revfold

API Reference

Pull normalized revenue, reconciliation, and payment data into BI tools, financial systems, and internal dashboards.

v1 — Stable

Base URL

https://revfold.vercel.app/api/v1

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer rv_live_<your_api_key>

Create and manage keys at /dashboard/settings/api-keys. Keys can be scoped to a single entity or all entities in your organization.

Rate Limiting

Each API key is limited to 1,000 requests per hour. Exceeded requests receive 429 Too Many Requests with a Retry-After header (seconds until reset).

Response Format

All successful responses use this envelope:

{
  "data": [ ... ],
  "meta": { "total": 342, "limit": 100, "offset": 0 }
}

Errors:

{
  "error": "Human-readable description",
  "code":  "ERROR_CODE"
}

Endpoints

GET/api/v1/revenue

List normalized revenue records from all connected SSPs. Paginated.

Query Parameters

Name	Type	Required	Description
entity_id	string (UUID)	required	Entity to query. Ignored if your API key is entity-scoped.
period	YYYY-MM	optional	Filter to a single month. Mutually exclusive with period_start/end.
period_start	YYYY-MM	optional	Start of date range (inclusive).
period_end	YYYY-MM	optional	End of date range (inclusive).
source	string	optional	SSP name (e.g. vistar_ca, hivestack, broadsign).
limit	integer	optional	Records to return. Default 100, max 1000.
offset	integer	optional	Pagination offset. Default 0.

Example Request

curl -H "Authorization: Bearer rv_live_..." \
  "https://revfold.vercel.app/api/v1/revenue?entity_id=ENTITY_UUID&period=2026-01&limit=100"

Example Response

{
  "data": [
    {
      "id": "abc123",
      "screen_id": "SCR-001",
      "screen_name": "YYZ T1 - Level 3 Display",
      "advertiser": "Acme Corp",
      "earned_month": "2026-01-01",
      "net_revenue_norm": 1250.00,
      "currency": "CAD",
      "source_ssp": "vistar_ca",
      "impressions": 48200
    }
  ],
  "meta": { "total": 342, "limit": 100, "offset": 0, "period": "2026-01" }
}

GET/api/v1/revenue/summary

Aggregate revenue totals grouped by period and SSP source.

Query Parameters

Name	Type	Required	Description
entity_id	string (UUID)	required	Entity to query.
period_start	YYYY-MM	optional	Start of date range.
period_end	YYYY-MM	optional	End of date range.

Example Request

curl -H "Authorization: Bearer rv_live_..." \
  "https://revfold.vercel.app/api/v1/revenue/summary?entity_id=ENTITY_UUID&period_start=2026-01&period_end=2026-03"

Example Response

{
  "data": [
    { "period": "2026-01-01", "source_ssp": "vistar_ca", "currency": "CAD", "total_revenue": 18420.50, "record_count": 147 },
    { "period": "2026-01-01", "source_ssp": "hivestack",  "currency": "CAD", "total_revenue": 6830.00,  "record_count": 52  }
  ],
  "meta": { "total": 6, "limit": 6, "offset": 0 }
}

GET/api/v1/reconciliation

Reconciliation snapshots — booked vs delivered vs invoiced vs received, with variance flags.

Query Parameters

Name	Type	Required	Description
entity_id	string (UUID)	required	Entity to query.
period	YYYY-MM	optional	Filter to a single month.
currency	CAD \| USD	optional	Currency to filter by. Default CAD.

Example Request

curl -H "Authorization: Bearer rv_live_..." \
  "https://revfold.vercel.app/api/v1/reconciliation?entity_id=ENTITY_UUID&period=2026-01"

Example Response

{
  "data": [
    {
      "period_month": "2026-01-01",
      "advertiser": "Acme Corp",
      "booked_revenue": 12000,
      "delivered_revenue": 11800,
      "invoiced_amount": 11800,
      "received_amount": 11800,
      "currency": "CAD",
      "variance_delivery": -200,
      "variance_billing": 0,
      "variance_payment": 0,
      "flags": ["UNDER_DELIVERED"]
    }
  ],
  "meta": { "total": 8, "limit": 1000, "offset": 0 }
}

GET/api/v1/payments

SSP payment records received by the entity.

Query Parameters

Name	Type	Required	Description
entity_id	string (UUID)	required	Entity to query.
period_start	YYYY-MM-DD	optional	Payment date range start.
period_end	YYYY-MM-DD	optional	Payment date range end.
status	paid \| outstanding	optional	"paid" = received/reconciled. "outstanding" = expected.
limit	integer	optional	Max 1000, default 100.
offset	integer	optional	Pagination offset.

Example Request

curl -H "Authorization: Bearer rv_live_..." \
  "https://revfold.vercel.app/api/v1/payments?entity_id=ENTITY_UUID&status=paid"

Example Response

{
  "data": [
    {
      "id": "def456",
      "payment_ref": "HS-2026-0147",
      "payment_date": "2026-02-15",
      "currency": "CAD",
      "gross_amount": 19250.50,
      "fee_credits": 0,
      "net_amount": 19250.50,
      "periods_covered": ["2026-01"],
      "status": "received",
      "connector_configs": { "source": "hivestack" }
    }
  ],
  "meta": { "total": 14, "limit": 100, "offset": 0 }
}

GET/api/v1/commissions

Venue commission records (e.g. airport revenue-share agreements).

Query Parameters

Name	Type	Required	Description
entity_id	string (UUID)	required	Entity to query.
period	YYYY-MM	optional	Filter to a single month.
limit	integer	optional	Max 1000, default 500.
offset	integer	optional	Pagination offset.

Example Request

curl -H "Authorization: Bearer rv_live_..." \
  "https://revfold.vercel.app/api/v1/commissions?entity_id=ENTITY_UUID&period=2026-01"

Example Response

{
  "data": [
    {
      "id": "ghi789",
      "period_month": "2026-01-01",
      "gross_revenue": 5400.00,
      "commission_rate": 0.13,
      "commission_amount": 702.00,
      "total_due": 702.00,
      "amount_paid": 702.00,
      "status": "paid",
      "venue_partners": { "name": "Plaza Premium Group" },
      "venue_locations": { "name": "YYZ Terminal 1", "airport_code": "YYZ" }
    }
  ],
  "meta": { "total": 4, "limit": 500, "offset": 0 }
}

GET/api/v1/connectors

List SSP and CRM connector status for your organization. Credentials are never returned.

Example Request

curl -H "Authorization: Bearer rv_live_..." \
  "https://revfold.vercel.app/api/v1/connectors"

Example Response

{
  "data": [
    {
      "id": "jkl012",
      "source": "hivestack",
      "status": "active",
      "last_sync_at": "2026-03-12T08:00:00Z",
      "last_sync_status": "success",
      "entity_id": "ENTITY_UUID",
      "entity_name": "Movia CA"
    }
  ],
  "meta": { "total": 3, "limit": 1000, "offset": 0 }
}

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing, invalid, or malformed Authorization header.
INVALID_KEY	401	The API key does not match any active key.
KEY_REVOKED	401	The API key has been revoked.
RATE_LIMITED	429	Exceeded 1,000 requests/hour. Check the Retry-After header.
MISSING_PARAM	400	A required query parameter was not provided.
NOT_FOUND	404	The requested entity was not found or is inaccessible with this key.
DB_ERROR	500	Internal database error.

Revfold API v1 — 2026. Manage keys at /dashboard/settings/api-keys.