Wire a brand-identity watchlist and run smishing takedown cases

This guide walks the full operator loop end to end: declare which tokens are legitimately yours, scan candidates you observe in the wild, open a takedown case for a hostile candidate, and work that case through to resolution. The reference material — detection signals, band thresholds, matching rules — lives in Brand impersonation watchlist, scan & takedown cases; this page is the task walkthrough. Every step uses cURL against the six endpoints under /api/v1/brand-identity/impersonation/*. The same surface is in the dashboard under Settings → Compliance → Brand impersonation watchlist.

1. What the impersonation monitor is

The impersonation monitor is a tenant-owned watchlist: you declare the brand names, domains, and sender IDs that are legitimately yours, and the scanner compares candidates you observe against those tokens. The watchlist persists under your organization settings (brand_impersonation_watchlist), so it is tenant-isolated and needs no schema migration — the same posture as other settings-backed compliance modules. Candidates come in three classes:

Lookalike domains — the host behind a smishing shortlink (acme-verify.tk, acnne.com).
Spoofed sender IDs — an SMS/RCS sender string that reads as your brand.
Display-name lookalikes — the sender name shown on WhatsApp, RCS, or a messaging platform.

The service is advisory only. It scores and prepares evidence; it never routes or sends anything, and no case status advances on its own. Filing a takedown notice with a registrar, carrier, or platform abuse desk is your action, done outside the product.

2. Create the watchlist

A PUT replaces the whole watchlist, so send all three lists every time:

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/brand-identity/impersonation/watchlist" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_names": ["Acme", "Acme Pay"],
    "protected_domains": ["acme.com", "acmepay.com"],
    "protected_sender_ids": ["ACME", "AcmePay"]
  }'

Node SDK

const watchlist = await orbit.request(
  'PUT',
  '/api/v1/brand-identity/impersonation/watchlist',
  {
    brand_names: ['Acme', 'Acme Pay'],
    protected_domains: ['acme.com', 'acmepay.com'],
    protected_sender_ids: ['ACME', 'AcmePay'],
  },
);

Constraints, validated at the edge:

Field	Item limit	List limit
`brand_names`	1–120 chars each	up to 20 entries
`protected_domains`	1–253 chars each	up to 50 entries
`protected_sender_ids`	1–20 chars each	up to 50 entries

Reads resolve to empty lists when you have never configured the watchlist; writes require an owner, admin, or developer role. Every replacement is recorded in your audit log (brand_identity.impersonation_watchlist.updated) with the entry counts, so you can trace who changed the declaration and when. Read the current watchlist back with GET on the same path.

3. Score a candidate

POST /brand-identity/impersonation/scan scores a batch of candidates against your watchlist. It is read-only: nothing persists, and repeating the same batch returns the same verdicts, so use it freely to triage before deciding whether a candidate deserves a case.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/brand-identity/impersonation/scan" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidates": [
      {
        "type": "domain",
        "value": "acme-verify.tk",
        "channel": "sms",
        "sample_text": "Acme: confirm your account at acme-verify.tk"
      },
      {
        "type": "sender_id",
        "value": "AcmeSupport"
      }
    ]
  }'

Each candidate’s verdict carries a score (0–100), a band (clean / suspicious / malicious), a recommendation (monitor / investigate / urgent_takedown), and the named findings that built the score. A sample verdict:

{
  "data": {
    "candidateCount": 1,
    "worstBand": "malicious",
    "urgentCount": 1,
    "investigateCount": 0,
    "verdicts": [
      {
        "candidate": {
          "type": "domain",
          "value": "acme-verify.tk",
          "channel": "sms",
          "observedAt": null,
          "sampleText": "Acme: confirm your account at acme-verify.tk",
          "sourceUrl": null
        },
        "matchedBrandToken": "acme",
        "score": 60,
        "band": "malicious",
        "recommendation": "urgent_takedown",
        "findings": [
          {
            "code": "combosquat",
            "severity": "block",
            "points": 40,
            "detail": "\"acme-verify.tk\" embeds the protected brand token \"acme\" but is not the tenant's registered asset"
          },
          {
            "code": "abused_tld",
            "severity": "warn",
            "points": 20,
            "detail": "Candidate domain uses the commonly-abused TLD \".tk\""
          }
        ]
      }
    ]
  },
  "meta": { "request_id": "req_01J…", "timestamp": "2026-08-24T12:00:00.000Z" }
}

Batches are capped at 50 candidates, duplicates collapse by (type, value), and verdicts sort worst score first. Your own registered assets always return a clean verdict — matching your own brand is not impersonation.

4. Assemble a takedown case

When a verdict deserves action, post the candidate to cases. The endpoint re-scores it, assembles a filing-ready evidence pack, stores the case, and returns its id:

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/brand-identity/impersonation/cases" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate": {
      "type": "domain",
      "value": "acme-verify.tk",
      "channel": "sms",
      "sample_text": "Acme: confirm your account at acme-verify.tk"
    },
    "note": "Reported by support on 2026-08-24; customer received smishing SMS."
  }'

The response’s data.caseId (formatted bpcase_…) is the handle you PATCH later. The evidence pack fields:

Field	What it carries
`candidate`	The candidate fingerprint you sent, echoed back.
`brandDisplayName`	Your first watchlisted brand name, used in the notice.
`matchedBrandToken`	Which protected token the candidate matched.
`score`, `band`, `findings`	The scoring detail, verbatim.
`recommendedRecipient`	The abuse-desk class best positioned to act (recipients below).
`noticeSummary`	A ready-to-send takedown notice text.

Recipient classes map from the candidate type:

Candidate type	`recommendedRecipient`
`domain`	`domain_registrar_abuse`
`sender_id`	`carrier_sms_abuse`
`display_name`	`messaging_platform_abuse`

For a lookalike domain you may also need hosting_provider_abuse — pick the desk that owns the infrastructure the attacker is using. The pack assembles the evidence; it transmits nothing. Supply the screenshots and sample messages you collected through the candidate’s sample_text and source_url fields so they ride along into the stored pack.

5. Work the case

List cases, newest first, optionally filtered to one status:

cURL

curl "https://api.orbit.devotel.io/api/v1/brand-identity/impersonation/cases?status=open" \
  -H "Authorization: Bearer $ORBIT_API_KEY"

Advance or dismiss with PATCH on the case id:

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/brand-identity/impersonation/cases/bpcase_9f2c4a…" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "reported", "note": "Filed with registrar abuse desk."}'

The lifecycle is a state machine; only these transitions are legal:

From	Allowed next statuses
`open`	`evidence_ready`, `dismissed`
`evidence_ready`	`reported`, `dismissed`
`reported`	`resolved`, `dismissed`
`resolved`	— (terminal)
`dismissed`	`open` (reopen)

Setting a case to its current status is an idempotent no-op, so retrying a transition is safe. The dismissal path is always available from any active state for false positives or accepted risk, and a dismissed case can be reopened to open. Every status change is written to your audit log (brand_identity.impersonation_case.status_changed).

6. Operate

Case storage is bounded: the list is pruned down to its cap as cases accumulate, dropping the oldest resolved/dismissed entries first, so active cases stay until everything closed has been trimmed. Case state — like the watchlist — lives under your organization settings (brand_impersonation_cases), tenant-isolated with no schema migration. Errors to handle:

Status	Code	Cause
`400`	validation error	A field over its limit, or an unknown enum value.
`404`	`TAKEDOWN_CASE_NOT_FOUND`	PATCH or GET by an unknown case id.
`409`	`TAKEDOWN_CASE_INVALID_TRANSITION`	A jump the state machine forbids (`open` → `resolved`, or anything out of `resolved`).

Writes (watchlist PUT, case create, case PATCH) need the owner, admin, or developer role; reads also allow viewer.

7. See also

Brand impersonation watchlist, scan & takedown cases — the reference page: detection signals, band thresholds, and the matching rules behind the scores.
Brand identity trust score — the inward-facing identity model: how your registered brand identity builds trust, versus this module’s outward-facing watch for third parties impersonating it.
Brand identity API reference — the endpoint contracts, including the impersonation routes.
Sender ID registration — register the legitimate sender IDs this module protects.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Wire a brand-identity watchlist and run smishing takedown cases

Wire a brand-identity watchlist and run smishing takedown cases

1. What the impersonation monitor is

2. Create the watchlist

3. Score a candidate

4. Assemble a takedown case

5. Work the case

6. Operate

7. See also

​Wire a brand-identity watchlist and run smishing takedown cases

​1. What the impersonation monitor is

​2. Create the watchlist

​3. Score a candidate

​4. Assemble a takedown case

​5. Work the case

​6. Operate

​7. See also

Wire a brand-identity watchlist and run smishing takedown cases

1. What the impersonation monitor is

2. Create the watchlist

3. Score a candidate

4. Assemble a takedown case

5. Work the case

6. Operate

7. See also