Sales Signals API User Manual

Overview

The Sales Signals API lets you set up, manage, and receive notifications (signals) about important events for domains (websites/companies) you care about. You can configure what you track, how you receive notifications, and review the history and status of all your signals.

Key API Entities:

• Signals: What you want to track (e.g., traffic changes, new markets, intent)
• Webhooks: Where the notifications should be sent (your endpoint URLs)
• Domains: The companies/websites you're monitoring
• Events: The log/history of all signal notifications
• Description endpoint: Shows you all valid values and configuration options for each signal type

API Architecture Cheat Sheet

JSON Schema Reference: API Endpoints

Below are the exact JSON request body schemas for every POST endpoint.

⚠️

Do not alter these schemas—they are enforced by the API.

GET endpoints do not require a request body.

1. Description

Endpoint: http://api.similarweb.com/v4/sales-signals/describe
Method: GET
No request body required.

2. Signals

Signals - Get All

Endpoint: /v4/sales-signals/signals/all
Method: GET
No request body required.

Signals - Deactivate

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/archive
Method: POST

{
  "id": "string"
}

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/traffic
Method: POST

{
    "traffic_changes":{
        "metric": "string",
        "direction": "string",
        "period": "string",
        "country": "string",
        "value": "number"
    }
}

Signals - Create New Market

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/traffic
Method: POST

{
  "new_markets": {
    "metric": "string",
    "countries": ["string"],
    "threshold_value": "number"
  }
}

Signals - Create News

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/news
Method: POST

{
  "categories": ["string"],
  "period": "string"
}

Signals - Create Intent

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/intent
Method: POST

{
  "topics": ["string"],
  "countries": ["string"]
}

Signals - Create AdNetworks

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/ad-network
Method: POST

{
  "ad_network_ids": ["string"],
  "action": "string"
}

Signals - Create Technology

Endpoint: http://api.similarweb.com/v4/sales-signals/signals/technology
Method: POST

{
  "period": "string",
  "type": "string",
  "technology_categories": ["string"],
  "technology_sub_categories": ["string"],
  "technologies": ["string"]
}

3. Webhooks

Webhooks - Get All Subscriptions

Endpoint: http://api.similarweb.com/v4/sales-signals/webhook-subscriptions/all
Method: GET
No request body required.

Webhooks - Add

Endpoint: http://api.similarweb.com/v4/sales-signals/webhook-subscriptions/add
Method: POST

{
  "url": "string",
  "signals_per_hook": "integer",
  "signal_types": ["string"]
}

Webhooks - Unsubscribe

Endpoint: http://api.similarweb.com/v4/sales-signals/webhook-subscriptions/archive
Method: POST

{
  "id": "string"
}

4. Domains

Domains - Subscribe

Endpoint: http://api.similarweb.com/v4/sales-signals/domains/subscribe
Method: POST

{
  "domains": ["string"]
}

Domains - Unsubscribe

Endpoint: http://api.similarweb.com/v4/sales-signals/domains/unsubscribe
Method: POST

{
  "domains": ["string"]
}

5. Events

Events - Resend

Endpoint: http://api.similarweb.com/v4/sales-signals/events/resend
Method: POST

{
  "subscription_id": "string",
  "date_from": "integer",
  "date_to": "integer",
  "status": "string",
  "ids": ["string"]
}

Events - History

Endpoint: http://api.similarweb.com/v4/sales-signals/events/history
Method: POST

{
  "subscription_id": "string",
  "date_from": "integer",
  "date_to": "integer",
  "status": "string",
  "ids": ["string"]
}

Notes:

• All string and number types, arrays, and field names must match the schemas above exactly
• Always refer to the Description endpoint for valid values for each field (such as allowed metrics, categories, countries, etc)

1. Description Endpoint: Your Single Source of Truth

Purpose:

Before you do anything, use the description endpoint to see what values are supported for each signal type.

⚠️

Why? The API is strict—only supported values are accepted. Enter something unsupported and you'll get a clear error.

What You Get from Description:

• Allowed percentages, metrics, periods, thresholds and directions for traffic and new market signals
• List of topics and countries for intent signals
• List of technologies for technology signals
• List of adnetworks and directions for Adnetwork signals
• List of news items for news signals

Practical tip:

Always check the description endpoint before configuring or changing signals. Don't guess.

2. Signals: Creating and Managing What You Track

2.1 Creating Signals

There are different endpoints and required parameters for each signal type.

Supported types:

• Traffic Change
• New Market
• Intent
• AdNetwork
• Technology changes
• News

Process:

1. Step 1: Decide what type of signal you need
2. Step 2: Check the description endpoint for required/allowed values
3. Step 3: Use the relevant signal creation endpoint and fill in the model with all required parameters

Error Handling:
If you submit a value that's not supported (wrong percentage, metric, action, etc.), you'll get a specific error. You cannot set up something the API doesn't allow.

2.2 Managing Signals

• Get all signals endpoint: Allows you to view your created signals, including filters, type, subtype, ID, and status
• Status: Can be active or deactivated (pause signals you don't want results for)
• Activate/Deactivate: Use dedicated endpoints to toggle status

3. Webhooks: Where the Signals Go

What's a Webhook?

An endpoint (URL) where the API sends notifications about signals you've set up.

3.1 Creating Webhooks

Required parameters:

• URL: Where notifications should be sent
• Signals per hook: How many signal events are sent in each HTTP request
• Signal types: Which types of signals should use this URL (can be specific or "all")

Examples:

• Only receive technology signals at a specific URL
• Use one URL for all five types of signals (traffic, new market, intent, etc.)

Behavior:
Once created, the webhook starts receiving events immediately.

3.2 Managing Webhooks

• Unsubscribe endpoint: Deactivate a webhook by its ID (stops sending events)
• Get all webhooks endpoint: See all your webhooks, their status (active/deactivated), which signal types they cover, how many signals per hook, and a creation timestamp

4. Domains: Specify What Companies to Track

You must subscribe domains to receive signals about them.

4.1 Subscribing/Unsubscribing Domains

• Subscribe endpoint: Add domains you want signals for
• Unsubscribe endpoint: Remove domains when you no longer need notifications

Pro tip:

Automate subscriptions using your CRM. For example, subscribe a domain when a new lead/account/contact is created in Salesforce or HubSpot. Unsubscribe when an account is no longer relevant (e.g., changes status in CRM).

5. Events: Monitoring, Troubleshooting, and Replay

Every signal notification sent by the API is an event. The events endpoints let you search, monitor, and retry signal deliveries.

5.1 Viewing Event History

• Search by event ID, status (notified, failed), date range, or subscription ID (webhook)
• Results are paginated due to potentially high volume
• For now, you can access two months of history

5.2 Troubleshooting Failed Events

• Filter by status to see failed deliveries
• Useful if your server had downtime or temporary issues

5.3 Re-sending Events

• Use the resend endpoint for all failed events in the past two months
• Filter by period or specific event IDs for more targeted resends

6. Common Pitfalls and Strong Recommendations

• Don't assume: The API will only accept pre-defined values. Always query the description endpoint first
• Error handling is strict and helpful: Expect clear errors for any unsupported parameter
• Automate where possible: Use your CRM's workflow automation to subscribe/unsubscribe domains
• Monitor event failures: Integrate event status checks and resending into your ops processes
• Keep your webhooks secure: Make sure only the API can access your endpoint URLs

Summary Flow Example

1. Query the description endpoint
2. Create signals with required and supported parameters
3. Set up webhooks for each type of signal you want to receive
4. Subscribe domains to monitor
5. Monitor events—check for failures, and resend as needed
6. Deactivate signals or webhooks when they're no longer relevant