Send a Signal — POST /v1/signals

Use this endpoint to push any engagement event into Stairoids from your tools or automation platform. A signal represents a meaningful interaction — a page visit, form submission, email open, or any custom event you define — and immediately contributes to account and contact scoring within your workspace.

Endpoint

POST https://api.stairoids.com/v1/signals

Authentication

Include your API key as a Bearer token in the Authorization header of every request.

Authorization: Bearer <api-key>
Content-Type: application/json

Request Body

type

string

required

The signal type. Can be any non-empty string. Use consistent, descriptive values across your integration — for example page_visit, email_open, or form_submit.

account

object

Account identification. Required if contact is omitted. At least one of account or contact must be present on every request.

Show account properties

account.domain

string

required

The company’s root domain, e.g. acme.com. Used to match or create an account record in your workspace.

account.name

string

A human-readable display name for the company, e.g. Acme Corp. Used only when creating a new account record.

contact

object

Contact identification. Required if account is omitted. At least one of account or contact must be present on every request.

Show contact properties

contact.email

string

required

The contact’s email address, e.g. alice@acme.com. Used to match or create a contact record in your workspace.

contact.first_name

string

The contact’s first name. Used only when creating a new contact record.

contact.last_name

string

The contact’s last name. Used only when creating a new contact record.

source

string

The name of the originating tool or system that generated this signal, e.g. activecampaign, my-website, or zapier. Helps you filter and attribute signals by integration.

properties

object

An arbitrary set of key-value pairs you want to attach to this signal. Values can be strings, numbers, or booleans. For example: { "page": "/pricing", "duration_seconds": 45 }.

occurred_at

string

An ISO 8601 timestamp representing when the event actually occurred, e.g. 2024-06-15T14:23:00Z. If omitted, Stairoids records the current server time.

If account.domain or contact.email matches an existing record in your workspace, the signal is attributed to that record. Otherwise, Stairoids automatically creates a new account or contact.

Code Examples

curl --request POST \
  --url https://api.stairoids.com/v1/signals \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "page_visit",
    "account": {
      "domain": "acme.com",
      "name": "Acme Corp"
    },
    "contact": {
      "email": "alice@acme.com",
      "first_name": "Alice",
      "last_name": "Chen"
    },
    "source": "my-website",
    "properties": {
      "page": "/pricing",
      "duration_seconds": 45
    },
    "occurred_at": "2024-06-15T14:23:00Z"
  }'

Response

All successful responses return HTTP 201 Created and a JSON envelope containing data and meta objects.

Response Fields

data

object

The created signal object.

Hide data properties

data.id

string

The unique identifier for this signal, e.g. sig_abc123. Store this if you need to retrieve the signal later.

data.type

string

The signal type, echoed from your request.

data.account

object

The matched or newly created account record associated with this signal.

Show account properties

data.account.id

string

The unique identifier for the account record, e.g. acc_xyz789.

data.account.domain

string

The root domain of the account, e.g. acme.com.

data.account.name

string

The display name of the account, e.g. Acme Corp.

data.account.score

number

The current aggregate score for this account across all signals.

data.contact

object | null

The matched or newly created contact record associated with this signal. Returns null if no contact was provided.

Show contact properties

data.contact.id

string

The unique identifier for the contact record, e.g. con_def456.

data.contact.email

string

The email address of the contact, e.g. alice@acme.com.

data.contact.score

number

The current aggregate score for this contact across all signals.

data.score

number

The score contribution of this individual signal, on a scale of 0–100. Score weights are configured in your workspace settings.

data.source

string

The originating source, echoed from your request.

data.properties

object

The custom properties attached to this signal, echoed from your request.

data.created_at

string

The ISO 8601 timestamp at which Stairoids recorded this signal.

Example Response

{
  "data": {
    "id": "sig_abc123",
    "type": "page_visit",
    "account": {
      "id": "acc_xyz789",
      "domain": "acme.com",
      "name": "Acme Corp",
      "score": 84
    },
    "contact": {
      "id": "con_def456",
      "email": "alice@acme.com",
      "score": 42
    },
    "score": 12,
    "source": "my-website",
    "properties": {
      "page": "/pricing",
      "duration_seconds": 45
    },
    "created_at": "2024-06-15T14:23:01Z"
  },
  "meta": {
    "request_id": "req_11aabb22ccdd",
    "timestamp": "2024-06-15T14:23:01Z"
  }
}

Error Responses

401 Unauthorized
422 Validation Error

Returned when the Authorization header is missing or your API key is invalid.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "request_id": "req_99qqrr00sstt"
  }
}

Returned when required fields are missing or have invalid values — for example, if neither account nor contact is provided, or if type is an empty string.

{
  "error": {
    "code": "validation_error",
    "message": "At least one of account.domain or contact.email is required.",
    "request_id": "req_aabbcc112233"
  }
}

​Endpoint

​Authentication

​Request Body

​Code Examples

​Response

​Response Fields

​Example Response

​Error Responses

Endpoint

Authentication

Request Body

Code Examples

Response

Response Fields

Example Response

Error Responses