Revisar Proposal de la organización
Records your organization’s decision on a proposal that is waiting on you — one ChainPatrol escalated to you, or one on a report you submitted yourself. These are exactly the proposals your Review page shows and the ones GET /organization/reports?needsCustomerReview=true counts; find their IDs in proposals[].id on that endpoint. APPROVE blocks the asset and takes a label (plus a brandId for labels that name a specific brand). REJECT takes a rejectReason. WATCHLIST rejects the proposal and parks the asset so it is re-evaluated if it comes back alive.
Pass assetId alongside proposalId; it must match the proposal’s current asset or the request returns 409, which keeps a caller from actioning a proposal it never read.
Approvals are held to the same safety checks as the Review page, with no override: an asset that any enabled legitimacy rule marks as legitimate cannot be approved here, and an allowlisted asset cannot be blocked here. Both return 403 and must be handled on the Review page by a person.
Rate limited to 10 reviews per organization per day, since a review is not undoable and looping over a queue is easy to do by accident. Exceeding it returns 429. The limit is shared across all of the organization’s API credentials and does not apply to reviews made from the Review page.
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 cuentaGET /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.
Inicio rápido
Autenticación
Incluye tu clave de API en el encabezadoX-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 leeproposals[].id y proposals[].asset.id:
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 ennote:
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á
ALLOWEDno se puede bloquear aquí; también devuelve403.
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 devuelve429.
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:Desde la CLI
La ChainPatrol CLI envuelve este endpoint y pide confirmación antes de escribir:--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 elassetId 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
Un403 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
Un409 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
400en lugar de omitir en silencio el envío a la Watchlist. GET /organization/reportsdevuelveproposals[].idjustamente para que las Proposals se puedan referenciar aquí.
Autorizaciones
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
Cuerpo
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.
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.
x > 0What 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.
APPROVE, REJECT, WATCHLIST 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 trademarksEmployee Impersonation— The asset is impersonating a specific employee of the organizationFake Employee— The asset claims to work at the company but is not directly impersonating a specific personTargeting Org Users— A scam the org wants taken down that falls outside direct impersonationGeneral Phishing— This asset is trying to steal user fundsC2 Server— Command and Control server providing backend infrastructure for phishing operationsFalse Positive— This asset was incorrectly flagged and should be allowedOrganization Member Impersonation— The asset is impersonating a member or employee of the organizationTargeting Organization— A scam the org wants taken down that falls outside direct impersonation
Brand Impersonation, Employee Impersonation, Fake Employee, Targeting Org Users, General Phishing, C2 Server, False Positive, Organization Member Impersonation, Targeting Organization 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.
irrelevant, no_malicious_activity, insufficient_evidence, not_targeting_org, decayed 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.
DEAD, PARKING, NOT_ENOUGH_EVIDENCE, OTHER