Fraud actions through REST API and MCP

Change how Fraud Detection scores ad clicks and act on the addresses it flags: block an address, remove a block, protect an address with the whitelist or remove it from the whitelist. Every action goes through the same checks as the Fraud Detection page of the admin panel. To read the fraud results, use the fraud:read tools and endpoints of the REST API v1 reference.

Access

Every operation needs the fraud:write scope and a role that may edit the workspace settings; otherwise it answers 403 workspace_read_only. Demo workspaces are read-only.
The scope is opt-in: on the consent page it is an extra box you must tick, and on the personal access token form it starts unticked. Connections and tokens made before it existed do not carry it.
Fraud Detection is included in the Business and Custom plans; on other plans every operation answers 403 plan_required.

Authentication, envelopes, errors and rate limits follow the REST API v1 reference; full schemas are in the OpenAPI document.

The one change AxiTrace makes in an ad account

AxiTrace never edits your campaigns, budgets or ads. The only change it can make in an ad account is the IP exclusion list of Google Ads Auto Exclusion: while Auto Exclusion is on and in live mode, every address you block is added as an IP exclusion in your Google Ads account on the next hourly synchronisation, and removed again when you unblock it. In dry_run mode nothing is sent, and blocks are recorded in AxiTrace only.

Operations

REST	MCP tool	What it does
`PATCH .../fraud/settings`	`update_fraud_settings`	Sensitivity, the ad-click limit, refund claims and Google Ads Auto Exclusion.
`POST .../fraud/blocks`	`block_ip`	Blocks one flagged IPv4 or IPv6 address.
`POST .../fraud/blocks/remove`	`unblock_ip`	Removes the block of one address.
`POST .../fraud/whitelist`	`whitelist_ip`	Protects an address or a range from being flagged or excluded.
`POST .../fraud/whitelist/remove`	`remove_ip_whitelist`	Removes an address or range you whitelisted.

Every REST path starts with /api/v1/workspaces/{workspace_id}.

Settings

Send only the fields to change; scores are recalculated on the next hourly analysis. The answer has the fraud section before and after, as GET .../settings?section=fraud returns it.

Field	Meaning
`sensitivity`	`conservative`, `balanced` or `aggressive`.
`click_limit_enabled`, `click_limit_without_cart`, `click_limit_with_cart`	The number of Google Ads clicks in 30 days without an order after which the addresses of a visitor are blocked, without and with an add to cart.
`refund_claims_enabled`, `refund_claims_min_clicks`, `refund_claims_min_cost`	When an invalid click refund claim is prepared: at least this many clicks (1 to 10,000) and this cost (an amount such as `25.00`).
`auto_exclusion`, `auto_exclusion_mode`	Send blocked addresses to Google Ads as IP exclusions; mode `dry_run` or `live`.
`confirmed`	Required to switch Auto Exclusion on: send `true` only after the merchant agreed that blocked addresses are sent to their Google Ads account.

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://axitrace.com/api/v1/workspaces/$WORKSPACE/fraud/settings" \
  -d '{"sensitivity": "balanced", "click_limit_enabled": true, "click_limit_without_cart": 5}'

Blocking and whitelisting addresses

Every address operation takes {"ip": "..."}; the whitelist also takes an optional note (at most 255 characters). The answer gives the address masked to its network (IPv4 /24, IPv6 /48), the result (blocked, unblocked, whitelisted or removed_from_whitelist), the Auto Exclusion state and any warnings, for example that a block is recorded in AxiTrace only because Auto Exclusion is off.

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://axitrace.com/api/v1/workspaces/$WORKSPACE/fraud/blocks" \
  -d '{"ip": "203.0.113.24"}'

{
  "data": {
    "workspace_id": "7a2b3c4d-0000-4000-8000-000000000011",
    "result": "blocked",
    "address_masked": "203.0.113.0/24",
    "auto_exclusion_enabled": true,
    "auto_exclusion_mode": "live",
    "warnings": []
  }
}

Block: the address must be on the list of flagged addresses (list_fraud_verdicts). Verified crawlers, addresses the bot filter already stops, shared networks, buying customers, your team and whitelisted addresses are refused with 422 validation_failed.
Unblock: an exclusion AxiTrace added in Google Ads is removed on the next synchronisation.
Whitelist: one IPv4 address, an IPv6 address (protected as its /64 network) or a range ending in .* such as 203.0.113.*. An active block of the address is removed.
Remove from the whitelist: the address is scored again from the next analysis. Automatic protections (buying customers, your team) cannot be removed.

Errors

403 insufficient_scope: the token does not carry fraud:write.
403 plan_required: the plan does not include Fraud Detection.
403 workspace_read_only: the role may not edit the workspace settings, or the workspace is a demo.
422 validation_failed: the address or a field is refused; nothing was changed.