How to investigate and close a fraud case

Before you start

UrbanFox creates fraud cases automatically when it detects suspicious activity. When the activity includes an identified account, UrbanFox links the case to an end-user account. This guide shows you how to list, review, update the linked account when needed, and close cases programmatically.

A valid access token (see How to authenticate)
Your tenant_slug, the tenant DNS slug used in the API host and path (for example, demo-retail)
Required scopes: read:cases to list cases, read:case to review a case, update:case to close it, and read:enduseraccount to inspect the linked account; add update:enduseraccount if you need to block, quarantine, or mark the linked account

List open cases

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/cases?status=OPEN' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Narrow by end-user account

If you know which account is under investigation:

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/cases?website_account_id=ACC_123&status=OPEN' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Filter by blocked accounts

List cases only for accounts that are currently blocked:

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/cases?user_is_blocked=true' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Review a specific case

Fetch full details including the risk score:

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/cases/CASE_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

The response includes the linked end-user account when UrbanFox can resolve one:

{
  "data": {
    "case_id": "case-abc123",
    "website_account_id": "account-abc123",
    "end_user_is_blocked": false,
    "status": "OPEN",
    "created_at": "2024-01-15T10:30:00Z",
    "current_state": {
      "case_status": "OPEN",
      "changed_at": "2024-01-15T10:35:00Z",
      "changed_by": "system",
      "reason": "Case created from model prediction",
      "score": 4
    },
    "details": {
      "overall_risk_score": 3,
      "primary_fraud_label": "Bot",
      "summary": "Account takeover attempt detected from suspicious IP",
      "recommended_action": "BLOCK"
    }
  }
}

This example shows only the fields used in this workflow. See the API Reference for the full case response schema.

Use data.details.recommended_action as one signal in the investigation. Copy data.website_account_id before you update account state, and check data.end_user_is_blocked so you know whether the account is already blocked. If website_account_id is UNKNOWN, continue with the case review only; UrbanFox could not resolve a website account identifier for that activity.

Inspect the linked end-user account

Use the case's website_account_id to inspect the current account flags:

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/enduseraccounts/WEBSITE_ACCOUNT_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

{
  "data": {
    "tenant_id": "00000000-0000-4000-8000-000000000000",
    "website_account_id": "account-abc123",
    "crm_account_id": "crm-abc456",
    "is_blocked": false,
    "is_quarantined": false,
    "is_fraudulent": false,
    "last_session_updated_on": "2024-01-15T10:30:00Z"
  }
}

Update the linked account

If the investigation confirms fraud, update only the flags that should change. For example, block the account and mark it as fraudulent:

curl -X PUT 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/enduseraccounts/WEBSITE_ACCOUNT_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "is_blocked": true,
    "is_fraudulent": true
  }'

Use only the account flags that match the investigation outcome. Omit any field you do not want to change.

Close the case

After you resolve the review and confirm any linked account state, update the case status:

curl -X PUT 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/cases/CASE_ID' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "status": "CLOSED" }'

If it's not working

Symptom	Action
`403` on case list or get	Confirm your token has `read:cases` or `read:case` permission
`403` on account get	Confirm your token has `read:enduseraccount` permission
`403` on account update	Confirm your token has `update:enduseraccount` permission
`403` on case update	Confirm your token has `update:case` permission
`404` on account get	Verify the `website_account_id` from the case exists for your tenant
`404` on case update	Verify the case ID exists for your tenant