Submit an alert

This guide walks through submitting a new alert to Doppel for an entity (a URL or phone number) you want investigated. Submitting an alert tells Doppel to triage the entity through its standard workflow and return a handle you can use to follow up.

What you'll do

1. Authenticate (see Authentication).
2. POST /v1/alert with the entity and brand.
3. Capture the alert id from the response so you can check the status or request a takedown later.

Prerequisites

• A V1 API key (see Authentication for the two auth modes — organization-wide or user-specific).
• The exact name of an active brand in your organization. Brand names are case-insensitive but must match an existing, non-archived brand. Use GET /v1/brands to list yours if you're unsure.

The examples below show the organization-wide auth mode (x-api-key only). For the user-specific mode, also send x-user-api-key (and x-organization-code if your user belongs to multiple organizations) — see Authentication.

Submit an alert

cURL

curl --request POST \
  --url "https://api.doppel.com/v1/alert" \
  --header "x-api-key: <YOUR_ORG_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "entity": "https://suspicious-site.example.com",
    "brand": "Acme Corp",
    "tags": ["Credential Theft"]
  }'

Python

import requests

response = requests.post(
    "https://api.doppel.com/v1/alert",
    headers={"x-api-key": "<YOUR_ORG_API_KEY>"},
    json={
        "entity": "https://suspicious-site.example.com",
        "brand": "Acme Corp",
        "tags": ["Credential Theft"],
    },
)
response.raise_for_status()
alert = response.json()
alert_id = alert["id"]

Node.js

const response = await fetch("https://api.doppel.com/v1/alert", {
  method: "POST",
  headers: {
    "x-api-key": "<YOUR_ORG_API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    entity: "https://suspicious-site.example.com",
    brand: "Acme Corp",
    tags: ["Credential Theft"],
  }),
});

if (!response.ok) {
  throw new Error(`Submit failed: ${response.status}`);
}
const alert = await response.json();
const alertId = alert.id;

Request body

Response

A successful submission returns the new alert's identity and a deep link into Doppel Vision:

{
  "id": "ACM-1234",
  "entity": "https://suspicious-site.example.com",
  "doppel_link": "https://app.doppel.com/alerts/ACM-1234",
  "last_activity": "2026-06-15T10:30:00"
}

The id is in the format ORG-NUMBER, where ORG is your organization's abbreviation. Persist this id — it's the handle you'll use to check status or take action on the alert later.

Status codes

Common patterns

Tagging the submission with a custom source

To label submissions from a particular integration, include source. Per the V1 OpenAPI spec, the string must exactly match the API value field of an external source configured under your organization's settings in Doppel Vision (not the display name).

{
  "entity": "https://suspicious-site.example.com",
  "brand": "Acme Corp",
  "source": "slack-integration"
}

Attaching evidence at creation time

Attach files to the alert at creation time:

import base64

with open("evidence.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.doppel.com/v1/alert",
    headers={"x-api-key": "<YOUR_ORG_API_KEY>"},
    json={
        "entity": "https://suspicious-site.example.com",
        "brand": "Acme Corp",
        "files": [{"file_name": "evidence.png", "file_to_upload": encoded}],
    },
)

You can attach up to 10 files per request, each up to 50MB.

Next steps

• Check the status of a submitted alert — read the alert's queue_state and entity_state via GET /v1/alert.
• Request a takedown — set an alert's queue_state to actioned via PUT /v1/alert.