Direct API Installation

Direct API is the source-of-truth path for backend events that are confirmed by durable product, billing, setup, or integration state. Use it when the event should be emitted from server code after a database write, provider confirmation, billing update, OAuth completion, background job, or metered usage calculation.

This is different from the Web SDK. The Web SDK is browser-safe supplemental instrumentation for visible user intent and UI friction. Direct API uses a secret ingest key and must never run in browser, mobile, desktop, or public client code.

Create an ingest keyCopy Anchor Link

In SaaSFunnels, open Settings > Integrations > Direct API and create a key. The secret is shown once.

Store it only in backend or server environment variables as SAASFUNNELS_INGEST_API_KEY. For an interactive shell, use the shell-safe prompt.

Never expose this key in client code, frontend bundles, mobile apps, desktop apps, public repositories, logs, analytics tools, or AI prompts.

Use developer toolsCopy Anchor Link

Use SaaSFunnels CLI and SaaSFunnels MCP Server to speed up Direct API setup without exposing real keys.

Validate a payload before shipping it:

saasfunnels events validate ./saasfunnels-event.json --source direct --json

Send one smoke event from a server-safe environment:

saasfunnels events send-test --file ./saasfunnels-event.json --json

Install a coding-agent handoff file if it would help. Choose the target for your tool; this example writes a portable Markdown handoff:

saasfunnels agent install --target markdown

Start MCP when an agent needs SaaSFunnels context:

saasfunnels mcp serve

Set a developer:read key as SAASFUNNELS_API_KEY for live MCP reads. MCP is read-only by default. Enable send_test_event only for explicit setup smoke testing.

Send a server eventCopy Anchor Link

Send events to:

https://app.saasfunnels.ai/api/events/ingest

Use the ingest key as a bearer token:

Replace the example timestamp with the event's actual UTC time and choose a unique, stable event_id for a new event. Reuse that ID only when retrying the same event.

curl -X POST https://app.saasfunnels.ai/api/events/ingest \
  -H "Authorization: Bearer ${SAASFUNNELS_INGEST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "evt_direct_001",
    "event_name": "usage_limit_hit",
    "account_id": "acct_123",
    "user_id": "user_456",
    "timestamp": "2026-06-20T15:00:00.000Z",
    "semantic_type": "limit_friction",
    "event_kind": "friction_event",
    "sentiment": "negative",
    "sentiment_score": -0.8,
    "sentiment_confidence": 0.9,
    "sentiment_source": "explicit",
    "value": 1,
    "properties": {
      "plan": "starter",
      "limit_name": "monthly_events",
      "usage_ratio": 0.93
    }
  }'

Feature-gate access and adoptionCopy Anchor Link

The Feature-gate upgrade Funnel waits for a server-confirmed entitlement_active event before it shows the unlocked step. Send that event only after your server verifies that the same account can use the selected Feature. Include funnel_journey_id and funnel_version_id in properties, using the identifiers from the verified Funnel action or decision context. A billing receipt alone does not prove Feature access, and a browser event cannot confirm it.

For a signed customer action connector, its execution request includes binding.journeyId and binding.publishedVersionId. After the host has applied the plan change and checked the Feature for that account, send a Direct API event like this from its backend. Reuse the same event_id when retrying delivery.

{
  "event_id": "entitlement_active:action_request_123",
  "event_name": "entitlement_active",
  "account_id": "acct_123",
  "timestamp": "2026-09-22T15:00:00.000Z",
  "semantic_type": "activation",
  "event_kind": "product_action",
  "properties": {
    "feature_key": "premium_exports",
    "funnel_journey_id": "44444444-4444-4444-8444-444444444444",
    "funnel_version_id": "66666666-6666-4666-8666-666666666666"
  }
}

Use the same SaaSFunnels account ID as the verified runtime session. The event timestamp must fall after the journey begins; a correct Price or provider result without this correlated access evidence leaves the customer in the checking state.

The server SDK can create the same event with a stable retry identity:

await funnels.sendFeatureEntitlementActive({
  accountId: "acct_123",
  featureKey: "premium_exports",
  funnelJourneyId: actionBinding.journeyId,
  funnelVersionId: actionBinding.publishedVersionId,
  occurredAt: new Date().toISOString(),
  verifiedAction,
});

Call this only after the host's entitlement check succeeds. The helper derives the idempotent event ID and sends the required correlation properties.

Send feature_adopted separately when the account actually uses the Feature. It measures later adoption; it does not unlock the Funnel or block publication. Confirm both event names in Events after their first server-side test delivery. A setup smoke event proves intake and mapping, while a controlled upgrade test must still prove that the access event is linked to the same account, journey, and published version.

Minimum viable SaaS account factsCopy Anchor Link

SaaSFunnels should learn a small account profile while events arrive. Send these as bounded properties on normal account-scoped events, especially signup, login, activation, plan change, team, and usage rollup events.

Example login event with account facts:

{
  "event_id": "login:acct_123:user_456:2026-06-20T15:00:00.000Z",
  "event_name": "user_logged_in",
  "account_id": "acct_123",
  "user_id": "user_456",
  "timestamp": "2026-06-20T15:00:00.000Z",
  "semantic_type": "login",
  "event_kind": "login",
  "properties": {
    "account_created_at": "2026-06-01T12:00:00.000Z",
    "plan": "starter",
    "is_in_trial": true,
    "trial_ends_at": "2026-06-28T12:00:00.000Z",
    "user_count": 7,
    "seat_count": 10,
    "active_user_count": 6
  }
}

Refresh these facts on lifecycle changes or daily account rollups. Do not create noisy page-view events just to refresh profile data.

Usage-based and API-heavy productsCopy Anchor Link

For API-heavy products, do not forward every customer API request to SaaSFunnels. Send aggregate usage from a backend scheduled job instead.

The recommended unit is one aggregate event per account, product, metric, and closed time bucket:

{
  "event_id": "usage_rollup:acct_123:api_platform:api_calls:2026-06-01",
  "event_name": "usage_rollup_recorded",
  "account_id": "acct_123",
  "timestamp": "2026-06-02T00:10:00.000Z",
  "semantic_type": "usage",
  "event_kind": "product_action",
  "value": 148253,
  "properties": {
    "product_key": "api_platform",
    "metric_key": "api_calls",
    "unit": "request",
    "usage_start": "2026-06-01T00:00:00.000Z",
    "usage_end": "2026-06-02T00:00:00.000Z",
    "aggregation_grain": "day",
    "source_system": "usage_metering"
  }
}

Use a cron job, queue worker, warehouse job, or metering service to calculate these rows from the customer's source-of-truth usage table. Daily buckets are enough for most revenue signals. Hourly buckets are useful when usage changes quickly, a customer is near a limit, or the revenue team needs same-day routing.

The aggregate payload should answer:

Keep product_key, metric_key, and unit stable. Treat them like a small product and metric catalog. For example, api_platform + api_calls + request should keep the same meaning over time. If pricing or packaging changes, add properties such as plan, tier, or pricing_version; do not silently change the unit behind an existing metric key.

Prevent overloadCopy Anchor Link

Aggregate before sending. A customer with millions of API requests should usually send hundreds or thousands of aggregate rows, not millions of Direct API calls. In the standard Direct API path, each request should represent an aggregate row; for very large row counts, use a bulk import plan instead of increasing concurrency.

Use these guardrails:

• Send only closed buckets, such as the previous hour or previous day.
• Use deterministic event_id values so retries are treated as the same logical event instead of duplicating usage.
• Retry failed rows with backoff and the same event_id.
• Split backfills into small date ranges and send oldest closed periods first.
• Keep each request compact. The Direct API accepts small JSON event payloads, not raw logs or large arrays.
• Start scheduled jobs with low concurrency, then increase only after Activity shows healthy accepts and low rejection rates.
• Send milestone or threshold events separately, such as quota_blocked, limit_hit, overage_started, or plan_upgraded.

If the customer needs to send a large historical backfill or very large numbers of aggregate rows per run, coordinate a bulk import plan instead of increasing request concurrency.

Direct API event discoveryCopy Anchor Link

Use Direct API for events that are better known by the backend than the browser:

• Completed billing or subscription state changes.
• Checkout completed, invoice paid, payment failed, refund, downgrade completed, cancel completed.
• Durable setup milestones such as integration configured, OAuth connected, destination configured, API key created, or first event ingested.
• Metered usage, credits consumed, quota calculations, API calls, background jobs, sync results, and anything billable.
• first_* milestones that must be race-safe and based on persisted state.

Use the Web SDK instead for browser-only intent before backend state changes, visible prompts, page-level UI friction, and supplemental adoption signals.

When using an AI coding tool, ask it to classify event candidates as:

Event contractCopy Anchor Link

Every revenue-relevant Direct API event should include:

Use stable event_id values for completed state changes, for example checkout_completed:<checkout_id> or integration_connected:<provider>:<account_id>.

Do not emit first_* milestones unless persisted state proves first occurrence race-safely. If first-occurrence detection is approximate, skip the event or use a non-first_* name.

Name your usersCopy Anchor Link

Accounts list their users by user_id. Add a user object with the person's name and email, and the Account's Users tab shows them by name:

{
  "event_name": "report_exported",
  "account_id": "acct_123",
  "user_id": "user_456",
  "user": { "name": "Ada Lovelace", "email": "ada@example.com" },
  "timestamp": "2026-06-20T15:00:00.000Z"
}

SaaSFunnels keeps the latest name and email for each user_id and leaves them out of event properties. Sending a field again updates it; leaving it out keeps the stored value. The same user object is accepted on Funnel runtime sessions and customer-server events. Use the same user_id everywhere so events and Funnel sessions show as one person.

Events to add firstCopy Anchor Link

Start with a small allowlist of 3 to 6 high-signal backend events.

Sentiment fieldsCopy Anchor Link

Sentiment is optional and separate from the event family. Missing sentiment is stored as unknown, not neutral; use neutral only when the product signal is explicitly neutral.

Send explicit bounded sentiment from the backend when the source-of-truth system knows it. If sentiment is omitted, SaaSFunnels can infer a reviewable mapping default from the event name, semantic type, event kind, and bounded property keys. Explicit payload sentiment takes precedence over mapped sentiment.

Do not send free-text feedback, survey responses, chat messages, support transcripts, raw comments, or AI-generated summaries as sentiment context. Send bounded labels and scores only.

See Event KPI Signals for the canonical KPI definitions, evidence bands, and Account filters these fields power.

Data safetyCopy Anchor Link

Do not send:

• Passwords, tokens, cookies, signatures, auth headers, API keys, session values, invite links, webhook URLs, provider tokens, or destination secrets.
• Personal data outside the user object, full URLs with query strings, full request/response bodies, stack traces, raw logs, prompts, comments, notes, support messages, or descriptions.
• Generic page views, auth page views, modal opens, hovers, local UI toggles, or debug logs as first-batch Direct API events.

Verify setupCopy Anchor Link

Send one account-scoped activation, usage, limit, or setup event from backend code. Then check Settings > Integrations > Direct API and Events in SaaSFunnels.

A successful setup should show:

• The event is accepted by the Direct API route.
• The event normalizes successfully.
• The event attaches to the expected account.
• Rejected payloads clearly explain missing account_id, auth, or revenue relevance.
• No secrets, raw PII, query-string values, or full request/response bodies are stored.