Signals

Signals Overview

Learn about signal types, how they work, and how to configure them for your use case.

#What are Signals?

Signals are a way to ingest structured data from your application into Bigmind. When an event occurs in your system — a customer visits a page, a deal reaches a milestone, or a metric changes — you send it to Bigmind as a signal event. Bigmind then uses AI to analyze these events in context and generate actionable insights for your team.

#Signal Types

There are three types of signals, each designed for different kinds of data:

Event Signals

Events are discrete occurrences — something happened at a point in time. Each event is independent and carries its own data payload.

Examples:

  • Customer visited a documentation page
  • User signed up for a trial
  • Support ticket was escalated
  • Contract was signed

Rate limit: 100 requests/min per signal

Metric Signals

Metrics are numeric values that are aggregated over a time period. When you send metric events, Bigmind automatically aggregates them using the configured aggregation function (sum, count, avg, min, max) over the configured period (hour, day, week, month).

Examples:

  • Number of API calls per day
  • Revenue generated per week
  • Average response time per hour
  • Total page views per month

Rate limit: 1,000 requests/min per signal

State Signals

State signals represent the current status of something. Unlike events (which are additive), a state update replaces the previous state. Use these for tracking ongoing conditions.

Examples:

  • Customer health score: healthy / at-risk / churning
  • Integration status: connected / disconnected / error
  • Account tier: free / pro / enterprise

Rate limit: 30 requests/min per signal

#Key Concepts

Signal Slug

Every signal has a unique slug (e.g., visited-documentation-page) that you use in API requests. The slug is auto-generated from the signal name but can be customized. It must be URL-safe and unique within your organization.

Identity

Each event must be associated with a CRM object via an identity. The identity specifies what type of object the event relates to and its ID in your CRM:

"identity": {
  "type": "account",
  "id": "001ABC000000123"
}

Supported standard object types:

Type Description
account A company or organization in your CRM
contact An individual person/contact
deal A sales opportunity or deal
lead A sales lead

You can also use custom object types that match your CRM's custom objects (e.g., bigmind_organizations).

Applicable Object Types

Each signal is configured with which object types it applies to. For example, a "Page Visit" signal might apply to accounts and contacts, while a "Deal Stage Changed" signal only applies to deals. When sending events, the identity.type must match one of the signal's applicable object types.

Schema & Schema Versioning

Each signal can have a JSON Schema that defines the structure of the data payload. Schemas serve two purposes:

  • Validation — incoming events are validated against the schema so malformed data is rejected early
  • AI context — field descriptions in the schema are used by Bigmind's AI agent to understand what each field means and how to generate insights from it

As the shape of your event data evolves, Bigmind automatically tracks schema versions. When sending an event you can specify:

  • "version": "latest" — use the latest schema version (recommended)
  • "version": 2 — pin to a specific schema version

Schemas are defined as standard JSON Schema objects. Here is an example for a "Page Visit" signal:

{
  "type": "object",
  "properties": {
    "page": {
      "type": "string",
      "description": "The URL path the customer visited, e.g. /docs/quickstart or /pricing"
    },
    "duration_seconds": {
      "type": "number",
      "description": "How long the customer spent on the page in seconds. Values above 120 indicate high engagement."
    },
    "referrer": {
      "type": "string",
      "description": "The referring URL that brought the customer to this page. Useful to understand traffic sources."
    },
    "is_authenticated": {
      "type": "boolean",
      "description": "Whether the customer was logged in when viewing the page. Authenticated visits indicate active product usage."
    }
  },
  "required": ["page"]
}

Tip: Write clear, descriptive description fields. Bigmind's AI agent reads these descriptions to understand the business context of each field and generate more relevant insights. For example, instead of "duration in seconds", write "How long the customer spent on the page in seconds. Values above 120 indicate high engagement."

Insights

Each signal has a default insight type and urgency level. When Bigmind's AI processes an event, it generates an insight with these defaults unless overridden:

Insight Type Description
opportunity A potential sales or expansion opportunity
risk A potential risk or churn indicator
action Something that requires immediate action
information General informational insight

Signal Trackers

Trackers let you subscribe to specific signals for specific object types and filter which records should be evaluated. For example, you can track the "Page Visit" signal only for enterprise accounts.

#Managing Signals

Signals, schemas, trackers, and all related configuration can be managed in the Bigmind UI at Settings → Enrichment → Signals. From there you can create new signals, edit existing ones, view schema versions, and set up trackers.

#API Key Security

Your API key (sk_...) should only be used in server-side code. Never expose it in client-side JavaScript, mobile apps, or public repositories. The same API key can be used to access other Bigmind APIs (meetings, webhooks, etc.), so treat it as a secret.

#Next Steps

Updated 3/16/2026