> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stairoids.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Signals: Track Every B2B Engagement Across Your Stack

> Signals are discrete engagement events tied to accounts and contacts. They power every automation, score, and insight inside Stairoids.

Signals are the heartbeat of Stairoids. Every time a prospect visits your website, opens an email, submits a form, or advances through a CRM stage, Stairoids captures that moment as a structured signal — a timestamped, scored event linked to an account and contact. These signals flow through the platform's intelligence engine and trigger automated actions across your connected tools, giving your team a real-time picture of who is engaging, how deeply, and when to act.

## Signal Anatomy

Every signal in Stairoids shares the same core structure, regardless of where it originated. Understanding this structure helps you configure field mappings, write filters, and build automations with precision.

<ResponseField name="id" type="string" required>
  A globally unique identifier for the signal event, assigned by Stairoids on ingestion (e.g. `sig_01hx4k9mz3fqp7yw`).
</ResponseField>

<ResponseField name="type" type="string" required>
  The event category that classifies what happened. See [Signal Types](#signal-types) below for the full list of built-in types.
</ResponseField>

<ResponseField name="account" type="string" required>
  The domain of the company associated with the event (e.g. `acme.com`). Stairoids uses this field to attribute signals to the correct account record and aggregate engagement scores.
</ResponseField>

<ResponseField name="contact" type="string">
  The email address of the individual who triggered the event (e.g. `jane@acme.com`). Optional when the identity is unknown, such as an anonymous page visit.
</ResponseField>

<ResponseField name="source" type="string" required>
  The name of the integration or ingestion method that produced the signal (e.g. `hubspot`, `webhook`, `api`). Used for filtering, attribution, and debugging.
</ResponseField>

<ResponseField name="properties" type="object">
  An open key-value map carrying event-specific metadata. For a `page_visit`, this might include `url` and `referrer`. For a `crm_stage_change`, it might include `from_stage` and `to_stage`. All values must be strings, numbers, or booleans.
</ResponseField>

<ResponseField name="score" type="number">
  The contribution of this individual signal to the account and contact engagement score at the time of ingestion. Computed automatically by [Signal Intelligence](/signals/signal-intelligence) based on signal type, recency, and frequency.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp recording when Stairoids ingested the signal (e.g. `2024-06-15T14:32:07Z`).
</ResponseField>

## Signal Types

Stairoids ships with a set of built-in signal types that cover the most common B2B engagement events. You can also define custom types by sending any string value in the `type` field via webhook or API.

| Type                  | Description                                              | Example Source          |
| --------------------- | -------------------------------------------------------- | ----------------------- |
| `page_visit`          | A contact or anonymous visitor loaded a tracked page     | Leadfeeder, JS snippet  |
| `email_open`          | A contact opened a tracked email                         | HubSpot, Mailchimp      |
| `email_click`         | A contact clicked a link inside an email                 | HubSpot, Lemlist        |
| `form_submit`         | A contact submitted a lead capture or gated content form | HubSpot Forms, Typeform |
| `crm_stage_change`    | A deal or contact moved to a new pipeline stage          | HubSpot, Pipedrive      |
| `linkedin_connection` | A prospect accepted a LinkedIn connection request        | HeyReach, Expandi       |
| `meeting_booked`      | A contact scheduled a meeting or demo                    | Calendly, Chili Piper   |
| `deal_created`        | A new deal record was created in your CRM                | HubSpot, Pipedrive      |

## Sample Signal Object

The JSON below shows a fully populated signal as it is stored and returned by the Stairoids API. This is the canonical shape you will encounter when querying signals, building webhook consumers, or debugging automations.

```json theme={null}
{
  "id": "sig_01hx4k9mz3fqp7yw",
  "type": "form_submit",
  "account": "acme.com",
  "contact": "jane@acme.com",
  "source": "hubspot",
  "properties": {
    "form_name": "Request a Demo",
    "page_url": "https://yoursite.com/demo",
    "utm_source": "linkedin",
    "utm_campaign": "q2-outbound"
  },
  "score": 18,
  "created_at": "2024-06-15T14:32:07Z"
}
```

## How Signals Enter Stairoids

There are three ways to get signals into the platform. Choose the method that best fits each tool in your stack — most teams use all three.

**Native integrations** are the fastest path. Connect a supported tool in Settings → Integrations and signals begin flowing immediately with no custom configuration. Field mapping is handled automatically.

**Webhook listeners** give you a unique inbound URL that any tool can POST events to. You configure the source tool to send data; Stairoids parses and normalises the payload using the field mapping you define.

**Direct API** gives you full programmatic control. Use `POST /v1/signals` with your API key to push signals from your own backend, data pipelines, or custom scripts.

<CardGroup cols={3}>
  <Card title="Incoming Automations" icon="arrow-down-to-bracket" href="/signals/incoming-automations">
    Configure native integrations, webhook listeners, and direct API ingestion to get signals flowing into Stairoids.
  </Card>

  <Card title="Signal Intelligence" icon="brain-circuit" href="/signals/signal-intelligence">
    See how Stairoids scores, correlates, and surfaces your signals into unified account and contact views.
  </Card>

  <Card title="Outgoing Automations" icon="arrow-up-from-bracket" href="/signals/outgoing-automations">
    Trigger actions in your CRM, sequencer, and other tools the moment the right engagement conditions are met.
  </Card>
</CardGroup>