Check the status of an alert

After you submit an alert, Doppel processes the entity through
its triage workflow. This guide shows how to read an alert's current state from
the API — either for a single alert by id, or in bulk with server-side list
filters.

What you'll do

1. Get an OAuth access token (see Authentication).
2. Look the alert up by id, or filter the alert list.
3. Read the queue_state field on the response.

Get a single alert by id

The id returned from POST /v2/alert is the handle for follow-up status checks. GET /v2/alert requires the id query parameter.

cURL

curl --request GET \
  --url "https://api.doppel.com/v2/alert?id=ACM-1234" \
  --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Python

import requests

response = requests.get(
    "https://api.doppel.com/v2/alert",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"id": "ACM-1234"},
)
response.raise_for_status()
alert = response.json()
print(alert["queue_state"], alert["entity_state"])

Node.js

const url = new URL("https://api.doppel.com/v2/alert");
url.searchParams.set("id", "ACM-1234");

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${access_token}` },
});
const alert = await response.json();
console.log(alert.queue_state, alert.entity_state);

Filter the alert list

To check status across many alerts at once — for example, to see everything waiting on takedown — use GET /v2/alerts with a queue_state filter:

curl --request GET \
  --url "https://api.doppel.com/v2/alerts?queue_state=actioned&page_size=100" \
  --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

response = requests.get(
    "https://api.doppel.com/v2/alerts",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"queue_state": "actioned", "page_size": 100},
)
for alert in response.json()["alerts"]:
    print(alert["id"], alert["entity"], alert["last_activity_timestamp"])

const url = new URL("https://api.doppel.com/v2/alerts");
url.searchParams.set("queue_state", "actioned");
url.searchParams.set("page_size", "100");

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${access_token}` },
});
const { alerts } = await response.json();

queue_state also accepts a comma-separated list. V2 provides four additional
multi-value filters:

Within one parameter, an alert matches if it matches any supplied value. You can
combine parameters to narrow the result set:

curl --request GET \
  --url "https://api.doppel.com/v2/alerts?queue_state=actioned,needs_confirmation&severity=high,medium&platform=domains" \
  --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

GET /v2/alerts is paginated. page is zero-indexed. The default
page_size is 30. The maximum page_size is 200.

Use last_activity_timestamp as the start of a last-activity range. Use
last_activity_before as the end of the range. Both limits are inclusive.

Use sort_type=last_actioned_at to sort by the most recent enforcement action.
Use sort_type=last_activity to sort by the most recent alert activity. You
must also send sort_order=asc or sort_order=desc.

date_last_actioned is a legacy alias for last_activity. Do not use this
alias for a new integration.

Each alert contains a maximum of 100 recent audit log entries by default. Set
audit_log_limit from 0 through 200 to change this limit. Check
audit_logs_truncated to determine if the response does not contain older
entries.

To synchronize or discover alerts without loading snapshots, audit logs, tags,
summaries, or screenshot data, send detail_level=basic. Each alert in a basic
response contains only id, entity, queue_state, entity_state,
severity, product, created_at, and last_activity_timestamp. Omit
detail_level (or send detail_level=full) to receive the standard alert
response.

curl --request GET \
  --url "https://api.doppel.com/v2/alerts?queue_state=actioned&detail_level=basic" \
  --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

The listing response uses last_activity_timestamp. A single-alert response
uses last_activity.

Reading the response

The status of an alert is captured by two fields:

• queue_state — where the alert sits in Doppel's workflow. Per the V2 OpenAPI spec, the value is one of: doppel_review, needs_confirmation, actioned, taken_down, monitoring, archived.
• entity_state — the live state of the entity (URL, phone, etc.) the alert is tracking. Per the V2 OpenAPI spec, the value is one of: active, down, parked, suspicious, unclassified, unrelated, related, unknown.

Two queue_state values map directly to UI actions in Doppel Vision:

• taken_down is shown as Resolved in the Doppel Vision app (per the V2 OpenAPI spec note).
• actioned is the value set when Request Takedown is invoked in the UI (see Request a takedown).

For the semantics of the other values, see the Get Alert entry in the V2 API reference.

Polling pattern

If you poll for status, do it on a backoff and stop once queue_state is taken_down or archived:

import time

TERMINAL_STATES = {"taken_down", "archived"}

def wait_for_resolution(alert_id: str, timeout_seconds: int = 86400) -> dict:
    deadline = time.time() + timeout_seconds
    delay = 60
    while time.time() < deadline:
        response = requests.get(
            "https://api.doppel.com/v2/alert",
            headers={"Authorization": f"Bearer {get_token()}"},
            params={"id": alert_id},
        )
        response.raise_for_status()
        alert = response.json()
        if alert["queue_state"] in TERMINAL_STATES:
            return alert
        time.sleep(delay)
        delay = min(delay * 2, 900)
    raise TimeoutError(f"{alert_id} did not reach a terminal state in time")

Status codes

Next steps

• Request a takedown — set an alert's queue_state to actioned via PUT /v2/alert.
• Submit a new alert — start tracking a new entity.