Saltar al contenido principal
POST
Review an organization proposal

Descripción general

Registra la decisión de tu organización sobre una Proposal (propuesta para bloquear o permitir un asset) que está esperando por ti: una que ChainPatrol te escaló o una de un reporte que tú mismo enviaste. Son exactamente las Proposals que muestra tu página Review (revisión de propuestas pendientes de aprobación) y las que cuenta GET /organization/reports?needsCustomerReview=true, así que este endpoint te permite vaciar esa cola sin abrir la app web. Hay un solo endpoint para los tres resultados posibles, que se distinguen por decision: WATCHLIST es una variante del rechazo y no un resultado aparte: se guarda como una revisión REJECT con el asset agregado a la Watchlist, que es la misma escritura que hace la página Review. Por eso una respuesta exitosa de Watchlist vuelve con review.decision: "REJECT" y watchlisted: true.
Una revisión no se puede deshacer a través de la API. APPROVE bloquea el asset y, como los assets son únicos por tipo y contenido, ese estado es global y no se limita a tu organización. Lee la Proposal antes de actuar sobre ella y usa el límite de revisiones como un resguardo, no como una meta.

Inicio rápido

Autenticación

Incluye tu clave de API en el encabezado X-API-KEY:

Cómo encontrar una Proposal para revisar

Los dos ID que necesita este endpoint salen del listado de reportes. Pide las Proposals que están esperando por ti y luego lee proposals[].id y proposals[].asset.id:
cURL

Solicitud de ejemplo

Cuerpo de la solicitud

proposalId es un parámetro de ruta, así que no se repite en el cuerpo.

Por qué assetId es obligatorio

assetId es un valor de confirmación, no una búsqueda. El servidor lo compara con el asset actual de la Proposal y devuelve 409 si no coinciden, lo que significa que un proposalId desactualizado o mal escrito falla de forma visible en lugar de revisar un asset distinto del que leíste. Toma ambos valores de la misma respuesta del listado y pásalos juntos.

Etiquetas de bloqueo

label es obligatorio al aprobar y se ignora en los demás casos. Brand Impersonation y Employee Impersonation también requieren brandId.

Motivos de rechazo

Los motivos de rechazo alimentan el desglose que ChainPatrol usa para ajustar la detección, así que elige el más cercano en lugar de poner el motivo real en note:

Respuesta

Respuesta exitosa

Respuesta de Watchlist

Una solicitud de Watchlist se registra como un rechazo con el asset en la Watchlist:

Campos de la respuesta

Controles de seguridad

Aprobar a través de la API está sujeto a los mismos controles que la página Review y, a diferencia de la interfaz, no se pueden anular:
  • Reglas de legitimidad. Si alguna regla de legitimidad habilitada concluyó que el asset parece legítimo (un dominio incluido en la lista Tranco, una coincidencia de regex con un dominio que te pertenece), la aprobación devuelve 403. Esa decisión la tiene que tomar una persona en la página Review.
  • Assets en la Allowlist (lista de permitidos). Un asset que actualmente está ALLOWED no se puede bloquear aquí; también devuelve 403.
Ambos son callejones sin salida deliberados y no advertencias. Cuando te encuentres con uno, revisa la Proposal en la app.

Límite de revisiones

Las revisiones están limitadas a 10 por organización por cada período móvil de 24 horas. El cupo se comparte entre todas las credenciales de API que tiene tu organización, y las revisiones hechas desde la página Review no cuentan para ese cupo. Si lo superas, se devuelve 429. El límite existe porque una revisión no se puede deshacer y es fácil recorrer una cola en bucle por accidente. Trátalo como un resguardo: si lo alcanzas con frecuencia, conviene vaciar la cola en la app.

Respuestas de error

400 Bad Request

No se cumplió un requisito condicional, o el tipo de asset no se puede enviar a la Watchlist:

403 Forbidden

La credencial no corresponde a un miembro de la organización con rol de cliente, o un control de seguridad rechazó la escritura:

404 Not Found

La Proposal no existe o no es una de las tuyas:

409 Conflict

assetId no coincide con el asset actual de la Proposal, o la Proposal ya fue resuelta:

429 Too Many Requests

Se agotó el cupo diario de revisiones de la organización:

Casos de uso

Vaciar la cola que está esperando por ti

Lee las Proposals que están esperando por tu organización y luego actúa sobre cada una:

Dejar en la Watchlist un asset que quedó inactivo

Un asset que está inactivo o estacionado (con una página de parking) no es un falso positivo: envíalo a la Watchlist para que ChainPatrol lo vuelva a evaluar si vuelve a estar activo:
cURL

Desde la CLI

La ChainPatrol CLI envuelve este endpoint y pide confirmación antes de escribir:
Pasa --yes para omitir la confirmación en un script, o --dry-run para imprimir el payload sin enviarlo. Consulta proposals review para ver todas las opciones.

Buenas prácticas

Lee antes de escribir

Cada solicitud necesita el assetId de un listado que acabas de leer, y eso es deliberado. Obtén la Proposal, decide a partir de su asset y de los datos de su escaneo, y solo entonces revísala: no inventes ID ni reutilices un listado viejo.

Trata el 403 como una derivación, no como una falla

Un 403 de un control de seguridad significa que la decisión necesita a una persona, no que tu integración esté rota. Registra el ID de la Proposal y sigue adelante; no reintentes.

No reintentes un 409

Un 409 significa que el asset no coincide o que la Proposal ya está resuelta. Vuelve a leer la Proposal en lugar de reintentar con el mismo cuerpo.

Notas

  • Las revisiones deben atribuirse a un miembro de la organización con rol de cliente. Las credenciales de staff se rechazan con 403.
  • El estado del asset es global: los assets son únicos por tipo y contenido, así que aprobar bloquea el asset en todas partes y no solo para tu organización.
  • No todos los tipos de asset se pueden enviar a la Watchlist. Los tipos que la Watchlist no puede volver a verificar se rechazan con 400 en lugar de omitir en silencio el envío a la Watchlist.
  • GET /organization/reports devuelve proposals[].id justamente para que las Proposals se puedan referenciar aquí.

Autorizaciones

X-API-KEY
string
header
requerido

Your API key. This is required by most endpoints to access our API programatically. Reach out to us at support@chainpatrol.io to get an API key for your use.

Parámetros de ruta

proposalId
integer
requerido

ID of the proposal to review. Read it from proposals[].id on GET /organization/reports.

Rango requerido: x > 0

Cuerpo

application/json

Review a proposal on your organization's behalf

Records your organization's decision on a proposal ChainPatrol escalated to you and you have not answered yet. These are exactly the proposals your Review page shows, and the ones counted by GET /organization/reports?needsCustomerReview=true.

Proposals on reports your organization sourced itself are not reviewable here: ChainPatrol triages those and staff approval blocks the asset on its own, so there is no decision for you to record. They return 403.

assetId
integer
requerido

ID of the asset this proposal is for, from proposals[].asset.id on GET /organization/reports. Required, and must match the proposal's current asset — a mismatch returns 409. This proves the request was built from a proposal you actually read, rather than from a guessed or stale ID.

Rango requerido: x > 0
decision
enum<string>
requerido

What to do with the proposal. APPROVE blocks the asset, REJECT declines it, and WATCHLIST declines it but parks the asset so it is re-evaluated if it comes back alive. WATCHLIST is recorded as a rejection with the asset watchlisted — the same write the Review page performs.

Opciones disponibles:
APPROVE,
REJECT,
WATCHLIST
slug
string

Organization slug. Optional for organization-scoped API keys, which resolve the organization from the key itself. Required when your credentials can reach more than one organization.

label
enum<string>

Why the asset is being blocked. Required when decision is APPROVE, ignored otherwise. One of: Brand Impersonation, Employee Impersonation, Fake Employee, Targeting Org Users, General Phishing, C2 Server, False Positive, Organization Member Impersonation, Targeting Organization.

  • Brand Impersonation — The asset is directly using the Brand's name, logo, or other trademarks
  • Employee Impersonation — The asset is impersonating a specific employee of the organization
  • Fake Employee — The asset claims to work at the company but is not directly impersonating a specific person
  • Targeting Org Users — A scam the org wants taken down that falls outside direct impersonation
  • General Phishing — This asset is trying to steal user funds
  • C2 Server — Command and Control server providing backend infrastructure for phishing operations
  • False Positive — This asset was incorrectly flagged and should be allowed
  • Organization Member Impersonation — The asset is impersonating a member or employee of the organization
  • Targeting Organization — A scam the org wants taken down that falls outside direct impersonation
Opciones disponibles:
Brand Impersonation,
Employee Impersonation,
Fake Employee,
Targeting Org Users,
General Phishing,
C2 Server,
False Positive,
Organization Member Impersonation,
Targeting Organization
brandId
integer

Brand the asset impersonates. Optional for most labels, but required for Brand Impersonation and Employee Impersonation, which name a specific impersonation target. List your brands with GET /organization/brands.

Rango requerido: x > 0
rejectReason
enum<string>

Why the proposal is being rejected. Required when decision is REJECT, ignored otherwise. These are the same reasons the Review page offers, and they feed ChainPatrol's detection-tuning breakdown — pick the closest one rather than relying on note.

Opciones disponibles:
irrelevant,
no_malicious_activity,
insufficient_evidence,
not_targeting_org,
decayed
watchlistReason
enum<string>

Why the asset is being parked. Required when decision is WATCHLIST, ignored otherwise. Use OTHER for anything not covered, in which case note becomes required and is treated as the reason. Note that the watchlist only covers asset types that can be re-checked for revival (URL, PAGE, EMAIL, and the social platforms); watchlisting any other type is rejected, so reject the proposal instead.

Opciones disponibles:
DEAD,
PARKING,
NOT_ENOUGH_EVIDENCE,
OTHER
note
string

Free-text detail recorded on the review, alongside the structured reason. Required when watchlistReason is OTHER.

Maximum string length: 1000

Respuesta

Successful response

Successful operation

proposal
object
requerido

The reviewed proposal

review
object
requerido

The review that was created

watchlisted
boolean
requerido

Whether the asset was added to the watchlist as part of this review