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 by filtering the alert list.

What you'll do

Get an OAuth access token (see Authentication).
Look the alert up by id, or list alerts filtered by queue_state.
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);

List alerts by queue state

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();

GET /v2/alerts is paginated (page is zero-indexed; default page_size is 30, max 200). Note that the listing response uses last_activity_timestamp, while 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

Status	Meaning
`200 OK`	Alert (or alert list) returned successfully.
`401 Unauthorized`	Invalid or missing JWT — refresh your access token.
`403 Forbidden`	The alert does not belong to your organization, or your token is not mapped to an organization.
`404 Not Found`	No alert in your organization matches the supplied `id`. (Single-alert endpoint only.)
`429 Too Many Requests`	Rate limit exceeded — see the `Retry-After` header.

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.