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

Get an OAuth access token (see Authentication).
POST /v2/alert with the entity and brand.
Capture the alert id from the response so you can check the status or request a takedown later.

Prerequisites

A valid access token (see Authentication).
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 /v2/brands to list yours if you're unsure.

Submit an alert

cURL

curl --request POST \
  --url "https://api.doppel.com/v2/alert" \
  --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  --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/v2/alert",
    headers={"Authorization": f"Bearer {access_token}"},
    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/v2/alert", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "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

Field	Type	Required	Description
`entity`	string	Yes	The URL or phone number to alert on.
`brand`	string	No	Name of the brand to associate with the alert. Must match an active (non-archived) brand in your organization. Case-insensitive.
`tags`	string[]	No	Tag names to apply at creation. Tags must already exist for your organization (or be global tags); unknown tags are silently ignored.
`source`	string	No	Custom API source identifier. Must exactly match the API value field of an external source configured under your organization's settings in Doppel Vision.
`files`	object[]	No	Up to 10 files to attach as evidence. Each entry is `{ "file_name": "...", "file_to_upload": "<base64>" }`. Maximum 50MB per file.

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

Status	Meaning
`201 Created`	New alert was created.
`200 OK`	An alert for this `entity` already exists in your organization. The existing alert is returned.
`400 Bad Request`	`entity` is missing, malformed, or refers to a protected asset (e.g. one of your own domains).
`404 Not Found`	The `brand` name does not match any active brand in your organization.
`409 Conflict`	An alert exists for this `entity` but is associated with a different brand. The response includes a `message` field explaining the conflict.

Common patterns

Tagging the submission with a custom source

To label submissions from a particular integration, include source. Per the V2 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/v2/alert",
    headers={"Authorization": f"Bearer {access_token}"},
    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 /v2/alert.
Request a takedown — set an alert's queue_state to actioned via PUT /v2/alert.