Lumen Documentation

Overview

Lumen is a context-aware intelligence layer for operations teams. It connects to your existing CRM, ERP, product analytics, and support systems, builds a unified model of how your business operates, and delivers proactive signals and scheduled briefings — without replacing the tools your team already uses.

All connectors operate in read-only mode by default. Lumen never modifies source data unless you explicitly enable write-back features on Enterprise plans.

Core concepts

Quickstart

Follow these steps to connect your first systems and receive an initial briefing.

Prerequisites

• Admin or integration-user access to at least one CRM or ERP system
• Outbound HTTPS access from Lumen to your SaaS APIs (or VPC deployment for Enterprise)
• A designated workspace owner and at least one department lead for briefing review

Setup

1. Create your workspace
   Sign up at app.lumen.io and invite team members. Assign roles: Admin, Editor, or Viewer.
2. Authorize connectors
   Go to Settings → Integrations. Connect your first system via OAuth or API key. Start with CRM and billing for the fastest time-to-value.
3. Review entity mappings
   Lumen suggests how records map across systems. Confirm or adjust in Settings → Entity Resolution before enabling signals.
4. Enable a briefing template
   Choose a role-based template (Sales Ops, CS, Finance) and set delivery time and channel.
5. Configure your first signal
   Use a pre-built template (e.g. "Stale deal") or define a custom condition. Set severity and routing.

Architecture

Lumen ingests data through connector APIs, normalizes records into a context graph, runs signal detection on a continuous schedule, and generates briefings on configured intervals. Delivery happens via email, Slack, webhooks, or the REST API.

Data flow

• Ingestion — Connectors poll or receive webhooks from source systems every 5–60 minutes depending on plan.
• Normalization — Raw records are mapped to Lumen entity types with source attribution preserved.
• Resolution — Entity mapping rules link the same customer across different IDs and systems.
• Processing — Signal conditions evaluate against the graph. Briefings aggregate relevant context at scheduled times.
• Delivery — Outputs include source links, timestamps, and audit IDs for every claim.

Authentication

Lumen supports two authentication methods for API access: workspace API keys and OAuth 2.0 for user-scoped operations.

API keys

Generate keys in Settings → API Keys. Keys are scoped to your workspace and inherit the permissions of the creating user. Pass the key in the Authorization header:

Authorization: Bearer lumen_live_xxxxxxxxxxxxxxxx

OAuth 2.0

For applications acting on behalf of users, use the authorization code flow. Redirect URI, client ID, and client secret are configured in Settings → OAuth Applications.

Connectors

Lumen ships with 40+ pre-built connectors. Each supports read-only access by default and can be configured with custom sync intervals.

Connector status, last sync time, and error logs are visible in Settings → Integrations. Failed syncs retry with exponential backoff and trigger a workspace notification after three consecutive failures.

Entity mapping

When the same customer appears with different identifiers across systems, Lumen applies mapping rules to resolve a single entity. During onboarding, Lumen suggests mappings based on email domains, company names, and external ID cross-references.

Mapping rule types

• Exact match — Same external ID configured in both systems
• Field match — Email, domain, or custom field equality
• Manual link — Admin explicitly links two records
• Confidence score — Fuzzy matches above 0.85 are suggested for review

Review and adjust mappings in Settings → Entity Resolution. Incorrect mappings affect signal accuracy — validate after connecting new systems.

Signals

Signals monitor the context graph for specific conditions and trigger alerts when matched. Each signal defines a condition, severity, cooldown period, and routing policy.

Pre-built signal templates

Custom signals

Define conditions using the signal builder in the workspace, or via the API. Custom signals require Growth or Enterprise plans.

{
  "name": "Enterprise pipeline stall",
  "condition": {
    "entity_type": "opportunity",
    "filters": { "segment": "enterprise", "days_since_activity": { "gte": 14 } },
    "stage_unchanged_days": { "gte": 7 }
  },
  "severity": "high",
  "cooldown_hours": 24,
  "route_to": ["slack:#sales-ops", "owner:account.executive"]
}

Briefings

Briefings are scheduled summaries tailored by role and department. Each briefing template defines included sections, delivery time, format, and audience.

Available templates

• Sales Ops — Pipeline coverage, stale deals, forecast variance, closed-won/lost
• Customer Success — Health score changes, renewal timeline, support volume spikes
• Engineering — Sprint progress, open blockers, incident summary, PR velocity
• Finance / FP&A — Revenue vs. plan, variance narrative, billing anomalies
• Leadership — Cross-department summary with top signals and key metrics

Every briefing item includes a source reference (system, record ID, timestamp) so recipients can verify claims without leaving their workflow.

Alert routing

Route signals and briefings based on ownership, team membership, or escalation policies.

Routing targets

• email:user@company.com — Direct email delivery
• slack:#channel-name — Slack channel (Growth+)
• owner:account.executive — Dynamic routing to entity owner field
• webhook:https://... — Custom endpoint (Growth+)
• pagerduty:service-id — PagerDuty escalation (Enterprise)

Escalation policies define what happens when a signal is not acknowledged within a configured window. Available on Enterprise plans.

REST API

The Lumen REST API provides programmatic access to entities, signals, briefings, and audit logs. Base URL:

https://api.lumen.io/v1

All requests and responses use JSON. Timestamps are ISO 8601 UTC. Pagination uses cursor-based next_cursor tokens.

Common headers

Entities

Ingest or update an entity from a custom source. Requires Growth or Enterprise plan.

POST /v1/entities
Authorization: Bearer lumen_live_xxxxxxxx
Content-Type: application/json

{
  "type": "account",
  "external_id": "acc_12345",
  "source": "internal_crm",
  "attributes": {
    "name": "Acme Corp",
    "arr": 48000,
    "segment": "enterprise",
    "owner_email": "sarah@acme.com"
  }
}

Retrieve a resolved entity with source attributions and linked records across systems.

Briefings

List generated briefings. Filter by template, date range, or department.

Trigger on-demand briefing generation for a specific template. Rate limited to 10 requests per hour per workspace.

{
  "id": "brf_8k2m9x",
  "template": "sales_ops",
  "generated_at": "2026-08-22T06:02:00Z",
  "sections": [
    {
      "title": "Pipeline attention",
      "items": [
        {
          "summary": "Acme Corp — no activity in 14 days",
          "severity": "high",
          "sources": [{ "system": "salesforce", "record_id": "006xx", "url": "..." }]
        }
      ]
    }
  ]
}

Webhooks

Subscribe to workspace events for downstream automation. Configure endpoints in Settings → Webhooks.

Event types

• signal.triggered — A signal condition matched
• briefing.completed — Scheduled briefing generated
• connector.sync_failed — Connector failed after retries
• entity.resolved — New cross-system entity link created

{
  "event": "signal.triggered",
  "timestamp": "2026-08-22T14:30:00Z",
  "data": {
    "signal_id": "sig_stale_deal",
    "severity": "high",
    "summary": "Acme Corp — no activity in 14 days, stage unchanged",
    "entity_id": "ent_acme_corp",
    "sources": [
      { "system": "salesforce", "record_id": "006xx000004T2MQ", "field": "LastActivityDate" }
    ]
  }
}

Webhook requests include an X-Lumen-Signature header (HMAC-SHA256). Verify signatures before processing payloads.

Errors & rate limits

HTTP status codes

Rate limits

{
  "error": {
    "code": "invalid_parameter",
    "message": "Field 'external_id' is required.",
    "param": "external_id",
    "request_id": "req_9f3k2m"
  }
}

Security

• SOC 2 Type II certified — report available under NDA for Enterprise customers
• Encryption — TLS 1.3 in transit, AES-256 at rest
• Access control — Role-based permissions (Admin, Editor, Viewer) with SSO on Enterprise
• Audit logs — Immutable log of all API calls, config changes, and data access
• Data retention — Configurable per workspace; default 24 months for processed data
• VPC deployment — Available on Enterprise for customers with strict data residency requirements

Report security issues to security@lumen.io. We acknowledge reports within 24 hours.

Deployment options

Support

Contact support or your account manager. For onboarding assistance, book a call through the demo request page.