Analytics
REST API reference for analytics
This reference is generated from the Invitebase OpenAPI contract.
Dashboard-ready referral funnel aggregates derived from durable records.
Retrieve referral funnel analytics
GET/v1/analytics/referral-funnel
Returns chart-ready, app-and-mode-scoped metrics calculated from the append-only event store, referral state timestamps, and fulfilled rewards. Use campaign_id to narrow the same response to one campaign. Date ranges are half-open: from is inclusive and to is exclusive. Test and live data cannot mix because mode comes from the authenticated secret key.
Authentication
Authorization: Bearer <secret key>.
Parameters
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
from | query | No | {"type":"string","format":"date-time"} | ISO-8601 inclusive range start. Must be supplied with to; defaults to the preceding 30 days when both are omitted. |
to | query | No | {"type":"string","format":"date-time"} | ISO-8601 exclusive range end. Must be supplied with from; defaults to now when both are omitted. |
campaign_id | query | No | {"type":"string"} | Restrict the result to one campaign. |
top_referrers_limit | query | No | {"type":"integer","minimum":1,"maximum":100,"default":10} | Number of ranked referrers to return (1–100, default 10). |
Responses
200
Funnel totals, daily chart points, and top referrers.
application/json schema:
{
"$ref": "#/components/schemas/ReferralFunnelAnalytics"
}400
The request was malformed or invalid.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}401
Missing or invalid API key.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}403
The API key is valid but is not permitted to call this endpoint.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}429
Too many requests.
Response headers:
{
"Retry-After": {
"description": "Seconds until the caller may retry.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}application/json schema:
{
"$ref": "#/components/schemas/Error"
}Schemas
Schema references below resolve against these definitions. Required fields, enums, bounds, and composed types are preserved from the contract.
The ReferralFunnelAnalytics object
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
account_id | string | Yes | |
campaign_id | string or null | Yes | |
mode | Mode | Yes | Whether the object exists in test or live mode (determined by the API key). |
livemode | boolean | Yes | |
range | object | Yes | |
metrics | object | Yes | |
daily | array | Yes | |
top_referrers | array | Yes |
Full schema:
{
"type": "object",
"required": [
"object",
"account_id",
"campaign_id",
"mode",
"livemode",
"range",
"metrics",
"daily",
"top_referrers"
],
"properties": {
"object": {
"type": "string",
"const": "referral_funnel"
},
"account_id": {
"type": "string"
},
"campaign_id": {
"type": [
"string",
"null"
]
},
"mode": {
"$ref": "#/components/schemas/Mode"
},
"livemode": {
"type": "boolean"
},
"range": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
}
}
},
"metrics": {
"type": "object",
"required": [
"clicks",
"signups",
"referrals",
"referrals_by_state",
"qualified_referrals",
"qualification_rate",
"rewards_paid",
"events_received"
],
"properties": {
"clicks": {
"type": "integer",
"minimum": 0
},
"signups": {
"type": "integer",
"minimum": 0
},
"referrals": {
"type": "integer",
"minimum": 0
},
"referrals_by_state": {
"type": "object",
"additionalProperties": {
"type": "integer",
"minimum": 0
}
},
"qualified_referrals": {
"type": "integer",
"minimum": 0
},
"qualification_rate": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1
},
"rewards_paid": {
"type": "object",
"required": [
"count",
"by_currency"
],
"properties": {
"count": {
"type": "integer",
"minimum": 0
},
"by_currency": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CurrencyAnalyticsAmount"
}
}
}
},
"events_received": {
"type": "integer",
"minimum": 0
}
}
},
"daily": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReferralFunnelDay"
}
},
"top_referrers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ReferralFunnelTopReferrer"
}
}
}
}The Mode object
Whether the object exists in test or live mode (determined by the API key).
Full schema:
{
"type": "string",
"enum": [
"test",
"live"
],
"description": "Whether the object exists in test or live mode (determined by the API key)."
}The CurrencyAnalyticsAmount object
Fulfilled reward spend in minor currency units. Amounts are strings to preserve integer precision. amount_per_qualified_referral is a decimal string or null when the range has no qualified referrals.
| Field | Type | Required | Description |
|---|---|---|---|
currency | Currency | Yes | ISO 4217 currency code (lowercase), e.g. "usd". |
amount | string | Yes | |
amount_per_qualified_referral | string or null | Yes |
Full schema:
{
"type": "object",
"required": [
"currency",
"amount",
"amount_per_qualified_referral"
],
"description": "Fulfilled reward spend in minor currency units. Amounts are strings to preserve integer precision. `amount_per_qualified_referral` is a decimal string or null when the range has no qualified referrals.\n",
"properties": {
"currency": {
"$ref": "#/components/schemas/Currency"
},
"amount": {
"type": "string",
"example": "1200"
},
"amount_per_qualified_referral": {
"type": [
"string",
"null"
],
"example": "600"
}
}
}The Currency object
ISO 4217 currency code (lowercase), e.g. "usd".
Full schema:
{
"type": "string",
"description": "ISO 4217 currency code (lowercase), e.g. \"usd\".",
"example": "usd"
}The ReferralFunnelDay object
| Field | Type | Required | Description |
|---|---|---|---|
date | string | Yes | |
clicks | integer | Yes | |
signups | integer | Yes | |
referrals | integer | Yes | |
qualified_referrals | integer | Yes | |
rewards_paid | integer | Yes | |
events_received | integer | Yes |
Full schema:
{
"type": "object",
"required": [
"date",
"clicks",
"signups",
"referrals",
"qualified_referrals",
"rewards_paid",
"events_received"
],
"properties": {
"date": {
"type": "string",
"format": "date",
"example": "2026-08-01"
},
"clicks": {
"type": "integer",
"minimum": 0
},
"signups": {
"type": "integer",
"minimum": 0
},
"referrals": {
"type": "integer",
"minimum": 0
},
"qualified_referrals": {
"type": "integer",
"minimum": 0
},
"rewards_paid": {
"type": "integer",
"minimum": 0
},
"events_received": {
"type": "integer",
"minimum": 0
}
}
}The ReferralFunnelTopReferrer object
| Field | Type | Required | Description |
|---|---|---|---|
referrer_id | string | Yes | |
external_id | string | Yes | |
name | string or null | No | |
clicks | integer | Yes | |
signups | integer | Yes | |
referrals | integer | Yes | |
qualified_referrals | integer | Yes | |
qualification_rate | number or null | Yes |
Full schema:
{
"type": "object",
"required": [
"referrer_id",
"external_id",
"clicks",
"signups",
"referrals",
"qualified_referrals",
"qualification_rate"
],
"properties": {
"referrer_id": {
"type": "string"
},
"external_id": {
"type": "string"
},
"name": {
"type": [
"string",
"null"
]
},
"clicks": {
"type": "integer",
"minimum": 0
},
"signups": {
"type": "integer",
"minimum": 0
},
"referrals": {
"type": "integer",
"minimum": 0
},
"qualified_referrals": {
"type": "integer",
"minimum": 0
},
"qualification_rate": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1
}
}
}The Error object
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes |
Full schema:
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"doc_url"
],
"properties": {
"type": {
"type": "string",
"enum": [
"invalid_request_error",
"authentication_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}