Create alert API

Create alert API

curl --request POST \
  --url https://api.technologychecker.io/v1/alerts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Who leaves Shopify (US, 51-200)",
  "signal_types": [
    "switch"
  ],
  "technology_id": 2184,
  "direction": "from",
  "filters": {
    "min_confidence": 0.5,
    "country": "united states",
    "employees": "51-200"
  },
  "webhook_url": "https://example.com/hooks/tc",
  "backfill_days": 7
}
'

import requests

url = "https://api.technologychecker.io/v1/alerts"

payload = {
    "name": "Who leaves Shopify (US, 51-200)",
    "signal_types": ["switch"],
    "technology_id": 2184,
    "direction": "from",
    "filters": {
        "min_confidence": 0.5,
        "country": "united states",
        "employees": "51-200"
    },
    "webhook_url": "https://example.com/hooks/tc",
    "backfill_days": 7
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Who leaves Shopify (US, 51-200)',
    signal_types: ['switch'],
    technology_id: 2184,
    direction: 'from',
    filters: {min_confidence: 0.5, country: 'united states', employees: '51-200'},
    webhook_url: 'https://example.com/hooks/tc',
    backfill_days: 7
  })
};

fetch('https://api.technologychecker.io/v1/alerts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.technologychecker.io/v1/alerts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Who leaves Shopify (US, 51-200)',
    'signal_types' => [
        'switch'
    ],
    'technology_id' => 2184,
    'direction' => 'from',
    'filters' => [
        'min_confidence' => 0.5,
        'country' => 'united states',
        'employees' => '51-200'
    ],
    'webhook_url' => 'https://example.com/hooks/tc',
    'backfill_days' => 7
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.technologychecker.io/v1/alerts"

	payload := strings.NewReader("{\n  \"name\": \"Who leaves Shopify (US, 51-200)\",\n  \"signal_types\": [\n    \"switch\"\n  ],\n  \"technology_id\": 2184,\n  \"direction\": \"from\",\n  \"filters\": {\n    \"min_confidence\": 0.5,\n    \"country\": \"united states\",\n    \"employees\": \"51-200\"\n  },\n  \"webhook_url\": \"https://example.com/hooks/tc\",\n  \"backfill_days\": 7\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.technologychecker.io/v1/alerts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Who leaves Shopify (US, 51-200)\",\n  \"signal_types\": [\n    \"switch\"\n  ],\n  \"technology_id\": 2184,\n  \"direction\": \"from\",\n  \"filters\": {\n    \"min_confidence\": 0.5,\n    \"country\": \"united states\",\n    \"employees\": \"51-200\"\n  },\n  \"webhook_url\": \"https://example.com/hooks/tc\",\n  \"backfill_days\": 7\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.technologychecker.io/v1/alerts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Who leaves Shopify (US, 51-200)\",\n  \"signal_types\": [\n    \"switch\"\n  ],\n  \"technology_id\": 2184,\n  \"direction\": \"from\",\n  \"filters\": {\n    \"min_confidence\": 0.5,\n    \"country\": \"united states\",\n    \"employees\": \"51-200\"\n  },\n  \"webhook_url\": \"https://example.com/hooks/tc\",\n  \"backfill_days\": 7\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "alert": {
      "id": "alrt_9f2c4a1e",
      "name": "Who leaves Shopify (US, 51-200)",
      "signal_types": [
        "switch"
      ],
      "scope": {
        "kind": "technology",
        "technology_id": 2184,
        "technology_name": "Shopify",
        "category_id": 123,
        "domains": [
          "<string>"
        ],
        "segment_id": "<string>"
      },
      "direction": "from",
      "missing_category_id": 123,
      "filters": {
        "min_confidence": 0.5,
        "churn_reliability": [
          "high",
          "medium"
        ],
        "min_confidence_label": "medium",
        "country": "united states",
        "city": "<string>",
        "state": "<string>",
        "industry": "<string>",
        "industry_code": 123,
        "employees": "51-200",
        "company_type": "<string>",
        "founded_min": 123,
        "founded_max": 123,
        "company": true,
        "has_email": true,
        "has_phone": true,
        "social": "<string>",
        "language": "<string>",
        "web_country": "<string>"
      },
      "webhook_url": "https://example.com/hooks/tc",
      "status": "active",
      "delivery_frequency": "daily",
      "crawl_cadence": "monthly",
      "last_fired_at": "2026-06-10 17:39:39",
      "consecutive_failures": 0,
      "created_at": "2026-06-10T16:39:39.000Z",
      "updated_at": "2026-06-10T16:39:39.000Z",
      "webhook_secret": "whsec_3f9a2b7c1d4e5f60"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Provide exactly one scope: technology_id, technology or category_id."
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

{
  "success": false,
  "error": {
    "code": "PLAN_LIMIT",
    "message": "Your plan allows up to 2 saved audiences. Delete one to create another."
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

POST

alerts

Create alert API

curl --request POST \
  --url https://api.technologychecker.io/v1/alerts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Who leaves Shopify (US, 51-200)",
  "signal_types": [
    "switch"
  ],
  "technology_id": 2184,
  "direction": "from",
  "filters": {
    "min_confidence": 0.5,
    "country": "united states",
    "employees": "51-200"
  },
  "webhook_url": "https://example.com/hooks/tc",
  "backfill_days": 7
}
'

import requests

url = "https://api.technologychecker.io/v1/alerts"

payload = {
    "name": "Who leaves Shopify (US, 51-200)",
    "signal_types": ["switch"],
    "technology_id": 2184,
    "direction": "from",
    "filters": {
        "min_confidence": 0.5,
        "country": "united states",
        "employees": "51-200"
    },
    "webhook_url": "https://example.com/hooks/tc",
    "backfill_days": 7
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Who leaves Shopify (US, 51-200)',
    signal_types: ['switch'],
    technology_id: 2184,
    direction: 'from',
    filters: {min_confidence: 0.5, country: 'united states', employees: '51-200'},
    webhook_url: 'https://example.com/hooks/tc',
    backfill_days: 7
  })
};

fetch('https://api.technologychecker.io/v1/alerts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.technologychecker.io/v1/alerts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Who leaves Shopify (US, 51-200)',
    'signal_types' => [
        'switch'
    ],
    'technology_id' => 2184,
    'direction' => 'from',
    'filters' => [
        'min_confidence' => 0.5,
        'country' => 'united states',
        'employees' => '51-200'
    ],
    'webhook_url' => 'https://example.com/hooks/tc',
    'backfill_days' => 7
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.technologychecker.io/v1/alerts"

	payload := strings.NewReader("{\n  \"name\": \"Who leaves Shopify (US, 51-200)\",\n  \"signal_types\": [\n    \"switch\"\n  ],\n  \"technology_id\": 2184,\n  \"direction\": \"from\",\n  \"filters\": {\n    \"min_confidence\": 0.5,\n    \"country\": \"united states\",\n    \"employees\": \"51-200\"\n  },\n  \"webhook_url\": \"https://example.com/hooks/tc\",\n  \"backfill_days\": 7\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.technologychecker.io/v1/alerts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Who leaves Shopify (US, 51-200)\",\n  \"signal_types\": [\n    \"switch\"\n  ],\n  \"technology_id\": 2184,\n  \"direction\": \"from\",\n  \"filters\": {\n    \"min_confidence\": 0.5,\n    \"country\": \"united states\",\n    \"employees\": \"51-200\"\n  },\n  \"webhook_url\": \"https://example.com/hooks/tc\",\n  \"backfill_days\": 7\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.technologychecker.io/v1/alerts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Who leaves Shopify (US, 51-200)\",\n  \"signal_types\": [\n    \"switch\"\n  ],\n  \"technology_id\": 2184,\n  \"direction\": \"from\",\n  \"filters\": {\n    \"min_confidence\": 0.5,\n    \"country\": \"united states\",\n    \"employees\": \"51-200\"\n  },\n  \"webhook_url\": \"https://example.com/hooks/tc\",\n  \"backfill_days\": 7\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "alert": {
      "id": "alrt_9f2c4a1e",
      "name": "Who leaves Shopify (US, 51-200)",
      "signal_types": [
        "switch"
      ],
      "scope": {
        "kind": "technology",
        "technology_id": 2184,
        "technology_name": "Shopify",
        "category_id": 123,
        "domains": [
          "<string>"
        ],
        "segment_id": "<string>"
      },
      "direction": "from",
      "missing_category_id": 123,
      "filters": {
        "min_confidence": 0.5,
        "churn_reliability": [
          "high",
          "medium"
        ],
        "min_confidence_label": "medium",
        "country": "united states",
        "city": "<string>",
        "state": "<string>",
        "industry": "<string>",
        "industry_code": 123,
        "employees": "51-200",
        "company_type": "<string>",
        "founded_min": 123,
        "founded_max": 123,
        "company": true,
        "has_email": true,
        "has_phone": true,
        "social": "<string>",
        "language": "<string>",
        "web_country": "<string>"
      },
      "webhook_url": "https://example.com/hooks/tc",
      "status": "active",
      "delivery_frequency": "daily",
      "crawl_cadence": "monthly",
      "last_fired_at": "2026-06-10 17:39:39",
      "consecutive_failures": 0,
      "created_at": "2026-06-10T16:39:39.000Z",
      "updated_at": "2026-06-10T16:39:39.000Z",
      "webhook_secret": "whsec_3f9a2b7c1d4e5f60"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Provide exactly one scope: technology_id, technology or category_id."
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

{
  "success": false,
  "error": {
    "code": "PLAN_LIMIT",
    "message": "Your plan allows up to 2 saved audiences. Delete one to create another."
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

Frequently asked questions

What can I alert on?

Anything you can query. There are five practical shapes: adoption on a technology or category, churn on a technology or category, switch on a technology with a direction or across a category, an account watchlist (["churn","adoption"] on a domains scope, for any stack change on domains you name), and a whitespace entrant (an adoption alert plus missing_category_id, which fires when a domain adopts your anchor while still running nothing in the gap category).

Where do I get the webhook secret?

It is in the create response as webhook_secret, prefixed whsec_. Store it immediately — it signs every delivery. You can also read it back later from the alert detail endpoint, which is the only other place it appears.

What is a HOT_SCOPE rejection?

A guard against alerts that can never work. Each delivery carries at most 100 events, so a scope generating more events per hour than that can never drain its backlog and would deliver permanently stale data. At creation we estimate the scope’s rate over the last 7 days and reject the ones that are too hot, with guidance. The fix is always to narrow: add firmographic filters, raise min_confidence, or use a technology scope instead of a whole category.

What does backfill_days do?

It sets the initial watermark to that many days ago, so your very first sweep delivers real events instead of waiting for something new to happen. The default is 7 and the maximum is 30. Set it to 0 if you only want events from now on.

Why can't I change the scope later?

The watermark tracks how far through a specific scope we have delivered, so its meaning is bound to that scope. Changing the scope would make the watermark meaningless and either replay or skip events. Delete the alert and create a new one instead. Everything else — name, status, webhook URL, filters, cadence, delivery frequency — is editable.

How do I stop churn alerts being noisy?

Two independent knobs. filters.churn_reliability gates on the detection method and already defaults to ["high","medium"], which excludes technologies whose detection flaps. filters.min_confidence_label gates on the combined per-event score and applies to adoption too. Setting it to medium or higher drops single-scan churns, which are the bulk of the noise — around half of them turn out to be false positives on live re-detection.

Authorizations

Authorization

string

header

required

API key in format tapi_live_[32-char] (live) or tapi_test_[32-char] (test)

Body

application/json

name

string

required

Example:

"Who leaves Shopify (US, 51-200)"

signal_types

enum<string>[]

required

["churn","adoption"] means any stack change, which is the natural account watch. switch cannot be combined with the others because its event shape differs.

Available options:

churn,

adoption,

switch

Example:

["switch"]

webhook_url

string<uri>

required

HTTPS only. Private, internal and metadata hosts are rejected, and redirects are never followed.

Example:

"https://example.com/hooks/tc"

technology_id

integer

Technology scope. Must be a detectable technology.

Example:

2184

technology

string

Technology scope by exact name.

category_id

integer

Category scope. Re-resolved fresh at every sweep, so technologies added to the category are covered automatically.

domains

string[]

Domains scope — the account watchlist. 1 to 1,000 domains (100 on Free). Normalized to lowercase and deduped; invalid entries are rejected with the offending values.

Example:

["acme.com", "example.com"]

segment_id

string

Audience scope. List audiences only; membership resolves live at each sweep.

direction

enum<string>

default:from

Switch alerts on a technology scope only. from is who left the anchor; to is who came to it.

Available options:

from,

to

missing_category_id

integer

Turns an adoption alert into a whitespace-entrant alert. Requires signal_types of exactly ["adoption"], a technology or category scope, and a category different from the anchor.

min_scans

integer

Whitespace precision gate. Defaults to 2 when missing_category_id is set.

Required range: 1 <= x <= 10

filters

object

Row-level filters applied to every sweep. Firmographic keys use the same vocabulary as the Signals API.

Show child attributes

delivery_frequency

enum<string>

default:daily

daily batches a day's events into one digest delivery. hourly is a per-sweep drip. Independent of crawl_cadence.

Available options:

hourly,

daily

crawl_cadence

enum<string>

default:monthly

Domains scope on a paid plan only. Buys re-scans of the watched domains so the underlying data refreshes as fast as the subscription. Forced to monthly on other scopes.

Available options:

daily,

weekly,

monthly

backfill_days

integer

default:7

How far back the first sweep reaches. 0 means future events only.

Required range: 0 <= x <= 30

Response

Alert created. webhook_secret is returned here — store it.

success

boolean

Example:

true

data

object

Show child attributes

⌘I

Getting started

Domain technologies

Technology data

Market intelligence

Company data

Live detection

Signals

Alerts

Audiences

Lead lists

Frequently asked questions

Authorizations

Body

Response

​Frequently asked questions

Authorizations

Body

Response

Frequently asked questions